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

# 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、\_ (底線)、- (連字號)、/ (正斜線)、\# (井字號)、: (冒號)。長度上限為 128 個字元。 | 是 | 
| fields | 一個或多個 field\_name 屬性的集合，定義了文件所包含的欄位。條件：新增操作的必要項目。需包含至少一個 *field\_name* 屬性。 | 有條件 | 
| field\_name | 指定欲新增的文件內某一欄位。欄位名稱必須以字母開頭，並可包含以下字元：a-z (小寫)、0-9 和 \_ (底線)。欄位名稱長度需至少 3 個字元且不得超過 64 個字元。名稱 score 是保留項目，不得做為欄位名稱使用。 若要為某欄位指定多個值，請指定值的陣列而非單一值。例如：<br />`"genre": ["Adventure","Drama","Fantasy","Thriller"]`<br /> 條件：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 狀態碼
<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 <br />限制：僅限 application/json 或 application/xml | 必要 | 
| 內容長度 | 請求內文以位元組為單位的長度。 | 是 | 
| 接受 | 描述回應資料格式的標準 MIME 類型。如需詳細資訊，請參閱 [W3C RFC 2616 第 14 節](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)。預設：請求的內容類型<br />限制：僅限 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 則為請求的內容類型。<br />限制：僅限 application/xml 或 application/json | 
| 內容長度 | 回應內文以位元組為單位的長度。 |