Amazon CloudSearch
開発者ガイド (API バージョン 2013-01-01)

documents/batch

このセクションでは、documents/batch リソースの HTTP リクエストおよび応答メッセージについて説明します。

Amazon CloudSearch ドメインにアップロードするデータを記述するためのドキュメントバッチを作成します。ドキュメントバッチは追加および削除操作のコレクションであり、ドメインで追加、更新、削除するドキュメントを表します。バッチは JSON または XML で記述できます。バッチは、インデックス作成のために Amazon CloudSearch で必要になるすべての情報を提供します。検索結果として返すことができるようにする各項目 (製品など) はドキュメントとして表されます—バッチは単に個々のドキュメントの追加および削除リクエストのコレクションです。各ドキュメントには固有の ID、および検索し、結果を返すデータを含むフィールドが 1 つ以上あります。

ドキュメントを更新するには、更新するドキュメントのドキュメント ID を使用して追加リクエストを指定します。詳細については、「Amazon CloudSearch でのドキュメントの追加および更新」を参照してください。同様に、ドキュメントを削除するには、削除するドキュメントのドキュメント ID を使用して削除リクエストを送信します。ドキュメントの削除の詳細については、「Amazon CloudSearch でのドキュメントの削除」を参照してください。

インデックス作成用のデータ送信の詳細については、「ドキュメントをアップロードする」を参照してください。

documents/batch JSON API

JSON documents/batch リクエスト

documents/batch リクエストの本文では、JSON または XML を使用して、実行するドキュメントのオペレーションを指定します。バッチの JSON 表現は、個々の追加および削除オペレーションを定義するオブジェクトのコレクションです。type プロパティは、オブジェクトが追加オペレーションと削除オペレーションのどちらを表すかを示します。たとえば、次の JSON バッチは、1 個のドキュメントを追加し、1 個のドキュメントを削除します。

[ { "type": "add", "id": "tt0484562", "fields": { "title": "The Seeker: The Dark Is Rising", "directors": ["Cunningham, David L."], "genres": ["Adventure","Drama","Fantasy","Thriller"], "actors": ["McShane, Ian","Eccleston, Christopher","Conroy, Frances", "Crewson, Wendy","Ludwig, Alexander","Cosmo, James", "Warner, Amelia","Hickey, John Benjamin","Piddock, Jim", "Lockhart, Emma"] } }, { "type": "delete", "id": "tt0484575" }]

注記

ドキュメントバッチを JSON で指定する場合、フィールドの値を null にすることはできません。

バッチの JSON スキーマ表現を次に示します。

{ "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["add", "delete"], "required": true }, "id": { "type": "string", "pattern": "[a-z0-9][a-z0-9_]{0,127}", "minLength": 1, "maxLength": 128, "required": true }, "fields": { "type": "object", "patternProperties": { "[a-zA-Z0-9][a-zA-Z0-9_]{0,63}": { "type": "string", } } } } } }

documents/batch リクエストのプロパティ (JSON)

プロパティ 説明 必須
type オペレーションのタイプ。add または delete はい
id 英数字の文字列。使用できる文字は、A ~ Z(大文字)、a ~ z(小文字)、0 ~ 9、_(下線)、-(ハイフン)、/(スラッシュ)、#(ハッシュ記号)、:(コロン)です。最大長は 128 文字です。 はい
fields ドキュメントに含まれるフィールドを定義する、1 つ以上の field_name プロパティのコレクション。

条件: 追加オペレーションの場合に必要です。少なくとも 1 個の field_name プロパティを含める必要があります。

条件付き
field_name 追加されるドキュメント内のフィールドを指定します。フィールド名は英数字で始まっている必要があり、次の文字を含めることができます。a​~​z(小文字)、0​~​9、_(下線)。フィールド名は、3 ~ 64 文字以内にする必要があります。score という名前は予約済みのため、フィールド名として使用できません。

フィールドに複数の値を指定するには、1 つの値の代わりに値の配列を指定します。(例:

"genre": ["Adventure","Drama","Fantasy","Thriller"]

条件: fields オブジェクトで少なくとも 1 個のフィールドを指定する必要があります。

条件付き

documents/batch 応答(JSON)

応答の本文には、実行された追加や削除の数、および生成されたすべてのエラーや警告がリストされます。

ドキュメントサービス API 応答の JSON スキーマの表現を次に示します。

{ "type": "object", "properties": { "status": { "type": "text", "enum": ["success", "error"], "required": true }, "adds": { "type": "integer", "minimum": 0, "required": true }, "deletes": { "type": "integer", "minimum": 0, "required": true }, "errors": { "type": "array", "required": false, "items": { "type": "object", "properties": { "message": { "type": "string", "required": true } } } }, "warnings": { "type": "array", "required": false, "items": { "type": "object", "properties": { "message": { "type": "string", "required": true } } } } } }

documents/batch 応答のプロパティ(JSON)

プロパティ 説明
status success または error である結果のステータス。
adds 実行されたドキュメントの追加オペレーションの数。ステータスが error であるときは常に 0。
deletes 実行されたドキュメントの削除オペレーションの数。ステータスが error であるときは常に 0。ドキュメントの完全な削除の詳細については、「Amazon CloudSearch でのドキュメントの削除」を参照してください。
エラー 解析エラーまたは検証エラーに関する情報を提供します。ステータスが error である場合にのみ指定されます。
warning 解析時または検証時に生成された警告に関する情報を提供します。

documents/batch ステータスコード

ドキュメントサービスリクエストは、3 種類のステータスコードを返すことができます。

  • 5xx ステータスコードは、内部サーバーエラーが発生したことを示します。通常一時的なエラー状態を表しているため、すべての 5xx エラーコードを捕捉して再試行することをお勧めします。

  • 4xx ステータスコードは、リクエストの形式が正しくないことを示します。

  • 2xx ステータスコードは、リクエストが正常に処理されたことを示します。

エラー 説明 HTTP ステータスコード
No Content-Type Content-Type ヘッダーがありません。 400
No Content-Length Content-Length ヘッダーがありません。 411
Incorrect Path URL パスが ''/YYYY-MM-DD/documents/batch'' と一致しません。 404
Invalid HTTP Method HTTP メソッドが POST ではありません。リクエストは、documents/batch に投稿する必要があります。 405
Invalid Accept Type Accept ヘッダーは、''application/xml'' または ''application/json'' 以外のコンテンツタイプを指定します。応答は XML または JSON 形式でのみ送信できます。 406
Request Too Large リクエストボディの長さが最大許容値を超えています。 413
Invalid Content Type コンテンツタイプが "application/json" または "application/xml" 以外です。 415
Invalid Character Set 文字セットが ''ASCII''、''ISO-8859-1''、または ''UTF-8'' 以外です。 415

一般的なリクエストヘッダー

名前 説明 必須
Content-Type オブジェクトデータの形式を記述する標準 MIME タイプ。詳細については、「W3C RFC 2616 Section 14」を参照してください。

デフォルト: application/json

制約: application/json または application/xml のみ

必須
Content-Length リクエストの本文のバイト長。 はい
Accept 応答データの形式を記述する標準 MIME タイプ。詳細については、「W3C RFC 2616 Section 14」を参照してください。

デフォルト: リクエストのコンテンツタイプ

制約: application/json または application/xml のみ

いいえ

共通の応答ヘッダー

名前 説明
Content-Type オブジェクトデータの形式を記述する標準 MIME タイプ。詳細については、「W3C RFC 2616 Section 14」を参照してください。

デフォルト: リクエスト内の Accept ヘッダーの値。または Accept ヘッダーがない場合や、application/xml または application/json を指定していない場合は、リクエストの Content-Type。

制約: application/xml または application/json のみ

Content-Length 応答の本文のバイト長。