Phương pháp tạo lô cụ thể là điểm cuối HTTP theo nhóm (www.googleapis.com/batch) sẽ ngừng hoạt động vào ngày 12 tháng 8 năm 2020, như đã thông báo trên blog của Google Developers. Các phương pháp xử lý hàng loạt khác vẫn hoạt động, như 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 theo nhóm 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ư điểm cuối hàng loạt HTTP dành riêng cho API
(www.googleapis.com/batch/API/VERSION).
Tài liệu này cho biết 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ể 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. Thay vào đó, nếu bạn đang sử dụng thư viện ứng dụng Google để thực hiện yêu cầu hàng loạt, hãy xem tài liệu của thư viện ứng dụng.
Tổng quan
Mỗi kết nối HTTP mà ứng dụng của bạn tạo ra sẽ dẫn đến một mức hao tổn nhất định. Google Mirror API hỗ trợ việc tạo yêu cầu hàng loạt để cho phép ứng dụng của bạn thực hiện một số lệnh gọi API vào một yêu cầu HTTP.
Ví dụ về các trường hợp bạn nên sử dụng lô:
- Bạn vừa bắt đầu sử dụng API và bạn có nhiều dữ liệu cần tải lên.
- Người dùng đã thực hiện các thay đổi đối với dữ liệu khi ứng dụng của bạn ngoại tuyến (bị ngắt kết nối khỏi Internet), vì vậy ứng dụng 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 bản cập nhật và xóa.
Trong mỗi trường hợp, thay vì gửi riêng từng cuộc gọi, bạn có thể nhóm các cuộc gọi lại với nhau thành một yêu cầu HTTP duy nhất. Tất cả yêu cầu nội bộ phải thuộc cùng một API Google.
Bạn chỉ được gửi 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 số lượng đó, hãy sử dụng nhiều yêu cầu hàng loạt.
Lưu ý: Hệ thống lô cho Google Mirror API 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 được kết hợp thành một yêu cầu HTTP và có thể gửi đến 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ô; sau đó sẽ có 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 là 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 tách thành một nhóm 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 có chứa nhiều lệnh gọi Google Mirror API, 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. Tiêu đề này cũng có thể có tiêu đề Content-ID không bắt buộc. Tuy nhiên, tiêu đề phần chỉ ở đó để đá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ủ 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 thân 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 các yêu cầu hàng loạt.
Tiêu đề HTTP cho yêu cầu hàng loạt bên ngoài, ngoại trừ 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 đề lệnh 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 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 lệnh gọi cụ thể, thì tiêu đề đó 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ừ khi các lệnh gọi đó ghi đè các tiêu đề Uỷ quyền của riêng họ.
Khi nhận được yêu cầu hàng loạt, máy chủ sẽ áp dụng các tham số truy vấn và tiêu đề 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 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 với loại nội dung multipart/mixed; mỗi phần là phản hồi của một trong các yêu cầu trong yêu cầu hàng loạt, theo cùng thứ tự như 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 cả 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 trước một tiêu đề Content-Type đánh dấu phần bắt đầ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 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 cuộc gọi của bạn theo thứ tự bất kỳ. Đừng tính đến việc các lệnh này đượ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 xảy ra theo một thứ tự nhất định, thì bạn không thể gửi các lệnh gọi này trong một yêu cầu duy nhất. Thay vào đó, hãy gửi một lệnh gọi đầu tiên, sau đó chờ phản hồi đầu tiên trước khi 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 Google Mirror.
Ví dụ về yêu cầu hàng loạt
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==--
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_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=--