バルク API を使用すると、単一のリクエストで複数のドキュメントを追加、更新、または削除できます。操作のバッチ処理により、ラウンドトリップが削減され、スループットが向上します。可能な限り複数の操作をまとめて送信してください。
前提条件
開始する前に、以下があることを確認してください。
OpenSearch アプリケーション
API リクエストに署名するための認証情報。署名の詳細については、「OpenSearch API V3 の署名メソッド」をご参照ください。
ドキュメントのアップロード
エンドポイント
POST /v3/openapi/apps/<app_name>/<table_name>/actions/bulk| プレースホルダー | 説明 |
|---|---|
<app_name> | アプリケーションの名前 |
<table_name> | データを受信するテーブル名 |
エンドポイントには、ホスト、リクエストヘッダー、およびエンコーディングの詳細が省略されます。完全なリクエストフォーマットについては、「OpenSearch API V3 の署名方式」をご参照ください。
リクエスト形式:JSON
HTTP メソッド:POST
リクエストボディ
リクエストボディは JSON 配列です。各要素は 1 つのドキュメント操作を表し、次のフィールドが含まれます。
cmd (必須)
実行する操作。有効な値:add、update、delete。
updateは標準アプリケーションではサポートされていません。代わりにaddを使用してください。
add
ドキュメントを作成します。同じプライマリキーを持つドキュメントがすでに存在する場合、OpenSearch は新しいドキュメントを作成する前に元のドキュメントを削除します。
{
"cmd": "add",
"fields": {
"id": "1",
"title": "This is the title",
"body": "This is the body"
}
}update
既存のドキュメントの指定されたフィールドを更新します。リクエストに含めたフィールドのみが変更されます。
{
"cmd": "update",
"fields": {
"id": "2",
"title": "This is the new title"
}
}delete
指定されたプライマリキーを持つドキュメントを削除します。そのプライマリキーを持つドキュメントが存在しない場合でも、削除操作は実行されます。
{
"cmd": "delete",
"fields": {
"id": "3"
}
}fields (必須)
操作対象のドキュメントフィールド。OpenSearch がドキュメントを識別するために使用するため、常にプライマリキーフィールドを含めてください。
delete 操作の場合、プライマリキーフィールドのみが必須です。
ARRAY 型のフィールドの場合、値を JSON 配列として指定します。
[
{
"cmd": "add",
"fields": {
"id": "0",
"int_array": [14, 85],
"string_array": ["abc", "xyz"]
}
}
]timestamp (オプション、高度なアプリケーションのみ)
操作が実行された時刻(ミリ秒単位)。OpenSearch はこれを使用して、同じプライマリキーに対する操作の順序を決定します。
省略された場合、OpenSearch はリクエストを受信した時刻を使用します。
標準アプリケーションはtimestampをサポートしていません。標準アプリケーションへのリクエストにこれを含めると、OpenSearch はエラーコード4007を返します。
リクエスト例
次の例では、add、update、delete の 3 つの操作を単一のリクエストでバッチ処理します。すべての例は、最上位レベルで JSON 配列形式を使用します。
POST http://<host>/v3/openapi/apps/app_schema_demo/tab/actions/bulkリクエストボディ:
[
{
"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"
}
}
]レスポンス
まず status フィールドを確認してください。status が FAIL の場合、errors で詳細を確認してください。
| パラメーター | 型 | 説明 |
|---|---|---|
status | STRING | OK はリクエストの受信に成功した場合、FAIL はリクエストが失敗した場合です。 |
result | STRING | true、失敗したリクエストの場合は返されません |
request_id | STRING | トラブルシューティング用の一意のリクエスト ID |
errors | STRING | エラーの詳細。各エラーには、code (エラーコード)、message (エラーの説明)、および params (追加パラメーター) が含まれます。「エラーコード |
成功レスポンス
{
"errors": [],
"request_id": "150116724719940316170289",
"status": "OK",
"result": true
}エラーレスポンス
{
"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"
}注意事項
各リクエストの後に戻り値を確認してください。
statusがOKであることは、OpenSearch がデータを受信したことを意味し、正常に処理されたことを意味するものではありません。OpenSearch はデータを非同期で処理します。処理エラーが発生した場合、エラーメッセージは OpenSearch コンソールに表示されます。定期的にコンソールを確認し、特にエラーコード3007に注意してください。リクエストサイズ制限:リクエストボディは、エンコーディング前に 2 MB を超えてはなりません。この制限を超えるリクエストは拒否されます。API オペレーションを呼び出すか、OpenSearch SDK を使用して、限られた回数および限られたサイズのデータをプッシュできます。アプリケーションタイプごとのプッシュ頻度とボリューム制限については、「使用制限」をご参照ください。
中国語文字の UTF-8 エンコーディング:リクエストボディに中国語文字が含まれる場合、ボディを UTF-8 でエンコードしてください。
Content-MD5ヘッダー値も UTF-8 でエンコードされたボディから計算する必要があります。