Một phương pháp cụ thể để tạo lô, điểm cuối HTTP HTTP toàn cục (www.googleapis.com/batch), đã ngừng hoạt động vào ngày 12 tháng 8 năm 2020, như đã thông báo trên blog dành cho Nhà phát triển của Google. Các phương pháp khác để tạo lô vẫn hoạt động, như được ghi lại trên phần còn lại của trang này. Nếu mã của bạn sử dụng điểm cuối HTTP HTTP toàn cục, hãy xem bài đăng trên blog để biết hướng dẫn về cách chuyển đổi để sử dụng các phương pháp khác, chẳng hạn như các điểm cuối lô HTTP cụ thể theo API (www.googleapis.com/batch/API/VERSION).
Tài liệu này cho thấy cách phân nhóm hàng loạt lệnh gọi API để 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 đề cập cụ thể cách tạo một yêu cầu hàng loạt bằng cách gửi một yêu cầu HTTP. Ngược lại, nếu bạn đang sử dụng thư viện ứng dụng khách của Google để tạo yêu cầu hàng loạt, hãy xem tài liệu về thư viện ứng dụng khách.
Tổng quan
Mỗi kết nối HTTP mà ứng dụng của bạn thực hiện sẽ dẫn đến mức hao tổn nhất định. API Báo cáo trải nghiệm quảng cáo của Google hỗ trợ tạo lô để cho phép ứng dụng của bạn đặt nhiều lệnh gọi API vào một yêu cầu HTTP.
Ví dụ về các tình huống mà bạn có thể muốn sử dụng tạo lô:
- Bạn vừa bắt đầu sử dụng API và có nhiều dữ liệu để tải lên.
- Người dùng đã thực hiện các thay đổi đối với dữ liệu trong khi ứng dụng của bạn ngoại tuyến (bị ngắt kết nối với Internet), vì vậy ứng dụng của bạn cần phải đồng bộ hóa dữ liệu cục bộ với máy chủ bằng cách gửi nhiều cập nhật và xoá.
Trong từng trường hợp, thay vì gửi riêng từng lệnh gọi, bạn có thể nhóm các lệnh gọi đó 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 nội bộ đều phải thuộc cùng một API Google.
Bạn chỉ được thực hiện 1000 cuộc gọi trong một yêu cầu hàng loạt. Nếu bạn cần thực hiện nhiều cuộc gọi hơn, hãy dùng nhiều yêu cầu theo lô.
Lưu ý: Hệ thống hàng loạt dành cho API Báo cáo trải nghiệm quảng cáo của Google sử dụng cú pháp giống như hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa sẽ khác nhau.
Chi tiết gói
Một 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 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 của lô; sau đó sẽ là ví dụ.
Lưu ý: Một nhóm các yêu cầu n được nhóm 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 n yêu cầu, chứ không phải là một yêu cầu. Yêu cầu hàng loạt được đưa vào một tập hợp các yêu cầu trước khi xử lý.
Định dạng của một yêu cầu hàng loạt
Yêu cầu hàng loạt là một yêu cầu HTTP tiêu chuẩn duy nhất chứa nhiều lệnh gọi API Báo cáo trải nghiệm quảng cáo của Google, sử dụng loại nội dung multipart/mixed. Trong yêu cầu HTTP chính đó, mỗi phần sẽ 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. Tiêu đề này cũng có thể có một tiêu đề Content-ID không bắt buộc. Tuy nhiên, tiêu đề của phần này 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ủ mở gói yêu cầu hàng loạt thành các yêu cầu riêng biệt, tiêu đề của phần sẽ bị bỏ qua.
Phần 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; không được phép sử dụng URL đầy đủ trong yêu cầu hàng loạt.
Các tiêu đề HTTP cho yêu cầu 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à một 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 một cuộc gọi riêng lẻ chỉ áp dụng cho cuộc 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 đề đó chỉ áp dụng cho cuộc 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 đề đó áp dụng cho tất cả các lệnh gọi riêng lẻ trừ khi các lệnh gọi đó ghi đè bằng các tiêu đề Uỷ quyền của riêng chúng.
Khi nhận được yêu cầu hàng loạt, máy chủ sẽ áp dụng các tham số và tiêu đề truy vấn của yêu cầu bên ngoài (nếu thích 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.
Phản hồi cho một yêu cầu hàng loạt
Phản hồi của máy chủ là phản hồi HTTP tiêu chuẩn duy nhất 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 hàng loạt, theo cùng thứ tự với 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ã 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 đứ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 có tiêu đề Content-ID phù hợ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 cuộc gọi theo thứ tự bất kỳ. Đừng tính những việc này được thực thi theo thứ tự mà bạn đã chỉ định. Nếu muốn đảm bảo rằng hai cuộc gọi xảy ra theo một thứ tự nhất định, bạn không thể gửi chúng trong một yêu cầu; thay vào đó, hãy gửi riêng lệnh gọi đầu tiên, sau đó đợi phản hồi đầu tiên rồi gửi lệnh thứ hai.
Ví dụ:
Ví dụ sau cho thấy việc sử dụng tính năng tạo lô với API Báo cáo trải nghiệm quảng cáo của Google.
Ví dụ về yêu cầu hàng loạt
POST /batch/v1?key=key HTTP/1.1 Content-Type: multipart/mixed; boundary=batch_aer --batch_aer Content-Type: application/http Content-ID: id1 GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1 --batch_aer Content-Type: application/http Content-ID: id2 GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1 --batch_aer--
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-Type: multipart/mixed; boundary=batch_aer
--batch_aer
Content-Type: application/http
Content-ID: response-id1
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site1",
"mobileSummary": {
"lastChangeTime": "2019-02-05T09:46:26.521747Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2019-02-07T23:07:29.017206Z",
"betterAdsStatus": "FAILING",
"enforcementTime": "2018-02-15T15:00:00Z",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
"filterStatus": "ON"
}
}
--batch_aer
Content-Type: application/http
Content-ID: response-id2
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site2",
"mobileSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
"filterStatus": "OFF"
}
}
--batch_aer--