批次要求

通用 HTTP 批次端點 (www.googleapis.com/batch) 將於 2020 年 8 月 12 日停止運作,並已公告於 Google Developers 網誌。關於如何轉換服務以使用 API 專屬 HTTP 批次端點 (www.googleapis.com/batch/api/version),請參閱網誌文章的操作說明。

本文說明如何批次處理 API 呼叫,以減少用戶端必須建立的 HTTP 連線數量。

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

總覽

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

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

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

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

單一批次要求最多能包含 1,000 個呼叫,如果您需要進行更多呼叫,請使用多個批次要求。

附註:BigQuery API 批次系統使用的語法與 OData 批次處理系統相同,但語意不同。

批次詳細資料

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

附註:組成批次的「n」個要求在用量限制中會算成「n」個要求,而不是一個要求。因為批次要求會先分解成一組要求再進行處理。

批次要求的格式

批次要求是單一標準 HTTP 要求,內含多個使用 multipart/mixed 內容類型的 BigQuery 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- 字串,如下列範例所示。

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

範例

以下範例顯示批次作業的使用,其中示範用的一般 (虛構) API 稱為 Farm API。但同樣的概念也適用於 BigQuery API。

批次要求範例

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

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

GET /farm/v1/animals/pony

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

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

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

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

批次回應範例

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

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--
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
需要協助嗎?請前往我們的支援網頁