بچینگ درخواست ها
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
این سند نشان می‌دهد که چگونه می‌توانید تماس‌های API را با هم دسته‌بندی کنید تا تعداد اتصالات HTTP را که کلاینت‌تان باید برقرار کند، کاهش دهید.
این سند به طور خاص در مورد ایجاد یک درخواست دسته ای با ارسال یک درخواست HTTP است. اگر در عوض، از کتابخانه سرویس گیرنده Google برای درخواست دسته ای استفاده می کنید، به مستندات کتابخانه سرویس گیرنده مراجعه کنید.
نمای کلی
هر اتصال HTTP مشتری شما منجر به مقدار معینی سربار می شود. People API از دسته بندی پشتیبانی می کند تا به مشتری شما اجازه دهد چندین تماس API را در یک درخواست HTTP قرار دهد.
نمونه هایی از موقعیت هایی که ممکن است بخواهید از دسته بندی استفاده کنید:
- شما به تازگی استفاده از API را شروع کرده اید و داده های زیادی برای آپلود دارید.
- زمانی که برنامه شما آفلاین بود (ارتباط با اینترنت قطع شده بود)، کاربر تغییراتی را در داده‌ها ایجاد کرد، بنابراین برنامه شما باید داده‌های محلی خود را با ارسال به‌روزرسانی‌ها و حذف‌های زیادی با سرور همگام‌سازی کند.
در هر مورد، به جای ارسال هر تماس جداگانه، می توانید آنها را در یک درخواست HTTP با هم گروه بندی کنید. همه درخواست‌های داخلی باید به همان Google API بروند.
شما به 1000 تماس در یک درخواست دسته ای محدود هستید. اگر باید بیشتر از آن تماس بگیرید، از چندین درخواست دسته ای استفاده کنید.
توجه : سیستم دسته‌ای برای People API از نحوی مشابه با سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معنایی متفاوت است.
جزئیات دسته
یک درخواست دسته ای شامل چندین تماس API است که در یک درخواست HTTP ترکیب شده اند، که می تواند به batchPath مشخص شده در سند کشف API ارسال شود. مسیر پیش فرض /batch/ api_name / api_version است. این بخش نحو دسته ای را به تفصیل شرح می دهد. بعداً، یک مثال وجود دارد.
توجه : مجموعه‌ای از n درخواست که با هم جمع شده‌اند به عنوان n درخواست به حساب می‌آیند، نه به عنوان یک درخواست. درخواست دسته ای قبل از پردازش به مجموعه ای از درخواست ها جدا می شود.
درخواست دسته ای یک درخواست استاندارد HTTP است که شامل چندین تماس People API است که از نوع محتوای multipart/mixed استفاده می کند. در آن درخواست اصلی HTTP، هر یک از بخش ها حاوی یک درخواست HTTP تو در تو است.
هر قسمت با هدر Content-Type: application/http HTTP. همچنین می تواند یک هدر Content-ID اختیاری داشته باشد. با این حال، سرصفحه‌های قسمت فقط برای علامت‌گذاری ابتدای قسمت وجود دارد. آنها جدا از درخواست تودرتو هستند. پس از اینکه سرور درخواست دسته ای را به درخواست های جداگانه باز می کند، سرصفحه های قسمت نادیده گرفته می شوند.
بدنه هر قسمت یک درخواست HTTP کامل است که فعل، URL، سرصفحه و بدنه خاص خود را دارد. درخواست HTTP فقط باید شامل قسمت مسیر URL باشد. URL های کامل در درخواست های دسته ای مجاز نیستند.
سرصفحه های HTTP برای درخواست دسته ای خارجی، به جز سرصفحه های Content- مانند Content-Type ، برای هر درخواست در دسته اعمال می شود. اگر یک هدر HTTP داده شده را هم در درخواست بیرونی و هم در یک تماس فردی مشخص کنید، آنگاه مقدار سرصفحه تماس منفرد بر مقدار سرصفحه درخواست دسته ای خارجی لغو می شود. سرصفحه های یک تماس فردی فقط برای آن تماس اعمال می شود.
به عنوان مثال، اگر یک سرصفحه مجوز برای یک تماس خاص ارائه کنید، آن هدر فقط برای آن تماس اعمال می شود. اگر یک سرصفحه مجوز برای درخواست خارجی ارائه دهید، آن هدر برای همه تماس‌های فردی اعمال می‌شود، مگر اینکه آنها آن را با سرصفحه‌های مجوز خود لغو کنند.
هنگامی که سرور درخواست دسته‌ای را دریافت می‌کند، پارامترهای پرس و جو و هدرهای درخواست بیرونی (در صورت لزوم) را برای هر قسمت اعمال می‌کند و سپس با هر قسمت به‌گونه‌ای رفتار می‌کند که گویی یک درخواست HTTP جداگانه است.
پاسخ به درخواست دسته ای
پاسخ سرور یک پاسخ استاندارد HTTP واحد با نوع محتوای multipart/mixed است. هر قسمت پاسخ به یکی از درخواست‌های موجود در درخواست دسته‌ای است، به همان ترتیب درخواست‌ها.
مانند بخش‌های موجود در درخواست، هر بخش پاسخ شامل یک پاسخ HTTP کامل، از جمله کد وضعیت، سرصفحه‌ها و بدنه است. و مانند قسمت‌های درخواست، قبل از هر بخش پاسخ، یک هدر Content-Type وجود دارد که شروع قسمت را مشخص می‌کند.
اگر قسمت معینی از درخواست دارای هدر Content-ID باشد، قسمت مربوطه از پاسخ دارای یک سرآیند Content-ID منطبق است که مقدار اصلی قبل از string response- قرار دارد، همانطور که در مثال زیر نشان داده شده است.
توجه : سرور ممکن است تماس های شما را به هر ترتیبی انجام دهد. روی اجرای آنها به ترتیبی که آنها را مشخص کردید حساب نکنید. اگر می‌خواهید اطمینان حاصل کنید که دو تماس با یک ترتیب مشخص انجام می‌شوند، نمی‌توانید آنها را در یک درخواست ارسال کنید. در عوض، اولی را به تنهایی ارسال کنید، سپس قبل از ارسال دومی منتظر پاسخ به اولی باشید.
مثال
مثال زیر استفاده از دسته بندی با People API را نشان می دهد.
نمونه درخواست دسته ای
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--
نمونه پاسخ دسته ای
این پاسخ به درخواست مثال در بخش قبل است.
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--
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eBatching in the People API allows combining multiple API calls into a single HTTP request to reduce overhead.\u003c/p\u003e\n"],["\u003cp\u003eUse batching for scenarios like initial data uploads or synchronizing offline changes.\u003c/p\u003e\n"],["\u003cp\u003eA batch request uses the \u003ccode\u003emultipart/mixed\u003c/code\u003e content type and nests individual API calls as parts.\u003c/p\u003e\n"],["\u003cp\u003eThe server processes each part of the batch request as a separate HTTP request, but the order of execution isn't guaranteed.\u003c/p\u003e\n"],["\u003cp\u003eThe batch response is also \u003ccode\u003emultipart/mixed\u003c/code\u003e, with each part corresponding to the response of an individual call in the request.\u003c/p\u003e\n"]]],["Batching API calls consolidates multiple requests into a single HTTP request, reducing overhead. This method is useful for initial data uploads or synchronizing offline data. A batch request, limited to 1000 calls, uses `multipart/mixed` and contains nested HTTP requests. Each part has `Content-Type: application/http` header, with the body as a complete HTTP request (path portion only). The server returns a `multipart/mixed` response with individual HTTP responses. Outer request headers apply to all, but individual call headers can override them.\n"],null,["# Batching 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 People 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 People 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 People 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 the People API.\n\n### Example batch request\n\n```\nPOST /batch HTTP/1.1\naccept-encoding: gzip, deflate\nAuthorization: Bearer your_auth_token\nContent-Type: multipart/mixed; boundary=\"batch_people\"\nContent-Length: total_content_length\n\n--batch_people\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: 1\n\nPOST /v1/people:createContact HTTP/1.1\nContent-Type: application/json\nContent-Length: \u003cvar translate=\"no\"\u003epart_content_length\u003c/var\u003e\nAccept: application/json\n{\n \"names\": [{ \"givenName\": \"John\", \"familyName\": \"Doe\" }]\n}\n\n--batch_people\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: 2\n\nGET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1\nAccept: application/json\n--batch_people--\n\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 OK\nContent-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nDate: Tue, 22 Jan 2020 18:56:00 GMT\nExpires: Tue, 22 Jan 2020 18:56:00 GMT\nCache-Control: private\n\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nContent-Type: application/http\nContent-ID: response-1\n\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=UTF-8\n{\n \"resourceName\": \"people/c11111111111111\",\n \"etag\": \"1111\",\n \"names\": [{ \"givenName\": \"John\", \"familyName\": \"Doe\" }]\n}\n\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nContent-Type: application/http\nContent-ID: response-2\n\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=UTF-8\n{\n \"resourceName\": \"people/c123456789012345\",\n \"etag\": \"1234\",\n \"emailAddresses\": [{ \"value\": \"jane.doe@gmail.com\" }]\n}\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--\n\n```"]]
