API bulk memungkinkan Anda menambahkan, memperbarui, atau menghapus beberapa dokumen dalam satu permintaan. Mengelompokkan operasi mengurangi jumlah round trip dan meningkatkan throughput—kirim beberapa operasi sekaligus bila memungkinkan.
Prasyarat
Sebelum memulai, pastikan Anda telah memiliki:
Aplikasi OpenSearch
Kredensial untuk menandatangani permintaan API. Untuk detail penandatanganan, lihat Signature method of OpenSearch API V3.
Unggah dokumen
Endpoint
POST /v3/openapi/apps/<app_name>/<table_name>/actions/bulk| Placeholder | Description |
|---|---|
<app_name> | Nama aplikasi Anda |
<table_name> | Nama tabel yang menerima data |
Endpoint ini tidak mencantumkan host, header permintaan, dan detail encoding. Untuk format permintaan lengkap, lihat Signature method of OpenSearch API V3.
Format permintaan: JSON
Metode HTTP: POST
Badan permintaan
Badan permintaan berupa array JSON. Setiap elemen merepresentasikan satu operasi dokumen dan berisi bidang-bidang berikut.
cmd (wajib)
Operasi yang akan dilakukan. Nilai yang valid: add, update, delete.
updatetidak didukung untuk aplikasi standar. Gunakanaddsebagai gantinya.
add
Membuat dokumen. Jika dokumen dengan primary key yang sama sudah ada, OpenSearch akan menghapus dokumen asli sebelum membuat yang baru.
{
"cmd": "add",
"fields": {
"id": "1",
"title": "This is the title",
"body": "This is the body"
}
}update
Memperbarui bidang tertentu dalam dokumen yang sudah ada. Hanya bidang yang Anda sertakan dalam permintaan yang akan dimodifikasi.
{
"cmd": "update",
"fields": {
"id": "2",
"title": "This is the new title"
}
}delete
Menghapus dokumen dengan primary key yang ditentukan. Jika tidak ada dokumen dengan primary key tersebut, operasi delete tetap dijalankan.
{
"cmd": "delete",
"fields": {
"id": "3"
}
}fields (wajib)
Bidang dokumen yang akan dioperasikan. Selalu sertakan bidang primary key—OpenSearch menggunakannya untuk mengidentifikasi dokumen.
Untuk operasi delete, hanya bidang primary key yang diperlukan.
Untuk bidang bertipe ARRAY, tentukan nilainya sebagai array JSON:
[
{
"cmd": "add",
"fields": {
"id": "0",
"int_array": [14, 85],
"string_array": ["abc", "xyz"]
}
}
]timestamp (opsional, hanya untuk aplikasi advanced)
Waktu pelaksanaan operasi, dalam milidetik. OpenSearch menggunakan nilai ini untuk menentukan urutan operasi pada primary key yang sama.
Jika tidak disertakan, OpenSearch menggunakan waktu saat permintaan diterima.
Aplikasi standar tidak mendukungtimestamp. Jika Anda menyertakannya dalam permintaan ke aplikasi standar, OpenSearch akan mengembalikan kode kesalahan4007.
Contoh permintaan
Contoh berikut mengelompokkan tiga operasi—add, update, dan delete—dalam satu permintaan. Semua contoh menggunakan format array JSON pada level terluar.
POST http://<host>/v3/openapi/apps/app_schema_demo/tab/actions/bulkBadan permintaan:
[
{
"cmd": "add",
"timestamp": 1401342874777,
"fields": {
"id": "1",
"title": "This is the title",
"body": "This is the body"
}
},
{
"cmd": "update",
"timestamp": 1401342874778,
"fields": {
"id": "2",
"title": "This is the new title"
}
},
{
"cmd": "delete",
"fields": {
"id": "3"
}
}
]Respons
Periksa bidang status terlebih dahulu. Jika status bernilai FAIL, periksa errors untuk detailnya.
| Parameter | Tipe | Deskripsi |
|---|---|---|
status | STRING | OK jika permintaan berhasil diterima; FAIL jika permintaan gagal |
result | STRING | true untuk permintaan yang berhasil; tidak dikembalikan untuk permintaan yang gagal |
request_id | STRING | ID permintaan unik untuk troubleshooting |
errors | STRING | Detail kesalahan. Setiap kesalahan mencakup: code (kode kesalahan), message (deskripsi kesalahan), dan params (parameter tambahan). Lihat Error codes |
Respons sukses
{
"errors": [],
"request_id": "150116724719940316170289",
"status": "OK",
"result": true
}Respons kesalahan
{
"errors": [
{
"code": 2001,
"message": "The application to be managed does not exist. The application to be managed does not exist.",
"params": {
"friendly_message": "The application to be managed does not exist."
}
}
],
"request_id": "150116732819940316116461",
"status": "FAIL"
}Catatan penggunaan
Periksa nilai kembali setelah setiap permintaan.
statusbernilaiOKberarti Pencarian Terbuka telah menerima data—bukan berarti data tersebut berhasil diproses. Pencarian Terbuka memproses data secara asinkron. Jika terjadi kesalahan pemrosesan, pesan kesalahan akan muncul di konsol Pencarian Terbuka. Periksa konsol secara berkala, dan berikan perhatian khusus pada kode kesalahan3007.Batas ukuran permintaan: Badan permintaan tidak boleh melebihi 2 MB sebelum encoding. Permintaan yang melebihi batas ini akan ditolak. Anda dapat mendorong data dalam jumlah dan ukuran terbatas dengan memanggil Operasi API atau menggunakan SDK OpenSearch. Untuk batas frekuensi dan volume dorong berdasarkan jenis aplikasi, lihat Limits.
Encoding UTF-8 untuk karakter Tionghoa: Jika badan permintaan berisi karakter Tionghoa, encode badan tersebut dalam UTF-8. Nilai header
Content-MD5juga harus dihitung dari badan yang telah diencode UTF-8.