documents/batch

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

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

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

インデックス作成用のデータ送信の詳細については、「upload documents」を参照してください。

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	レスポンスの本文のバイト長。