Koleksiyonlar ile düzeninizi koruyun
İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
Bu belgede, istemcinizin kurması gereken HTTP bağlantılarının sayısını azaltmak için API çağrılarının nasıl toplu olarak yapılacağı gösterilmektedir.
Bu doküman, özellikle HTTP isteği göndererek toplu istek gönderme hakkındadır. Bunun yerine toplu istek yapmak için bir Google istemci kitaplığı kullanıyorsanız istemci kitaplığının belgelerine bakın.
Genel Bakış
İstemcinizin oluşturduğu her HTTP bağlantısı belirli miktarda ek yük oluşturur. Directory API, istemcinizin tek bir HTTP isteğine birden fazla API çağrısı eklemesine olanak tanımak için toplu hale getirmeyi destekler.
API'yi kullanmaya yeni başladıysanız ve yüklemeniz gereken çok fazla veri varsa.
Bir kullanıcı, uygulamanız çevrimdışıyken (internet bağlantısı kapalıyken) verilerde değişiklik yaptı. Bu nedenle, uygulamanızın çok sayıda güncelleme ve silme işlemi göndererek yerel verilerini sunucuyla senkronize etmesi gerekiyor.
Her durumda, her çağrıyı ayrı ayrı göndermek yerine tek bir HTTP isteğinde gruplandırabilirsiniz. Tüm iç istekler aynı Google API'ye gönderilmelidir.
Tek bir toplu istekte en fazla 1.000 çağrı gönderebilirsiniz. Bundan daha fazla arama yapmanız gerekiyorsa birden fazla toplu istek kullanın.
Not: Directory API'nin toplu sistemi, OData toplu işleme sistemiyle aynı söz dizimini kullanır ancak anlamları farklıdır.
Toplu işlem ayrıntıları
Toplu istek, tek bir HTTP isteğinde birleştirilen birden fazla API çağrısından oluşur. Bu istek, API keşif belgesinde belirtilen batchPath adresine gönderilebilir. Varsayılan yol /batch/api_name/api_version'tir. Bu bölümde toplu söz dizimi ayrıntılı olarak açıklanmaktadır. Ardından bir örnek verilmiştir.
Not: Birlikte gruplandırılmış n istek grubu, kullanım sınırınıza tek bir istek olarak değil, n istek olarak dahil edilir. Toplu istek, işleme alınmadan önce bir dizi isteğe ayrılır.
Toplu istek biçimi
Toplu istek, multipart/mixed içerik türünü kullanan birden fazla Directory API çağrısı içeren tek bir standart HTTP isteğidir. Bu ana HTTP isteğinde, parçaların her biri iç içe yerleştirilmiş bir HTTP isteği içerir.
Her bir parça kendi Content-Type: application/http HTTP başlığıyla başlar. İsteğe bağlı bir Content-ID başlığı da olabilir. Ancak bölüm üst bilgileri yalnızca bölümün başlangıcını işaretlemek içindir ve iç içe yerleştirilmiş istekten ayrıdır. Sunucu, toplu isteği ayrı istekler halinde açtıktan sonra bölüm üst bilgileri yoksayılır.
Her bir parçanın gövdesi, kendi yüklemi, URL'si, başlıkları ve gövdesi ile eksiksiz bir HTTP isteğidir. HTTP isteği yalnızca URL'nin yol bölümünü içermelidir. Toplu isteklerde tam URL'lere izin verilmez.
Content-Type gibi Content- üstbilgileri hariç olmak üzere dış toplu istek için HTTP üstbilgileri, toplu istekteki her istek için geçerlidir. Hem dış istek hem de tek bir çağrıda belirli bir HTTP üst bilgisi belirtirseniz tek bir çağrı üst bilgisinin değeri, dış toplu istek üst bilgisinin değerini geçersiz kılar. Bir aramanın üstbilgileri yalnızca o arama için geçerlidir.
Örneğin, belirli bir arama için bir Yetkilendirme üst bilgisi sağlarsanız bu üstbilgi yalnızca söz konusu arama için geçerli olur. Dış istek için bir Yetkilendirme üst bilgisi sağlarsanız bu üst bilgi, kendi Yetkilendirme üst bilgileriyle geçersiz kılınmadığı sürece tüm ayrı çağrılar için geçerli olur.
Sunucu, toplu isteği aldığında dış isteğinin sorgu parametrelerini ve üst bilgilerini (uygun olduğu şekilde) her bir parçaya uygular ve ardından her bir parçayı ayrı bir HTTP isteği gibi işler.
Toplu istek yanıtı
Sunucunun yanıtı, multipart/mixed içerik türüne sahip tek bir standart HTTP yanıtıdır. Her bölüm, toplu istekteki isteklerden birine verilen yanıttır ve isteklerle aynı sıradadır.
İstekteki parçalar gibi her yanıt parçası da durum kodu, üstbilgiler ve gövde dahil olmak üzere eksiksiz bir HTTP yanıtı içerir. İstekteki bölümler gibi, her yanıt bölümünün önünde bölümün başlangıcını işaretleyen bir Content-Type üstbilgisi bulunur.
İsteğin belirli bir bölümünde Content-ID başlığı varsa yanıtın ilgili bölümünde de eşleşen bir Content-ID başlığı bulunur. Bu başlıkta, orijinal değerin önünde aşağıdaki örnekte gösterildiği gibi response- dizesi bulunur.
Not: Sunucu, çağrılarınızı herhangi bir sırada gerçekleştirebilir. Bu komutların belirttiğiniz sırayla yürütüleceğini varsaymayın. İki çağrının belirli bir sırada gerçekleşmesini istiyorsanız bunları tek bir istekle gönderemezsiniz. Bunun yerine, ilkini tek başına gönderin ve ikinciyi göndermeden önce ilk çağrıya verilen yanıtı bekleyin.
Örnek
Aşağıdaki örnekte, Farm API adlı genel (hayali) bir demo API ile toplu işlemlerin kullanımı gösterilmektedir. Ancak Directory API için de aynı kavramlar geçerlidir.
[[["Anlaması kolay","easyToUnderstand","thumb-up"],["Sorunumu çözdü","solvedMyProblem","thumb-up"],["Diğer","otherUp","thumb-up"]],[["İhtiyacım olan bilgiler yok","missingTheInformationINeed","thumb-down"],["Çok karmaşık / çok fazla adım var","tooComplicatedTooManySteps","thumb-down"],["Güncel değil","outOfDate","thumb-down"],["Çeviri sorunu","translationIssue","thumb-down"],["Örnek veya kod sorunu","samplesCodeIssue","thumb-down"],["Diğer","otherDown","thumb-down"]],["Son güncelleme tarihi: 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```"]]
