Yêu cầu theo lô là một yêu cầu HTTP tiêu chuẩn duy nhất chứa nhiều lệnh gọi 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.
Bạn có thể gửi yêu cầu hàng loạt đến batchPath đã chỉ định cho API. batchPath cho Merchant API là batch/{sub-api}/v1. Bạn có thể tìm thấy batchPath cho các API khác trong tài liệu khám phá của chúng.
Sau đây là một số ví dụ về lý do bạn nên xử lý hàng loạt các yêu cầu:
Bạn vừa 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 khi ứng dụng của bạn đang ở chế độ ngoại tuyến và ứng dụng của bạn cần đồng bộ hoá dữ liệu cục bộ với máy chủ.
Việc gửi nhiều yêu cầu song song giúp bạn không phải chờ yêu cầu phụ chậm nhất, từ đó cải thiện thời gian phản hồi của máy chủ và giảm độ trễ.
Viết yêu cầu hàng loạt
Sau đây là yêu cầu mẫu theo lô của Merchant API. Yêu cầu này kết hợp một yêu cầu get để truy xuất kho hàng tại khu vực của một sản phẩm và một yêu cầu insert để cập nhật kho hàng tại khu vực của cùng một sản phẩm. Bạn phải tuân thủ chính xác định dạng của ví dụ:
Sử dụng https://merchantapi.googleapis.com/batch/{sub-api}/v1 làm URL cơ sở.
Chỉ định một ranh giới để phân tách từng yêu cầu lồng nhau, ví dụ: -H
'Content-Type: multipart/mixed,boundary=batch_inventory' \
Phân tách từng yêu cầu lồng nhau bằng ranh giới, ví dụ: --batch_inventory.
Thêm Content-Type: application/http vào đầu mỗi yêu cầu lồng nhau.
Sử dụng Content-ID để gắn nhãn từng yêu cầu lồng nhau bằng mã nhận dạng của riêng bạn. Ví dụ:Content-ID: <get~en~US~123456>.
Thêm một dòng trống giữa tiêu đề, đường dẫn và nội dung của mỗi yêu cầu lồng nhau. Nếu yêu cầu lồng nhau không có nội dung, hãy để một dòng trống trước ranh giới tiếp theo.
Đừng thêm URL cơ sở vào từng yêu cầu riêng lẻ được lồng.
Kết thúc yêu cầu chính bằng một ranh giới cuối cùng, ví dụ: --batch_inventory–.
Các yêu cầu có thể không thực thi theo thứ tự mà bạn chỉ định.
Sử dụng Content-ID để xác định từng yêu cầu.
Nếu bạn cần thực thi các lệnh gọi theo một thứ tự nhất định, hãy gửi riêng từng lệnh gọi và đợi phản hồi cho yêu cầu đầu tiên trước khi gửi yêu cầu tiếp theo.
Đọc phản hồi hàng loạt
Sau đây là ví dụ về một phản hồi hàng loạt HTTP. Thứ tự của các phản hồi có thể không khớp với thứ tự của các yêu cầu. Sử dụng Content-ID để xác định yêu cầu lồng nhau mà mỗi phản hồi lồng nhau thuộc về. Trong các phản hồi, API sẽ thêm tiền tố response- vào mỗi Content-ID.
[[["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-26 UTC."],[[["\u003cp\u003eThe Shopping Content API allows batch requests with multiple entries of different methods (insert, update, delete, custom) within a single request, while the Merchant API requires separate, parallel requests for similar functionality.\u003c/p\u003e\n"],["\u003cp\u003eWhen using client libraries, the Shopping Content API offers a \u003ccode\u003ecustombatch\u003c/code\u003e method, whereas the Merchant API utilizes individual API calls that can be executed concurrently using \u003ccode\u003eApiFuture\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eFor scenarios without client libraries, batching in the Shopping Content API involves a single POST request to a specific batch endpoint with an "entries" array, while the Merchant API uses multipart/mixed requests to combine multiple operations.\u003c/p\u003e\n"]]],[],null,["You can use [batch requests](//cloud.google.com/compute/docs/api/how-tos/batch)\nwith the Merchant API to send multiple HTTP requests in a single API call.\n\nIf you prefer to perform batching with [client\nlibraries](/merchant/api/client-libraries), see [Refactor code for concurrent\nrequests](/merchant/api/guides/compatibility/refactor-concurrent-requests).\n\nA batch request is a single standard HTTP request containing multiple API calls,\nusing the `multipart/mixed` content type. Within the main HTTP request, each\npart contains a nested HTTP request.\n\nYou can send the batch request to the specified `batchPath` for the API. The\n`batchPath` for Merchant API is `batch/{sub-api}/v1`. You can find the\n`batchPath` for other APIs in their [discovery\ndocuments](/discovery/v1/reference/apis).\n\nExamples of reasons to batch your requests include:\n\n- You just started using the API and have a lot of data to upload.\n- A user made changes to data while your application was offline, and your application needs to synchronize local data with the server.\n\nSending multiple requests in parallel prevents you from waiting for the slowest\nsub-request, which improves server response times and reduces latency.\n| **Tip:** For optimal performance of high-throughput tasks like product or inventory updates, we recommend starting with a moderate batch size and then scaling based on your API quota. For the API-specific quotas, see [Quota and\n| limits](/merchant/api/guides/quotas-limits)\n| **Note:** Batching requests doesn't reduce your usage count. If a batch has N individual requests, it counts as N requests against your quota.\n\nWrite a batch request\n\nHere's a sample Merchant API batch request. This request combines a get request\nto retrieve the regional inventory for a product, and an insert request to\nupdate the regional inventory for the same product. You should follow the format\nof the example exactly:\n\n1. Use `https://merchantapi.googleapis.com/batch/{sub-api}/v1` as the base URL.\n2. Specify a boundary to separate each nested request, for example: `-H\n 'Content-Type: multipart/mixed,boundary=batch_inventory' \\`\n3. Separate each nested request with the boundary, for example `--batch_inventory`.\n4. Include `Content-Type: application/http` at the beginning of each nested request.\n5. Use `Content-ID` to label each nested request with your own ID. For example: `Content-ID: \u003cget~en~US~123456\u003e`.\n6. Include a blank line between the header, path and body of each nested request. If the nested request doesn't have a body, leave a blank line before the next boundary.\n7. Don't include the base URL in each individual nested request.\n8. End the main request with a final boundary, for example `--batch_inventory--`.\n\n curl https://merchantapi.googleapis.com/batch/inventories/v1 \\\n -H 'Authorization: Bearer \u003cTOKEN\u003e' \\\n -H 'Content-Type: multipart/mixed,boundary=batch_inventory' \\\n --data '\n --batch_inventory\n Content-Type: application/http\n Content-ID: \u003cget:online:en:US:123456\u003e\n GET /inventories/v1/accounts/123/products/online:en:US:123456/regionalInventories\n --batch_inventory\n Content-Type: application/http\n Content-ID: \u003cpost:online:en:US:123456\u003e\n POST /inventories/v1/accounts/123/products/online:en:US:123456/regionalInventories:insert\n {\n \"region: \"123456\",\n \"price\": {\n \"amountMicros\": \"100000000\",\n \"currencyCode\": \"USD\"\n }\n }\n --batch_inventory--\n '\n\nNotes on ordering\n\n- Requests might not execute in the order you specify them.\n- Use `Content-ID` to identify individual requests.\n- If you need to execute your calls in a given order, send them separately and wait for the response to the first request before sending the next one.\n\nRead a batch response\n\nHere's an example of an HTTP batch response. The order of the responses might\nnot match the order of the requests. Use `Content-ID` to identify the nested\nrequest each nested response belongs to. In the responses, the API adds a\n`response-` prefix to each `Content-ID`. \n\n --batch_inventory\n Content-Type: application/http\n Content-ID: \u003cresponse-get~en~US~123456\u003e\n HTTP/1.1 200 OK\n Content-Type: application/json; charset=UTF-8\n Vary: Origin\n Vary: X-Origin\n Vary: Referer\n {}\n --batch_inventory\n Content-Type: application/http\n Content-ID: \u003cresponse-post~en~US~123456\u003e\n HTTP/1.1 200 OK\n Content-Type: application/json; charset=UTF-8\n Vary: Origin\n Vary: X-Origin\n Vary: Referer\n {\n \"name\": \"accounts/123/products/en~US~123456/regionalInventories/123456\",\n \"region\": \"123456\",\n \"price\": {\n \"amountMicros\": \"100000000\",\n \"currencyCode\": \"USD\"\n }\n }\n --batch_inventory--\n '"]]
