Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Tài liệu này cho biết cách kết hợp 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 chủ yếu nói 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 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 thực hiện sẽ dẫn đến một mức hao tổn nhất định. Directory API hỗ trợ tính năng tạo yêu cầu 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 trường hợp bạn nên sử dụng tính năng xử lý hàng loạt:
Bạn mới bắt đầu sử dụng API và có nhiều dữ liệu cần tải lên.
Người dùng đã thay đổi dữ liệu trong khi ứng dụng của bạn đang ở chế độ ngoại tuyến (đã 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 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 chuyển đến cùng một API của Google.
Bạn chỉ được gửi tối đa 1.000 lệnh gọi trong một yêu cầu hàng loạt. Nếu bạn 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 theo lô.
Lưu ý: Hệ thống xử lý hàng loạt cho Directory API sử dụng cú pháp giống với hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa lại 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 đượ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 đế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 xử lý hàng loạt; sau đó, sẽ có một ví dụ.
Lưu ý: Một nhóm các yêu cầu n được gộp lại với nhau sẽ được tính vào hạn mức sử dụng dưới dạng các yêu cầu n, chứ không phải một yêu cầu. Yêu cầu theo lô đượ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 theo lô
Yêu cầu hàng loạt là một yêu cầu HTTP chuẩn duy nhất chứa nhiều lệnh gọi Directory 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. Tệp 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ỉ dùng để đánh dấu phần bắt đầu; các tiêu đề này 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, 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 theo lô bên ngoài. 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 đó ghi đè tiêu đề đó bằng tiêu đề Uỷ quyền của riêng chúng.
Khi nhận được yêu cầu theo lô, 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 đó coi mỗi phần như một yêu cầu HTTP riêng biệt.
Phản hồi yêu cầu theo lô
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 theo lô, theo thứ tự giống 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 đều có một tiêu đề Content-Type ở phía trước để đá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 tương ứng của phản hồi sẽ có tiêu đề Content-ID khớp, với giá trị ban đầu đứng trước 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 thứ tự bất kỳ. Đừng tin rằng các lệnh 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 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, 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 cho thấy cách sử dụng tính năng xử lý hàng loạt bằng một API minh hoạ chung (hư cấu) có tên là Farm API. Tuy nhiên, các khái niệm tương tự cũng áp dụng cho Directory API.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-08-29 UTC."],[],[],null,["# Sending Batch Requests\n\nThis document shows how to batch API calls together to reduce the number of HTTP connections\nyour client has to make.\n\nThis document is specifically about making a batch request by sending an\nHTTP request. If, instead, you're using a Google client library to make a batch request, see the [client library's documentation](https://developers.google.com/api-client-library/).\n\nOverview\n--------\n\nEach HTTP connection your client makes results in a certain amount of overhead. The Directory API supports batching, to allow your client to put several API calls into a single HTTP request.\n\nExamples of situations when you might want to use batching:\n\n- You've just started using the API and you have a lot of data to upload.\n- A user made changes to data while your application was offline (disconnected from the Internet), so your application needs to synchronize its local data with the server by sending a lot of updates and deletes.\n\nIn each case, instead of sending each call separately, you can group them together into a single HTTP request. All the inner requests must go to the same Google API.\n\nYou're limited to 1000 calls in a single batch request. If you must make more calls than that, use multiple batch requests.\n\n**Note** : The batch system for the Directory API uses the same syntax as the [OData batch processing](http://www.odata.org/documentation/odata-version-3-0/batch-processing/) system, but the semantics differ.\n\n\nBatch details\n-------------\n\nA batch request consists of multiple API calls combined into one HTTP request, which can be sent to the `batchPath` specified in the [API discovery document](https://developers.google.com/discovery/v1/reference/apis). The default path is `/batch/`\u003cvar translate=\"no\"\u003eapi_name\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eapi_version\u003c/var\u003e. This section describes the batch syntax in detail; later, there's an [example](#example).\n\n**Note** : A set of \u003cvar translate=\"no\"\u003en\u003c/var\u003e requests batched together counts toward your usage limit as \u003cvar translate=\"no\"\u003en\u003c/var\u003e requests, not as one request. The batch request is separated into a set of requests before processing.\n\n### Format of a batch request\n\nA batch request is a single standard HTTP request containing multiple Directory API calls, using the `multipart/mixed` content type. Within that main HTTP request, each of the parts contains a nested HTTP request.\n\nEach part begins with its own `Content-Type: application/http` HTTP header. It can also have an optional `Content-ID` header. However, the part headers are just there to mark the beginning of the part; they're separate from the nested request. After the server unwraps the batch request into separate requests, the part headers are ignored.\n\nThe body of each part is a complete HTTP request, with its own verb, URL, headers, and body. The HTTP request must only contain the path portion of the URL; full URLs are not allowed in batch requests.\n\nThe HTTP headers for the outer batch request, except for the `Content-` headers such as `Content-Type`, apply to every request in the batch. If you specify a given HTTP header in both the outer request and an individual call, then the individual call header's value overrides the outer batch request header's value. The headers for an individual call apply only to that call.\n\nFor example, if you provide an Authorization header for a specific call, then that header applies only to that call. If you provide an Authorization header for the outer request, then that header applies to all of the individual calls unless they override it with Authorization headers of their own.\n\nWhen the server receives the batched request, it applies the outer request's query parameters and headers (as appropriate) to each part, and then treats each part as if it were a separate HTTP request.\n\n### Response to a batch request\n\nThe server's response is a single standard HTTP response with a `multipart/mixed` content type; each part is the response to one of the requests in the batched request, in the same order as the requests.\n\nLike the parts in the request, each response part contains a complete HTTP response, including a status code, headers, and body. And like the parts in the request, each response part is preceded by a `Content-Type` header that marks the beginning of the part.\n\nIf a given part of the request had a `Content-ID` header, then the corresponding part of the response has a matching `Content-ID` header, with the original value preceded by the string `response-`, as shown in the following example.\n\n**Note**: The server might perform your calls in any order. Don't count on their being executed in the order in which you specified them. If you want to ensure that two calls occur in a given order, you can't send them in a single request; instead, send the first one by itself, then wait for the response to the first one before sending the second one.\n\nExample\n-------\n\nThe following example shows the use of batching with a generic (fictional) demo API called the Farm API. However, the same concepts apply to the Directory API.\n\n### Example batch request\n\n```\nPOST /batch/farm/v1 HTTP/1.1\nAuthorization: Bearer your_auth_token\nHost: www.googleapis.com\nContent-Type: multipart/mixed; boundary=batch_foobarbaz\nContent-Length: total_content_length\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem1:12930812@barnyard.example.com\u003e\n\nGET /farm/v1/animals/pony\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem2:12930812@barnyard.example.com\u003e\n\nPUT /farm/v1/animals/sheep\nContent-Type: application/json\nContent-Length: part_content_length\nIf-Match: \"etag/sheep\"\n\n{\n \"animalName\": \"sheep\",\n \"animalAge\": \"5\"\n \"peltColor\": \"green\",\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem3:12930812@barnyard.example.com\u003e\n\nGET /farm/v1/animals\nIf-None-Match: \"etag/animals\"\n\n--batch_foobarbaz--\n```\n\n### Example batch response\n\nThis is the response to the example request in the previous section. \n\n```\nHTTP/1.1 200\nContent-Length: response_total_content_length\nContent-Type: multipart/mixed; boundary=batch_foobarbaz\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item1:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 200 OK\nContent-Type application/json\nContent-Length: response_part_1_content_length\nETag: \"etag/pony\"\n\n{\n \"kind\": \"farm#animal\",\n \"etag\": \"etag/pony\",\n \"selfLink\": \"/farm/v1/animals/pony\",\n \"animalName\": \"pony\",\n \"animalAge\": 34,\n \"peltColor\": \"white\"\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item2:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 200 OK\nContent-Type: application/json\nContent-Length: response_part_2_content_length\nETag: \"etag/sheep\"\n\n{\n \"kind\": \"farm#animal\",\n \"etag\": \"etag/sheep\",\n \"selfLink\": \"/farm/v1/animals/sheep\",\n \"animalName\": \"sheep\",\n \"animalAge\": 5,\n \"peltColor\": \"green\"\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item3:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 304 Not Modified\nETag: \"etag/animals\"\n\n--batch_foobarbaz--\n```"]]
