如 Google Developers 網誌公告的批次方法,全球性 HTTP 批次端點 (www.googleapis.com/batch
) 已於 2020 年 8 月 12 日終止。如本頁其餘部分所述,其他批次處理方法仍可正常運作。如果您的程式碼使用全域 HTTP 批次端點,請參閱網誌文章,瞭解如何改用其他方法,例如 API 專屬的 HTTP 批次端點 (www.googleapis.com/batch/API/VERSION
)。
本文說明如何批次處理 API 呼叫,以減少用戶端必須建立的 HTTP 連線數量。
本文件特別介紹如何傳送 HTTP 要求以提出批次要求。如果您目前使用 Google 用戶端程式庫提出批次要求,請參閱用戶端程式庫的說明文件。
總覽
用戶端建立的每個 HTTP 連線都會造成一定程度的負擔。Google Mirror API 支援批次處理,讓用戶端可以一次發出多個 API 呼叫。
以下是您可能想要使用批次作業的狀況範例:
- 您剛開始使用 API,有許多資料需要上傳。
- 使用者在您的應用程式離線 (中斷與網際網路的連線) 時變更了資料,所以應用程式必須傳送許多更新和刪除資料,讓本機資料能夠與伺服器同步處理。
在各情況下,您不用個別傳送每個呼叫,而是將這些呼叫歸入同一個 HTTP 要求。所有內部要求都必須傳送至同一個 Google API。
單一批次要求最多只能呼叫 1,000 次。如果您需要進行呼叫,請使用多個批次要求。
注意:Google Mirror API 的批次系統使用的語法與 OData 批次處理系統相同,但語意不同。
批次詳細資料
批次要求包含多個 API 呼叫,合併為一個 HTTP 要求,可傳送至 API 探索文件中指定的 batchPath
。預設路徑為 /batch/api_name/api_version
。本節詳細說明批次語法,稍後會有範例。
注意:系統會將一組「n」批次處理成一個用量上限,並計入「n」要求的用量,而不是一個要求。批次要求會先分割成一組要求,然後再進行處理。
批次要求的格式
批次要求是單一標準 HTTP 要求,其中包含使用 multipart/mixed
內容類型的多個 Google Mirror 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-
,如以下範例所示。
注意事項:伺服器得按任意順序執行您的呼叫。不要期望呼叫會按您的指定順序執行。如果您想要確保兩個呼叫依指定順序執行,就不能以單一要求傳送它們,而要先傳送第一個呼叫,然後等到第一個呼叫的回應後才能傳送第二個呼叫。
範例
以下範例說明如何使用 Google Mirror API 進行批次處理。
批次要求範例
POST /batch HTTP/1.1 Content-Length: content_length content-type: multipart/mixed; boundary="===============7330845974216740156==" accept-encoding: gzip, deflate --===============7330845974216740156== Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: TIMELINE_INSERT_USER_1 POST /mirror/v1/timeline HTTP/1.1 Content-Type: application/json authorization: Bearer user_1_token accept: application/json content-length: 24 {"text": "Hello there!"} --===============7330845974216740156== Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: TIMELINE_INSERT_USER_2 POST /mirror/v1/timeline HTTP/1.1 Content-Type: application/json authorization: Bearer user_2_token accept: application/json content-length: 24 {"text": "Hello there!"} --===============7330845974216740156== Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: TIMELINE_INSERT_USER_3 POST /mirror/v1/timeline HTTP/1.1 Content-Type: application/json authorization: Bearer user_3_token accept: application/json content-length: 24 {"text": "Hello there!"} --===============7330845974216740156==--
批次回應範例
這是前一節中範例要求的回應。
HTTP/1.1 200 OK Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q= Date: Tue, 22 Jan 2013 18:56:00 GMT Expires: Tue, 22 Jan 2013 18:56:00 GMT Cache-Control: private, max-age=0 --batch_pK7JBAk73-E=_AA5eFwv4m2Q= Content-Type: application/http Content-ID: response-TIMELINE_INSERT_USER_1 HTTP/1.1 201 Created Content-Type: application/json Content-Length: 304 { "kind": "glass#timelineItem", "id": "1234567890", "selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890", "created": "2012-09-25T23:28:43.192Z", "updated": "2012-09-25T23:28:43.192Z", "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"", "text": "Hello there!" } --batch_pK7JBAk73-E=_AA5eFwv4m2Q= Content-Type: application/http Content-ID: response-TIMELINE_INSERT_USER_2 HTTP/1.1 201 Created Content-Type: application/json Content-Length: 304 { "kind": "glass#timelineItem", "id": "0987654321", "selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321", "created": "2012-09-25T23:28:43.192Z", "updated": "2012-09-25T23:28:43.192Z", "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"", "text": "Hello there!" } --batch_pK7JBAk73-E=_AA5eFwv4m2Q= Content-Type: application/http Content-ID: response-TIMELINE_INSERT_USER_3 HTTP/1.1 201 Created Content-Type: application/json Content-Length: 304 { "kind": "glass#timelineItem", "id": "5432109876", "selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876", "created": "2012-09-25T23:28:43.192Z", "updated": "2012-09-25T23:28:43.192Z", "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"", "text": "Hello there!" } --batch_pK7JBAk73-E=_AA5eFwv4m2Q=--