翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# documents/batch
<a name="documents-batch-resource"></a>

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

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

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

インデックス作成用のデータ送信の詳細については、「[Amazon CloudSearch ドメインへのデータのアップロード](uploading-data.md)」を参照してください。

## documents/batch JSON API
<a name="documents-batch-json"></a>

### JSON documents/batch リクエスト
<a name="documents-batch-json-request"></a>

`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 スキーマ](http://json-schema.org/)表現を次に示します。

```
{
    "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)
<a name="documents-batch-json-properties"></a>


****  

| プロパティ | 説明 | 必須 | 
| --- | --- | --- | 
| 型 | オペレーションのタイプ。add または delete。 | はい | 
| id | 英数字の文字列。使用できる文字は、A～Z (大文字)、a～z (小文字)、0～9、\$1 (下線)、- (ハイフン)、/ (スラッシュ)、\$1 (ハッシュ記号)、: (コロン) です。最大長は 128 文字です。 | はい | 
| fields | ドキュメントに含まれるフィールドを定義する、1 つ以上の field\$1name プロパティのコレクション。条件: 追加オペレーションの場合に必要です。少なくとも 1 個の *field\$1name* プロパティを含める必要があります。 | 条件付き | 
| field\$1name | 追加されるドキュメント内のフィールドを指定します。フィールド名は英数字で始まっている必要があり、次の文字を含めることができます。a​～​z (小文字)、0​～​9、\$1 (下線)。フィールド名は、3～64 文字以内にする必要があります。score という名前は予約済みのため、フィールド名として使用できません。 フィールドに複数の値を指定するには、1 つの値の代わりに値の配列を指定します。例: `"genre": ["Adventure","Drama","Fantasy","Thriller"]`  条件: fields オブジェクトで少なくとも 1 個のフィールドを指定する必要があります。  | 条件付き | 

### documents/batch レスポンス (JSON)
<a name="documents-batch-json-response"></a>

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

ドキュメントサービス 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)
<a name="documents-batch-json-response-properties"></a>


****  

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

# documents/batch XML API
<a name="documents-batch-xml"></a>

## XML documents/batch リクエスト
<a name="documents-batch-xml-request"></a>

`documents/batch` リクエストの本文では、XML で、実行するドキュメントのオペレーションを指定します。例:

```
<batch>
	<add  id="tt0484562">
		<field name="title">The Seeker: The Dark Is Rising</field>
		<field name="director">Cunningham, David L.</field>
		<field name="genre">Adventure</field>
		<field name="genre">Drama</field>
		<field name="genre">Fantasy</field>
		<field name="genre">Thriller</field>
		<field name="actor">McShane, Ian</field>
		<field name="actor">Eccleston, Christopher</field>
		<field name="actor">Conroy, Frances</field>
		<field name="actor">Ludwig, Alexander</field>
		<field name="actor">Crewson, Wendy</field>
		<field name="actor">Warner, Amelia</field>
		<field name="actor">Cosmo, James</field>
		<field name="actor">Hickey, John Benjamin</field>
		<field name="actor">Piddock, Jim</field>
		<field name="actor">Lockhart, Emma</field>
	</add>
	<delete id="tt0301199" />
</batch>
```

### documents/batch リクエストの要素 (XML)
<a name="documents-batch-xml-request-elements"></a>


****  

| Element | 説明 | 必須 | 
| --- | --- | --- | 
| バッチ | 検索ドメインに送信する追加または削除オペレーションのコレクション。バッチには、少なくとも 1 つの add または delete 要素を含める必要があります。 | はい | 
| 追加 | 検索ドメインに追加するドキュメントを指定します。id 属性は必須であり、add 要素には少なくとも 1 つのフィールドが含まれている必要があります。属性: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudsearch/latest/developerguide/documents-batch-xml.html)  | いいえ | 
| field | 追加されるドキュメント内のフィールドを指定します。名前属性およびフィールド値は必須です。フィールド名は英数字で始まっている必要があり、次の文字を含めることができます。a​～​z (小文字)、0​～​9、\$1 (下線)。score という名前は予約済みのため、フィールド名として使用できません。フィールド値にはテキストや CDATA を指定できます。 フィールドに複数の値を指定するには、同じ名前の複数のフィールド要素を含めます。例: <pre><field name="genre">Adventure</field><br /><field name="genre">Drama</field><br /><field name="genre">Fantasy</field><br /><field name="genre">Thriller</field></pre> 制約: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudsearch/latest/developerguide/documents-batch-xml.html)  条件: add 要素で少なくとも 1 個のフィールドを指定する必要があります。  | 条件付き | 
| 削除 | 検索ドメインから削除するドキュメントを指定します。id 属性は必須です。delete 要素は空にする必要があります。ドキュメントの完全な削除の詳細については、「[Amazon CloudSearch でのドキュメントの削除](preparing-data.md#deleting-documents)」を参照してください。制約: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudsearch/latest/developerguide/documents-batch-xml.html)  | いいえ | 

## documents/batch レスポンス (XML)
<a name="documents-batch-xml-response"></a>

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

ドキュメントサービス API レスポンスの RelaxNG スキーマは次のとおりです。

```
 start = response

response = element response {
    attribute status { "success" | "error" },
    attribute adds { xsd:integer },
    attribute deletes { xsd:integer },
    element errors {
        element error {
            text
        }+
    }? &
    element warnings {
        element warning {
            text
        }+
    }?
}
```

### documents/batch レスポンスの要素 (XML)
<a name="documents-batch-xml-response-elements"></a>


****  

| Element | 説明 | 
| --- | --- | 
| 結果 | リクエストを解析および検証するときに生成されたエラーおよび警告をリストする要素が含まれます。 属性: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudsearch/latest/developerguide/documents-batch-xml.html) 制約: ステータスが `error` の場合、results 要素にはエラーのリストが含まれます。ステータスが `success` の場合、results 要素に警告のリストを含めることができますが、エラーは含まれません。  | 
| エラー | リクエストの解析時および検証時に発生したエラーを示す error 要素のコレクションが含まれます。 | 
| エラー | 解析エラーまたは検証エラーに関する情報を提供します。値はエラーの説明を提供します。 | 
| warnings | リクエストの解析時および検証時に生成された警告を示す warning 要素のコレクションが含まれます。 | 
| 警告 | 解析または検証の警告に関する情報を提供します。値はエラーの説明を提供します。 | 

## documents/batch ステータスコード
<a name="documents-batch-status-codes"></a>

ドキュメントサービスリクエストは、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  | 

## 一般的なリクエストヘッダー
<a name="documents-batch-common-request-headers"></a>


****  

| 名前 | 説明 | 必須 | 
| --- | --- | --- | 
| Content-Type | オブジェクトデータの形式を記述する標準 MIME タイプ。詳細については、[「W3C RFC 2616 Section 14」](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)を参照してください。デフォルト: application/json  制約: application/json または application/xml のみ  | 必須 | 
| Content-Length | リクエストの本文のバイト長。 | はい | 
| Accept | レスポンスデータの形式を記述する標準 MIME タイプ。詳細については、[「W3C RFC 2616 Section 14」](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)を参照してください。デフォルト: リクエストのコンテンツタイプ 制約: application/json または application/xml のみ | いいえ | 

## 共通のレスポンスヘッダー
<a name="documents-batch-common-response-headers"></a>


****  

| 名前 | 説明 | 
| --- | --- | 
| Content-Type | オブジェクトデータの形式を記述する標準 MIME タイプ。詳細については、[「W3C RFC 2616 Section 14」](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)を参照してください。デフォルト: リクエスト内の Accept ヘッダーの値。または Accept ヘッダーがない場合や、application/xml または application/json を指定していない場合は、リクエストの Content-Type。 制約: application/xml または application/json のみ  | 
| Content-Length | レスポンスの本文のバイト長。 |