ドキュメントのアップロード
必要に応じて、APIオペレーションを呼び出して、1つまたは複数のドキュメントを作成、更新、および削除できます。
URL
/v3/openapi/apps/$app_name/$table_name/actions/bulk$app_nameは、管理するアプリケーションの名前に置き換えます。
$table_nameは、アプリケーションでデータを受信するために使用するテーブルの名前に置き換えます。
サンプルURLには、リクエストヘッダーやエンコード方式などの情報は含まれていません。
サンプルURLには、OpenSearchへの接続に使用するエンドポイントも含まれていません。
サポートされている形式
JSON
HTTPリクエストメソッド
POST
リクエストパラメーター
データプッシュのリクエストの署名文字列の計算方法とヘッダーの指定方法については、OpenSearch API V3の署名方式を参照してください。
データ処理のコマンド構文
注記
標準アプリケーションはtimestampパラメーターをサポートしていません。リクエストでtimestampパラメーターを指定すると、エラーコード4007が返されます。
次のサンプルコードは、高度なアプリケーションのデータを処理する方法の例を示しています。
[
{
"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"
}
}
]timestamp: オプション。ドキュメントに対して操作が実行されたときのタイムスタンプ。単位：ミリ秒。OpenSearchは、タイムスタンプを使用して、特定のプライマリキー値を持つドキュメントが管理されるシーケンスを識別します。このパラメーターは、高度なアプリケーションでのみサポートされています。標準アプリケーションを使用している場合は、このパラメーターを指定できません。指定すると、エラーコード4007が返されます。デフォルトでは、このパラメーターが指定されていない場合、OpenSearchは、OpenSearchがドキュメントを受信した時刻をタイムスタンプとして使用して、ドキュメントに対する操作を実行します。
cmd: 必須。ドキュメントに対して実行される操作。有効な値：add、update、delete。update値は、標準アプリケーションではサポートされていません。一度に複数の操作を実行するリクエストを送信することをお勧めします。これにより、ネットワーク上でのインタラクション効率と処理効率が向上します。add値は、ドキュメントを作成することを指定します。指定されたプライマリキー値を持つドキュメントが既に存在する場合は、新しいドキュメントが作成される前に元のドキュメントが削除されます。update値は、ドキュメント内の指定されたフィールドを更新することを指定します。delete値は、ドキュメントを削除することを指定します。指定されたプライマリキー値を持つドキュメントが存在しない場合、ドキュメントは削除されます。
fields: 必須。ドキュメント内で操作が実行されるフィールド。プライマリキーフィールドを指定する必要があります。OpenSearchは、プライマリキー値に基づいてドキュメントを識別します。ドキュメントを削除する場合は、ドキュメントのプライマリキーフィールドのみを指定する必要があります。
ARRAYタイプのフィールドを指定するには、JSON配列の形式で指定する必要があります。例：
{"fields": { "id": "0","int_array": [14,85],"string_array": ["abc","xyz"]},"cmd": "ADD"}]。サンプルコードでは、最外層は一度に複数のドキュメントを管理するために使用されるJSON配列です。
レスポンスパラメーター
パラメーター | タイプ | 説明 |
errors | ARRAY | エラー情報。messageパラメーターはエラーメッセージ、paramsパラメーターはエラーパラメーター、codeパラメーターはエラーコードを示します。エラーコードの詳細については、エラーコードを参照してください。 |
request_id | STRING | リクエストのID。トラブルシューティングに使用されます。 |
status | STRING | リクエストの実行結果。有効な値：OKとFAIL。OK値は、リクエストが成功したことを示します。FAIL値は、リクエストが失敗したことを示します。この場合は、エラーコードに基づいてエラーのトラブルシューティングを行ってください。 |
result | STRING | リクエストの結果。リクエストが成功した場合、true値が返されます。リクエストが失敗した場合は、このパラメーターは返されません。 |
例
データ処理のAPIリクエストの例。リクエストヘッダーのパラメーターやエンコード方式などの情報は省略されています。
http://host/v3/openapi/apps/app_schema_demo/tab/actions/bulk
// アップロードするドキュメント。リクエストボディに配置する必要があります。
[{"cmd":"ADD","fields":{"id":1,"name":"Test Data Push"}}]成功レスポンスの例
{
"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"
}使用上の注意
APIオペレーションの呼び出しまたはOpenSearch SDKの使用によってデータをプッシュする場合、アプリケーションのフィールド名では大文字と小文字は区別されません。
APIオペレーションの呼び出しまたはOpenSearch SDKの使用によってプッシュできるデータの回数とサイズには制限があります。アプリケーションごとに異なる制限が課されます。詳細については、制限を参照してください。
データのアップロードリクエストを送信した後、戻り値を確認する必要があります。エラーコードが返された場合は、エラーコードに基づいてエラーのトラブルシューティングを行い、データの損失を防ぎます。特にエラーコード3007に注意してください。OpenSearchはデータを非同期的に処理します。戻り値OKは、OpenSearchがデータを受信したことを示します。これは、データが正しく処理されたことを示すものではありません。データ処理中にエラーが発生した場合、関連するエラーメッセージがOpenSearchコンソールに表示されます。できるだけ早くエラーメッセージを確認してください。
HTTP POSTリクエストを送信するときにアップロードできるデータのサイズには制限があります。エンコード前のデータサイズが2 MBを超える場合、OpenSearchはリクエストを拒否し、エラーを返します。
データプッシュへのHTTP POSTリクエストの本文に中国語の文字が含まれている場合は、本文をUTF-8でエンコードする必要があります。さらに、Content-MD5ヘッダーの値も、MD5値を計算する前にUTF-8でエンコードする必要があります。そうしないと、エラーが返され、リクエストが失敗します。