documents/batch

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

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

更新文件時，您要指定新增請求並提供您希望更新的該份文件的文件 ID。如需詳細資訊，請參閱 在 Amazon CloudSearch 中新增及更新文件。同樣地，若要刪除文件，您應提交刪除請求並提供您希望刪除的該份文件的文件 ID。如需如何刪除文件的相關資訊，請參閱在 Amazon CloudSearch ch 中刪除文件。

如需如何提交資料以供編製索引的詳細資訊，請參閱upload documents。

documents/batch JSON API

JSON documents/batch 請求

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 結構描述表示法如下所示：

{
    "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	一個或多個 field_name 屬性的集合，定義了文件所包含的欄位。 條件：新增操作的必要項目。需包含至少一個 field_name 屬性。	有條件
field_name	指定欲新增的文件內某一欄位。欄位名稱必須以字母開頭，並可包含以下字元：a-z (小寫)、0-9 和 _ (底線)。欄位名稱長度需至少 3 個字元且不得超過 64 個字元。名稱 score 是保留項目，不得做為欄位名稱使用。 若要為某欄位指定多個值，請指定值的陣列而非單一值。例如： "genre": ["Adventure","Drama","Fantasy","Thriller"] 條件：fields 物件必須指定至少一個欄位。	有條件

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 則一律為零。
deletes	已執行的刪除文件操作數目。狀態若是 error 則一律為零。如需有關永久刪除文件的資訊，請參閱在 Amazon CloudSearch ch 中刪除文件。
錯誤	提供有關剖析或驗證錯誤的資訊。若狀態為 error 才會指定。
warning	提供有關剖析或驗證期間產生的某項警告的資訊。

documents/batch 狀態碼

文件服務請求可能傳回以下三類的狀態碼：

• 5xx 狀態碼表示發生內部伺服器錯誤。建議您截獲並重試所有 5xx 錯誤碼，因為這通常代表暫時性錯誤情況。

• 4xx 狀態碼表示請求的格式不正確。

• 2xx 狀態碼表示已成功處理請求。

錯誤	描述	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

常見請求標題

名稱	描述	必要
內容類型	描述物件資料格式的標準 MIME 類型。如需詳細資訊，請參閱 W3C RFC 2616 第 14 節。 預設：application/json 限制：僅限 application/json 或 application/xml	必要
內容長度	請求內文以位元組為單位的長度。	是
接受	描述回應資料格式的標準 MIME 類型。如需詳細資訊，請參閱 W3C RFC 2616 第 14 節。 預設：請求的內容類型 限制：僅限 application/json 或 application/xml	否

常見回應標頭

名稱	描述
內容類型	描述物件資料格式的標準 MIME 類型。如需詳細資訊，請參閱 W3C RFC 2616 第 14 節。 預設：請求的 Accept 標頭值，若 Accept 標頭遺漏或未指定 application/xml 或 application/json 則為請求的內容類型。 限制：僅限 application/xml 或 application/json
內容長度	回應內文以位元組為單位的長度。