本頁面由 Cloud Translation API 翻譯而成。

傳送批次要求

這個版本的 API 只會使用批次要求來轉移訂閱項目。此外，API 的批次要求中不會填入批次 Content-ID 欄位。

本文說明如何批次處理 API 呼叫，以減少 HTTP 連線數量而非客戶需要做的事

本文專門說明如何透過傳送 HTTP 要求來提交批次要求。如果您是使用 Google 用戶端程式庫提交批次要求，請參閱用戶端程式庫的說明文件。

總覽

用戶端的每個 HTTP 連線都會造成一定程度的負擔。Admin SDK API 支援批次作業，可讓用戶端在單一 HTTP 要求中加入數個 API 呼叫。

以下是您可能想要使用批次作業的狀況範例：

您剛開始使用 API，有許多資料需要上傳。
使用者在您的應用程式離線 (中斷與網際網路的連線) 時變更了資料，所以應用程式必須傳送許多更新和刪除資料，讓本機資料能夠與伺服器同步處理。

在任一案例中，都不需要個別傳送每一個呼叫，只需將這些呼叫分組後組成單一 HTTP 要求。所有內部要求都必須前往相同的 Google API。

單一批次要求最多能包含 1,000 個呼叫。如果您發出的呼叫數量超過這個上限，請使用多個批次要求。

注意：Admin SDK API 批次系統使用的語法與 OData 批次處理系統相同，但語意不同。

批次詳細資料

批次要求是由多個 API 呼叫合併成一個 HTTP 要求，系統會將這個要求傳送至 API 探索文件中指定的 batchPath。預設路徑為 /batch/api_name/api_version。本節將詳細說明批次語法。後面還有範例。

注意：一組批次處理的 n 要求將計入用量限制，並計為 n 要求，而非單一要求。在這個處理之前，批次要求會拆分成一組要求。

批次要求的格式

批次要求是單一標準 HTTP 要求，內含多個使用 multipart/mixed 內容類型的 Admin SDK API 呼叫。在主要 HTTP 要求中，每個分部都含有一個巢狀的 HTTP 要求。

每個部分都以自己的 Content-Type: application/http HTTP 標頭開始。也可以有選用的 Content-ID 標頭。但分部標頭只是用來標示部分開頭。內容與巢狀請求無關伺服器將批次要求解除包裝成個別要求後，系統會忽略該部分標頭。

每個部分的主體都是完整的 HTTP 要求，具有自己的動詞、網址、標頭和內文。HTTP 要求只能包含 URL 的路徑部分；批次要求禁止納入完整的 URL。

外部批次要求的 HTTP 標頭會套用於批次中的每項要求，但 Content- 標頭 (例如 Content-Type) 除外。如果您在外部要求和個別呼叫中均指定所提供的 HTTP 標頭，則個別呼叫標頭的值會覆寫外部批次要求標頭的值。個別呼叫的標頭只會套用於該呼叫。

例如，如果您提供 Authorization 標頭用於特定呼叫，則該標頭只會套用於該呼叫。如果您提供 Authorization 標頭用於外部要求，則除非個別呼叫以自己的 Authorization 標頭覆寫所提供的標頭，否則所提供的 Authorization 標頭會套用於所有個別呼叫。

當伺服器收到批次要求時，即會將外部要求的查詢參數和標頭 (在適用情況下) 套用至每一個分部，然後將每個分部視為不同的 HTTP 要求。

回應批次要求

伺服器回應是含有 multipart/mixed 內容類型的單一標準 HTTP 回應。每個部分都是回應批次要求中其中一個要求的回應，回應順序與要求順序相同。

就像要求中的分部一樣，每個回應分部都含有完整的 HTTP 回應，包括狀態碼、標頭和內文；如同要求的各個部分，每個回應部分的前面都會加上 Content-Type 標頭，用來標示該部分的開頭。

如果要求的指定部分有 Content-ID 標頭，則回應的對應部分會有相符的 Content-ID 標頭，且原始值在前面加上 response- 字串，如以下範例所示。

注意：伺服器可能會按任意順序執行呼叫。不要期望呼叫會按您的指定順序執行。如果您想要確保兩個呼叫依指定順序執行，就不能以單一要求傳送它們，而要先傳送第一個呼叫，然後等到第一個呼叫的回應後才能傳送第二個呼叫。

範例

以下範例顯示如何使用 Admin SDK API 進行批次處理。

批次要求範例


/*This example uses comments and variables for clarity.*/
/*These are not used in JSON. Do not include these comments or verbatim*/
/*variable strings in your batch request.*/
/*To batch multiple requests in one call, use the following*/
/*                                                         */
/*POST HTTP request, and use the following request body syntax.*/
/*                                                  */
/*POST https://www.googleapis.com/batch*/

--batch_foobar--

批次回應範例

這是前一節中範例要求的回應。

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:12930812@barnyard.example.com>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--