Tài liệu này cho biết cách gộp các lệnh gọi API 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 tạo yêu cầu hàng loạt bằng cách gửi 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 thực hiện sẽ dẫn đến một mức hao tổn nhất định. API Nhân dân hỗ trợ phân lô để cho phép ứng dụng khách đư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 có thể cần sử dụng tính năng phân lô:
- Bạn mới bắt đầu sử dụng API và có nhiều dữ liệu để tải lên.
- Một người dùng đã thay đổi dữ liệu khi ứng dụng của bạn không có kết nối mạng (bị ngắt kết nối với Internet), vì vậy, ứng dụng cần đồng bộ hoá dữ liệu cục bộ với máy chủ bằng cách gửi nhiều nội dung 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 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 API Google.
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 cần thực hiện nhiều lệnh gọi hơn con số đó, 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 Người dùng sử dụng cú pháp giống như hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa khác nhau.
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 đế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ô; ở phần sau sẽ có ví dụ.
Lưu ý: Một nhóm các yêu cầu n được gộp 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 là 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 tiêu chuẩn chứa nhiều lệnh gọi API Người dùng, 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 đề của 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 được lồng. 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, 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.
Tiêu đề HTTP cho yêu cầu theo lô 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 lô ngoài. Tiêu đề của 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 đề đó sẽ 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 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 đó ghi đè tiêu đề đó bằng tiêu đề Uỷ quyền của chính chúng.
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.
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 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 theo lô, theo đúng thứ 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ã 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 cụ thể 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, có 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 lệnh gọi của bạn theo thứ tự bất kỳ. Không tính vào việc các lệnh đó đượ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, 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 lệnh gọi đầu tiên, sau đó đợi phản hồi cho lệnh gọi đầu tiên trước khi gửi lệnh 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 Mọi người.
Ví dụ về yêu cầu hàng loạt
POST /batch HTTP/1.1 accept-encoding: gzip, deflate Authorization: Bearer your_auth_token Content-Type: multipart/mixed; boundary="batch_people" Content-Length: total_content_length--batch_people Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 1
POST /v1/people:createContact HTTP/1.1 Content-Type: application/json Content-Length: part_content_length Accept: application/json { "names": [{ "givenName": "John", "familyName": "Doe" }] }
--batch_people Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 2
GET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1 Accept: application/json --batch_people--
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_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Date: Tue, 22 Jan 2020 18:56:00 GMT Expires: Tue, 22 Jan 2020 18:56:00 GMT Cache-Control: private--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "resourceName": "people/c11111111111111", "etag": "1111", "names": [{ "givenName": "John", "familyName": "Doe" }] }
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "resourceName": "people/c123456789012345", "etag": "1234", "emailAddresses": [{ "value": "jane.doe@gmail.com" }] } --batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--