本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

本節說明 `documents/batch` 資源的 HTTP 請求和回應訊息。

您可以建立文件批次來描述要上傳至 Amazon CloudSearch 網域的資料。文件批次是一組新增和刪除操作，各項操作代表了您希望新增、更新或從網域刪除的文件。批次的描述格式可以是 JSON 或 XML。批次提供 Amazon CloudSearch 編製索引所需的所有資訊。您想要以搜尋結果 （例如產品） 傳回的每個項目都會以文件表示，批次只是個別文件的新增和刪除請求集合。每份文件都具有獨一無二的 ID 和一個或多個欄位，其中包含您要搜尋及由結果傳回的資料。

更新文件時，您要指定新增請求並提供您希望更新的該份文件的文件 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 批次將新增一份文件並刪除某份文件：

```
[
{ "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>


****  

| 屬性 | Description | 必要 | 
| --- | --- | --- | 
| type | 操作類型，add 或 delete。 | 是 | 
| id | 英數字串。允許的字元如下：A-Z (大寫字母)、a-z (小寫字母)、0-9、\$1 (底線)、- (連字號)、/ (正斜線)、\$1 (井字號)、: (冒號)。長度上限為 128 個字元。 | 是 | 
| fields | 一個或多個 field\$1name 屬性的集合，定義了文件所包含的欄位。條件：新增操作的必要項目。需包含至少一個 *field\$1name* 屬性。 | 有條件 | 
| field\$1name | 指定欲新增的文件內某一欄位。欄位名稱必須以字母開頭，並可包含以下字元：a-z (小寫)、0-9 和 \$1 (底線)。欄位名稱長度需至少 3 個字元且不得超過 64 個字元。名稱 score 是保留項目，不得做為欄位名稱使用。 若要為某欄位指定多個值，請指定值的陣列而非單一值。例如： `"genre": ["Adventure","Drama","Fantasy","Thriller"]`  條件：fields 物件必須指定至少一個欄位。  | 有條件 | 

### 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>


****  

| 屬性 | 描述 | 
| --- | --- | 
| status | 結果狀態，可能是 success 或 error。 | 
| adds | 已執行的新增文件操作數目。狀態若是 error 則一律為零。 | 
| deletes | 已執行的刪除文件操作數目。狀態若是 error 則一律為零。如需有關永久刪除文件的資訊，請參閱[在 Amazon CloudSearch 中刪除文件](preparing-data.md#deleting-documents)。 | 
| 錯誤 | 提供有關剖析或驗證錯誤的資訊。若狀態為 error 才會指定。 | 
| warning | 提供有關剖析或驗證期間產生的某項警告的資訊。 | 

# 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 | Description | 必要 | 
| --- | --- | --- | 
| 批次 | 您要提交至搜尋網域的一組新增或刪除操作。批次必須包含至少一個 add 或 delete 元素。 | 是 | 
| add | 指定您要新增至搜尋網域的文件。id 屬性是必要項目，且 add 元素必須包含至少一個欄位。屬性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudsearch/latest/developerguide/documents-batch-xml.html)  | 否 | 
| field | 指定欲新增的文件內某一欄位。name 屬性和欄位值是必要項目。欄位名稱必須以字母開頭，並可包含以下字元：a-z (小寫)、0-9 和 \$1 (底線)。名稱 score 是保留項目，不得做為欄位名稱使用。欄位值可以是文字或 CDATA。 若要為某欄位指定多個值，請附上多個同名的 field 元素。例如： <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/zh_tw/cloudsearch/latest/developerguide/documents-batch-xml.html)  條件：add 元素必須指定至少一個欄位。  | 有條件 | 
| delete | 指定您要從搜尋網域移除的文件。id 屬性是必要項目。delete 元素需為空白。如需有關永久刪除文件的資訊，請參閱[在 Amazon CloudSearch 中刪除文件](preparing-data.md#deleting-documents)。限制條件： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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 | Description | 
| --- | --- | 
| result | 包含各元素以列出剖析及驗證請求時產生的錯誤和警告。 屬性： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudsearch/latest/developerguide/documents-batch-xml.html) 限制：狀態為 `error` 時，results 元素將包含一份錯誤清單。如果狀態是 `success`，results 元素可能包含一份警告清單但無任何錯誤。  | 
| 錯誤 | 包含 error 元素的集合以識別剖析及驗證請求時發生的錯誤。 | 
| error | 提供有關剖析或驗證錯誤的資訊。其值提供該項錯誤的描述。 | 
| warnings | 包含 warning 元素的集合以識別剖析及驗證請求時產生的警告。 | 
| warning | 提供有關剖析或驗證警告的資訊。其值提供該項錯誤的描述。 | 

## documents/batch 狀態碼
<a name="documents-batch-status-codes"></a>

文件服務請求可能傳回以下三類的狀態碼：
+ 5xx 狀態碼表示發生內部伺服器錯誤。建議您截獲並重試所有 5xx 錯誤碼，因為這通常代表暫時性錯誤情況。
+ 4xx 狀態碼表示請求的格式不正確。
+ 2xx 狀態碼表示已成功處理請求。


****  

|  錯誤  |  Description  | HTTP 狀態碼  | 
| --- | --- | --- | 
|  無內容類型  |  遺漏 Content-Type 標頭。 |  400  | 
|  無內容長度  |  遺漏 Content-Length 標頭。 |  411  | 
|  路徑不正確  |  URL 路徑不符合 ''/YYYY-MM-DD/documents/batch''。 |  404  | 
|  HTTP 方法無效  |  HTTP 方法不是 POST。請求必須發佈至 documents/batch。 |  405  | 
|  接受類型無效  |  Accept 標頭指定了 ''application/xml'' 或 ''application/json'' 以外的內容類型。回應只能以 XML 或 JSON 形式傳送。 |  406  | 
|  請求過大  |  請求內文的長度超出允許的上限值。 |  413  | 
|  內容類型無效  |  內容類型並非 "application/json" 或 "application/xml"。 |  415  | 
|  字元集無效  |  字元集並非 ''ASCII''、''ISO-8859-1'' 或 ''UTF-8''。 |  415  | 

## 常見請求標題
<a name="documents-batch-common-request-headers"></a>


****  

| 名稱 | 描述 | 必要 | 
| --- | --- | --- | 
| 內容類型 | 描述物件資料格式的標準 MIME 類型。如需詳細資訊，請參閱 [W3C RFC 2616 第 14 節](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)。預設：application/json  限制：僅限 application/json 或 application/xml  | 必要 | 
| 內容長度 | 請求內文以位元組為單位的長度。 | 是 | 
| 接受 | 描述回應資料格式的標準 MIME 類型。如需詳細資訊，請參閱 [W3C RFC 2616 第 14 節](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)。預設：請求的內容類型 限制：僅限 application/json 或 application/xml | 否 | 

## 常見回應標頭
<a name="documents-batch-common-response-headers"></a>


****  

| 名稱 | 描述 | 
| --- | --- | 
| 內容類型 | 描述物件資料格式的標準 MIME 類型。如需詳細資訊，請參閱 [W3C RFC 2616 第 14 節](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)。預設：請求的 Accept 標頭值，若 Accept 標頭遺漏或未指定 application/xml 或 application/json 則為請求的內容類型。 限制：僅限 application/xml 或 application/json  | 
| 內容長度 | 回應內文以位元組為單位的長度。 |