Tạo lô cho các yêu cầu API Google Analytics

Tài liệu này trình bày cách nhóm các lệnh gọi API lại với nhau để giảm số lượng kết nối HTTP mà ứng dụng của bạn phải thực hiện.

Tài liệu này trình bày cụ thể về việc thực hiện một yêu cầu hàng loạt bằng cách gửi một yêu cầu HTTP. Thay vào đó, nếu bạn đang sử dụng thư viện ứng dụng của Google để gửi yêu cầu hàng loạt, hãy xem tài liệu về thư viện ứng dụng.

Tổng quan

Mỗi kết nối HTTP mà ứng dụng của bạn sẽ tạo ra một mức hao tổn nhất định. API Google Analytics hỗ trợ tạo lô để cho phép khách hàng của bạn đưa nhiều lệnh gọi API vào một yêu cầu HTTP.

Ví dụ về các trường hợp mà bạn nên sử dụng tính năng tạo lô:

Trong mỗi trường hợp, thay vì gửi riêng từng lệnh gọi, bạn có thể nhóm chúng lại với nhau thành một yêu cầu HTTP duy nhất. Tất cả các yêu cầu bên trong phải đi tới cùng một Google API.

Bạn chỉ có thể thực hiện tối đa 1.000 lệnh gọi trong một yêu cầu theo lô. Nếu bạn phải thực hiện nhiều lệnh gọi hơn thế, hãy sử dụng nhiều yêu cầu hàng loạt.

Lưu ý: Hệ thống xử lý hàng loạt cho API Google Analytics sử dụng cú pháp giống như hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa thì khác.

Chi tiết gói

Yêu cầu hàng loạt bao gồm nhiều lệnh gọi API kết hợp thành một yêu cầu HTTP. Yêu cầu này có thể được gửi tới batchPath được chỉ định trong tài liệu khám phá API. Đường dẫn mặc định là /batch/api_name/api_version. Phần này mô tả chi tiết về cú pháp lô; phần sau sẽ có ví dụ.

Lưu ý: Một nhóm các yêu cầu n được gộp lại với nhau sẽ được tính vào hạn mức sử dụng của bạn dưới dạng các yêu cầu n, chứ không phải một yêu cầu. Yêu cầu hàng loạt được tách thành một nhóm yêu cầu trước khi xử lý.

Định dạng của yêu cầu hàng loạt

Yêu cầu hàng loạt là một yêu cầu HTTP chuẩn chứa nhiều lệnh gọi API Google Analytics, sử dụng loại nội dung multipart/mixed. Trong yêu cầu HTTP chính đó, mỗi phần đều chứa một yêu cầu HTTP lồng nhau.

Mỗi phần bắt đầu bằng tiêu đề HTTP Content-Type: application/http riêng. Tệp này cũng có thể có tiêu đề Content-ID (không bắt buộc). Tuy nhiên, các tiêu đề phần chỉ xuất hiện để đánh dấu phần đầu của phần đó; chúng tách biệt với yêu cầu lồng nhau. Sau khi máy chủ khám phá yêu cầu hàng loạt thành các yêu cầu riêng biệt, các tiêu đề của phần sẽ bị bỏ qua.

Nội dung của mỗi phần là một yêu cầu HTTP hoàn chỉnh, với động từ, URL, tiêu đề và nội dung riêng. Yêu cầu HTTP chỉ được chứa phần đường dẫn của URL; URL đầy đủ không được phép trong yêu cầu hàng loạt.

Các tiêu đề HTTP cho yêu cầu theo lô bên ngoài, ngoại trừ các tiêu đề Content- như Content-Type, áp dụng cho mọi yêu cầu trong lô. Nếu bạn chỉ định một tiêu đề HTTP nhất định trong cả yêu cầu bên ngoài và lệnh gọi riêng lẻ, thì giá trị của tiêu đề cuộc gọi riêng lẻ sẽ ghi đè giá trị của tiêu đề yêu cầu hàng loạt bên ngoài. Tiêu đề của từng cuộc gọi chỉ áp dụng cho lệnh gọi đó.

Ví dụ: nếu bạn cung cấp tiêu đề Uỷ quyền cho một cuộc gọi cụ thể, thì tiêu đề đó sẽ chỉ áp dụng cho lệnh gọi đó. Nếu bạn cung cấp tiêu đề Uỷ quyền cho yêu cầu bên ngoài, thì tiêu đề đó sẽ áp dụng cho tất cả các lệnh gọi riêng lẻ trừ phi các lệnh gọi này ghi đè tiêu đề Uỷ quyền của riêng mình.

Khi nhận được yêu cầu theo lô, máy chủ sẽ áp dụng tham số truy vấn và tiêu đề của yêu cầu bên ngoài (nếu phù hợp) cho từng phần, sau đó xử lý từng phần như thể đó là một yêu cầu HTTP riêng biệt.

Phản hồi một yêu cầu hàng loạt

Phản hồi của máy chủ là một phản hồi HTTP chuẩn có loại nội dung multipart/mixed; mỗi phần là phản hồi cho một trong các yêu cầu trong yêu cầu theo lô, theo thứ tự tương tự như các yêu cầu.

Giống như các phần trong yêu cầu, mỗi phần phản hồi chứa một phản hồi HTTP hoàn chỉnh, bao gồm một mã trạng thái, tiêu đề và nội dung. Và giống như các phần trong yêu cầu, mỗi phần phản hồi đều đứng sau một tiêu đề Content-Type đánh dấu phần đầu của phần đó.

Nếu một phần nhất định của yêu cầu có tiêu đề Content-ID, thì phần tương ứng của phản hồi sẽ có tiêu đề Content-ID trùng khớp, với giá trị ban đầu đứng sau chuỗi response-, như trong ví dụ sau.

Lưu ý: Máy chủ có thể thực hiện các lệnh gọi của bạn theo thứ tự bất kỳ. Không tin vào việc các tham số đó được thực thi theo thứ tự mà bạn đã chỉ định. Nếu muốn đảm bảo rằng hai lệnh gọi diễn ra theo một thứ tự nhất định, bạn không thể gửi các lệnh gọi đó trong một yêu cầu; thay vào đó, hãy tự gửi yêu cầu đầu tiên rồi đợi phản hồi cho lệnh gọi đầu tiên trước khi gửi lệnh gọi thứ hai.

Ví dụ:

Ví dụ sau đây cho thấy việc sử dụng tính năng tạo lô bằng API Google Analytics.

Ví dụ về yêu cầu hàng loạt

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--

Ví dụ về phản hồi hàng loạt

Đây là phản hồi cho yêu cầu mẫu trong phần trước.

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--

Thư viện ứng dụng

Hãy làm theo hướng dẫn sau đây về thư viện ứng dụng để xem cách triển khai tính năng Lô sản phẩm bằng ngôn ngữ của bạn:

Gộp nhóm và hạn mức Google Analytics

Mặc dù việc phân lô có thể giúp bạn tiết kiệm chi phí khi tạo nhiều yêu cầu HTTP, mỗi yêu cầu API Google Analytics trong một yêu cầu hàng loạt sẽ được tính vào hạn mức dự án hằng ngày của bạn. Theo mặc định,một dự án có thể giải quyết tối đa 50.000 yêu cầu mỗi ngày; việc tạo lô sẽ không giúp bạn duy trì mức hạn mức này.

Ngoại trừ các yêu cầu Quyền người dùng ghi (xoá, chèn, cập nhật) theo lô, tất cả giới hạn về số lượng vẫn áp dụng. Ví dụ: API Báo cáo chính bị giới hạn ở 10 yêu cầu đồng thời cho mỗi chế độ xem (hồ sơ); việc tạo lô sẽ không giúp bạn duy trì dưới giới hạn này.

Giới hạn 1,5 truy vấn mỗi giây (QPS) cho mỗi mã tài khoản áp dụng cho Yêu cầu ghi API quản lý và Cấp phép yêu cầu ghi API. Do đó, việc phân lô các yêu cầu ghi này có thể không cải thiện được hiệu suất.