本文說明如何批次處理 API 呼叫，以減少用戶端必須建立的 HTTP 連線數量。
本文件專門說明如何透過傳送 HTTP 要求來提出批次要求。請改為使用 Google 用戶端程式庫提出批次要求，請參閱用戶端程式庫的說明文件。
總覽
用戶端建立的每個 HTTP 連線都會造成一定程度的負擔。People API 支援批次處理，可讓用戶端在單一 HTTP 要求中加入數個 API 呼叫。
以下是您可能想要使用批次作業的狀況範例：
- 您剛開始使用 API，有許多資料需要上傳。
- 使用者在您的應用程式離線 (中斷與網際網路的連線) 時變更了資料，所以應用程式必須傳送許多更新和刪除資料，讓本機資料能夠與伺服器同步處理。
在任一情況下，您都可以將這些呼叫集結成單一 HTTP 要求，而不要個別傳送每項呼叫。所有內部要求都必須傳送至同一個 Google API。
單一批次要求最多能呼叫 1,000 次。如果您需要進行更多的呼叫，請使用多個批次要求。
注意：People API 批次系統使用的語法與 OData 批次處理系統相同，但語意不同。
批次詳細資料
批次要求是由多個 API 呼叫合併成一個 HTTP 要求，這個要求可以傳送到 API 探索文件中指定的 batchPath。預設路徑為 /batch/api_name/api_version。本節詳細說明批次語法，並在之後提供範例。
注意：批次處理的 n 要求組合會計入用量限制，當做 n 要求，而非單一要求。批次要求會在處理之前，先將要求分成一組要求。
批次要求的格式
批次要求是單一標準 HTTP 要求，內含多個使用 multipart/mixed 內容類型的 People API 呼叫。在主要 HTTP 要求中，每個部分都含有一個巢狀的 HTTP 要求。
每個部分的開頭都是專屬的 Content-Type: application/http HTTP 標頭。也可以視需要使用 Content-ID 標頭。不過，部分標頭只是用來標示該部分的開頭，與巢狀要求不同。伺服器將批次要求解除包裝成個別的要求後，就會忽略部分標頭。
每個分部的主體本身就是一個完整的 HTTP 要求，有自己的動詞、URL、標頭和內文。HTTP 要求只能包含 URL 的路徑部分；批次要求禁止納入完整的 URL。
外部批次要求的 HTTP 標頭會套用至批次中的所有要求，但 Content- 標頭 (例如 Content-Type) 除外。如果您在外部要求和個別呼叫中均指定所提供的 HTTP 標頭，則個別呼叫標頭的值會覆寫外部批次要求標頭的值。個別呼叫的標頭只會套用於該呼叫。
例如，如果您提供 Authorization 標頭用於特定呼叫，則該標頭只會套用於該呼叫。如果您提供 Authorization 標頭用於外部要求，則除非個別呼叫以自己的 Authorization 標頭覆寫所提供的標頭，否則所提供的 Authorization 標頭會套用於所有個別呼叫。
當伺服器收到批次要求時，即會將外部要求的查詢參數和標頭 (在適用情況下) 套用至每一個分部，然後將每個分部視為不同的 HTTP 要求。
回應批次要求
伺服器回應是包含 multipart/mixed 內容類型的單一標準 HTTP 回應；每個部分都是批次要求中其中一個要求的回應，與要求的順序相同。
就像要求中的分部一樣，每個回應分部都含有完整的 HTTP 回應，包括狀態碼、標頭和內文；就像要求中的部分一樣，每個回應部分的前面都會加上 Content-Type 標頭，標示該部分的開頭。
如果要求的指定部分有 Content-ID 標頭，則回應的對應部分會有相符的 Content-ID 標頭，原始值前面會加上 response- 字串，如以下範例所示。
注意事項：伺服器得按任意順序執行您的呼叫。不要期望呼叫會按您的指定順序執行。如果您想要確保兩個呼叫依指定順序執行，就不能以單一要求傳送它們，而要先傳送第一個呼叫，然後等到第一個呼叫的回應後才能傳送第二個呼叫。
範例
以下範例顯示如何搭配 People API 使用批次處理。
批次要求範例
POST /batch HTTP/1.1 accept-encoding: gzip, deflate Authorization: Bearer your_auth_token Content-Type: multipart/mixed; boundary="batch_people" Content-Length: total_content_length--batch_people Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 1
POST /v1/people:createContact HTTP/1.1 Content-Type: application/json Content-Length: part_content_length Accept: application/json { "names": [{ "givenName": "John", "familyName": "Doe" }] }
--batch_people Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 2
GET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1 Accept: application/json --batch_people--
批次回應範例
這是前一節中範例要求的回應。
HTTP/1.1 200 OK Content-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Date: Tue, 22 Jan 2020 18:56:00 GMT Expires: Tue, 22 Jan 2020 18:56:00 GMT Cache-Control: private--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "resourceName": "people/c11111111111111", "etag": "1111", "names": [{ "givenName": "John", "familyName": "Doe" }] }
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "resourceName": "people/c123456789012345", "etag": "1234", "emailAddresses": [{ "value": "jane.doe@gmail.com" }] } --batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--