Yêu cầu theo lô

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ề cách tạo yêu cầu hàng loạt bằng cách gửi yêu cầu HTTP. Nếu bạn đang sử dụng thư viện ứng dụng của Google để tạo 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 thực hiện đều dẫn đến một lượng chi phí nhất định. Gmail API hỗ trợ tính năng nhóm hàng loạt để cho phép ứng dụng của bạn đưa một số lệnh gọi API vào một yêu cầu HTTP duy nhất.

Ví dụ về các tình huống mà bạn có thể muốn sử dụng tính năng nhóm hàng loạt:

• Bạn vừa bắt đầu sử dụng API và có nhiều dữ liệu cần tải lên.
• Một người dùng đã thay đổi dữ liệu trong khi ứng dụng của bạn đang ở trạng thái ngoại tuyến (không kết nối với Internet), vì vậy, ứng dụng của bạn cần đồng bộ hoá 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à lệnh xoá.

Trong mỗi trường hợp, thay vì gửi từng lệnh gọi riêng biệt, 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 bên trong phải được gửi đến cùng một API của Google.

Bạn chỉ được thực hiện tối đa 100 lệnh gọi trong một yêu cầu hàng loạt. Nếu phải thực hiện nhiều lệnh gọi hơn, 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 Gmail sử dụng cùng một cú pháp như hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa thì khác.

Lưu ý: Kích thước lô lớn hơn có thể kích hoạt tính năng giới hạn tốc độ. Bạn không nên gửi các lô lớn hơn 50 yêu cầu.

Chi tiết gói

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, 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 cú pháp hàng loạt; sau đó, sẽ có một ví dụ.

Lưu ý: Một tập hợp gồm n yêu cầu đượ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 tập hợp các 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 duy nhất chứa nhiều lệnh gọi Gmail API, sử dụng loại nội dung multipart/mixed. Trong yêu cầu HTTP chính đó, mỗi phần 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. Nó 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ỉ dùng để đánh dấu phần bắt đầu; chúng tách biệt với yêu cầu lồng nhau. Sau khi máy chủ giải nén yêu cầu hàng loạt thành các yêu cầu riêng biệt, các tiêu đề 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; 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 hàng loạt 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 đề 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. Các tiêu đề cho một lệnh gọi riêng lẻ 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 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ừ phi các lệnh gọi này ghi đè tiêu đề đó bằng tiêu đề Uỷ quyền của riêng chúng.

Khi máy chủ nhận được yêu cầu được nhóm 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 biệt.

Phản hồi 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 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 được nhóm hàng loạt, theo cùng thứ tự với 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 đều được đặt trước một tiêu đề Content-Type đánh dấu phần bắt đầu.

Nếu một phần nhất định của yêu cầu có tiêu đề Content-ID, thì phần phản hồi tương ứng sẽ có tiêu đề Content-ID khớp, với giá trị ban đầu được đặt trước chuỗi response-, như minh hoạ 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 bất kỳ thứ tự nào. Đừng tin rằng các lệnh gọi này 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 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 duy nhất; thay vào đó, hãy gửi lệnh gọi đầu tiên riêng biệt, sau đó đợ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 minh hoạ cách sử dụng tính năng nhóm hàng loạt với một API bản minh hoạ (giả định) chung có tên là Farm API. Tuy nhiên, các khái niệm tương tự cũng áp dụng cho Gmail API.

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

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:[e-mail]>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

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
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:[e-mail]>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:[e-mail]>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--