Yêu cầu hàng loạt

Tài liệu này cho biết cách gộp nhóm các 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 trình bày cụ thể về việc thực hiện yêu cầu theo lô 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 của bạn tạo ra sẽ dẫn đến một mức hao tổn nhất định. API Gmail hỗ trợ tính năng tạo lô, cho phép ứng dụ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ô:

• Bạn vừa bắt đầu sử dụng API này 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 không kết nối mạng (ngắt 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 nội dung cập nhật và xoá.

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 phép thực hiện tối đa 100 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 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 Gmail sử dụng cú pháp giống như hệ thống xử lý hàng loạt OData, nhưng về mặt ngữ nghĩa thì khác.

Lưu ý: Kích thước lô lớn hơn có khả năng kích hoạt giới hạn số lượng yêu cầu. Bạn không nên gửi những 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. 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 cú pháp hàng loạt; ở phần sau, sẽ có ví dụ.

Lưu ý: Một nhóm các yêu cầu n được gộp chung với nhau sẽ 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 dưới dạng 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 Gmail, 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. Tệp này cũng có thể có một tiêu đề Content-ID (không bắt buộc). Tuy nhiên, các 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 đượ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.

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; URL đầy đủ không được phép 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 cho trước 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 đề của yêu cầu hàng loạt bên 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 lệnh 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ẽ được áp dụng cho tất cả các lệnh gọi riêng lẻ trừ khi chúng ghi đè tiêu đề đó bằng tiêu đề Uỷ quyền của chính lệnh gọi đó.

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 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à một phản hồi HTTP đơn chuẩn có kiểu 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 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 đều 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 được đứng sau bằng một tiêu đề Content-Type đánh dấu sự bắt đầ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 các lệnh gọi của bạn theo bất kỳ thứ tự nào. Không tin vào việc các chuỗi đó đượ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 thứ tự nhất định, bạn không thể gửi các lệnh gọi này trong một yêu cầu; thay vào đó, hãy tự gửi lệnh đầ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 cho thấy việc sử dụng tính năng tạo lô với một API minh hoạ chung (giả tưởng) được gọi là API nông trại. Tuy nhiên, các khái niệm tương tự cũng áp dụng cho API Gmail.

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