批次處理 Google Analytics (分析) API 要求

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

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

總覽

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

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

更新使用者權限。發出批次要求來更新使用者權限時，可以獲得特定的效能提升和配額獎勵，詳情請參閱「使用者權限開發人員指南」。
行動報告應用程式可能會離線，您必須在應用程式恢復連線後提出一組資料要求。
您有一個服務帳戶應用程式，需要定期建立多份報表。
您必須建立一組自訂維度或自訂指標，並只提出一個 HTTP 要求。

在每個情況下，您可以將呼叫組合成單一 HTTP 要求，不用分別傳送每個呼叫。所有內部要求都必須前往同一個 Google API。

單一批次要求最多可以呼叫 1,000 個呼叫。如果您必須發出更多呼叫，請使用多個批次要求。

注意：Google Analytics (分析) API 批次系統使用的語法與OData 批次處理系統相同，但語意不同。

批次詳細資料

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

注意：分批的 n 要求集會算成 n 要求，而非單一要求。處理前，系統會將批次要求分成一組要求。

批次要求的格式

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

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

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

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

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

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

回應批次要求

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

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

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

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

範例

下例示範如何透過 Google Analytics (分析) API 進行批次處理。

批次要求範例

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

批次回應範例

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

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

用戶端程式庫

請參考以下用戶端程式庫指南，瞭解如何使用您的語言實作批次處理：

批次處理和 Google Analytics (分析) 配額

雖然批次處理可省下建立多個 HTTP 要求的費用，但凡是透過批次要求建立的 Google Analytics (分析) API 要求都會計入每日專案配額。根據預設，專案每天可提出最多 50,000 次要求，而批次處理能幫助您避免超過這項配額。

除了批次的使用者權限寫入 (刪除、插入、更新) 要求外，系統依然適用所有頻率限制。舉例來說，Core Reporting API 最多只能每個資料檢視 10 個並行要求 (個人資料)，批次處理功能無法幫助您低於這項限制。

每個帳戶 ID 的每秒 1.5 次查詢 (QPS) 限制適用於 Management API 寫入要求和 Provisioning API 寫入要求。因此，批次處理這些寫入要求可能無法改善效能。