Toplu İstek Gönderme

Bu belgede, istemcinizin kurması gereken HTTP bağlantılarının sayısını azaltmak için API çağrılarını nasıl toplu hale getireceğiniz gösterilmektedir.

Bu belge özellikle HTTP isteği göndererek toplu istek yapma hakkındadır. Bunun yerine, toplu istek yapmak için bir Google istemci kitaplığı kullanıyorsanız istemci kitaplığının dokümanlarına bakın.

Genel bakış

İstemcinizin her bir HTTP bağlantısı, belirli miktarda ek yüke neden olur. Directory API, istemcinizin tek bir HTTP isteğine birkaç API çağrısı koymasına olanak tanımak için toplu işlemi destekler.

Gruplama işlemini kullanabileceğiniz durumlara örnekler:

• API'yi kullanmaya yeni başladınız ve yüklemeniz gereken çok fazla veri var.
• Bir kullanıcı, uygulamanız çevrimdışıyken (internet bağlantısı kesilirken) verilerde değişiklik yaptı, bu yüzden uygulamanızın çok sayıda güncelleme ve silme göndererek yerel verileri sunucuyla senkronize etmesi gerekiyor.

Her durumda, her bir çağrıyı ayrı ayrı göndermek yerine bunları tek bir HTTP isteğinde gruplandırabilirsiniz. Tüm dahili istekler aynı Google API'ye gitmelidir.

Tek bir toplu istekte 1.000 çağrıyla sınırlısınız. Bundan daha fazla çağrı yapmanız gerekiyorsa birden çok toplu istek kullanın.

Not: Directory API'nin toplu işlem sistemi, OData toplu işleme sistemiyle aynı söz dizimini kullanır ancak anlamları farklıdır.

Grup ayrıntıları

Toplu istek, birden fazla API çağrısının bir HTTP isteğinde birleştirilmesinden oluşur ve bu çağrı, API keşif belgesinde belirtilen batchPath öğesine gönderilebilir. Varsayılan yol /batch/api_name/api_version şeklindedir. Bu bölümde toplu söz dizimi ayrıntılı olarak açıklanmaktadır; daha sonra bir örnek bulunacaktır.

Not: Toplu olarak toplanan bir n istek, kullanım sınırınıza tek bir istek olarak değil, n istekleri olarak dahil edilir. Toplu istek, işlenmeden önce bir istek grubuna ayrılır.

Toplu istek biçimi

Toplu istek, multipart/mixed içerik türünü kullanan birden çok 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 bölüm kendi Content-Type: application/http HTTP başlığıyla başlar. İsteğe bağlı bir Content-ID başlığı da olabilir. Bununla birlikte, parça başlıkları sadece parçanın başlangıcını belirtmek için yer alır; iç içe yerleştirilmiş istekten ayrıdır. Sunucu, toplu isteğin sarmalamasını ayrı istekler halinde açtıktan sonra parça başlıkları yoksayılır.

Her bölümün gövdesi, kendine ait yüklemi, URL'si, başlıkları ve gövdesi olan eksiksiz bir HTTP isteğidir. HTTP isteği, yalnızca URL'nin yol kısmını içermelidir; toplu isteklerde tam URL'lere izin verilmez.

Content-Type gibi Content- üstbilgileri hariç olmak üzere dış toplu isteğin HTTP üstbilgileri, toplu işteki her isteğe uygulanır. Hem dış istekte hem de tek bir çağrıda belirli bir HTTP üst bilgisi belirtirseniz bağımsız çağrı başlığının değeri, dış toplu istek başlığının değerini geçersiz kılar. Tek bir aramanın üstbilgileri yalnızca söz konusu çağrı için geçerlidir.

Örneğin, belirli bir çağrı için bir Yetkilendirme üst bilgisi sağlarsanız bu üstbilgi yalnızca söz konusu çağrı için geçerli olur. Dış istek için bir Yetkilendirme üst bilgisi sağlarsanız bu üstbilgi kendi Yetkilendirme başlıklarıyla geçersiz kılınmadığı sürece tek tek tüm çağrılar için geçerli olur.

Sunucu toplu isteği aldığında, her bir bölüme dış isteğin sorgu parametrelerini ve başlıklarını (uygun olduğu şekilde) uygular ve daha sonra, her bölümü ayrı bir HTTP isteği gibi değerlendirir.

Toplu isteğe yanıt verme

Sunucunun yanıtı, multipart/mixed içerik türüne sahip tek bir standart HTTP yanıtıdır; her bir bölüm, istekle aynı sırada, toplu istekteki isteklerden birine verilen yanıttır.

İstekteki parçalar gibi her yanıt bölümü de durum kodu, başlıklar ve gövdeyi içeren tam 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ı belirten bir Content-Type başlığı bulunur.

İsteğin belirli bir kısmının Content-ID başlığı varsa yanıtın ilgili bölümü, aşağıdaki örnekte gösterildiği gibi, orijinal değerin önünde response- dizesinin bulunduğu, eşleşen bir Content-ID başlığına sahip olur.

Not: Sunucu, çağrılarınızı herhangi bir sırada gerçekleştirebilir. Bu anahtar kelimelerin belirttiğiniz sıraya göre yürütülmesine güvenmeyin. İki çağrının belirli bir sırada gerçekleşmesini istiyorsanız bunları tek bir istekte gönderemezsiniz. Bunun yerine, ilk çağrıyı tek başına gönderin, ardından ikinciyi göndermeden önce ilk çağrının yanıtını bekleyin.

Örnek

Aşağıdaki örnekte, Farm API adlı genel (kurgusal) bir demo API'siyle toplu işlemenin kullanımı gösterilmektedir. Ancak aynı kavramlar Directory API için de geçerlidir.

Örnek toplu istek

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

Örnek toplu yanıt

Bu, önceki bölümde yer alan örnek isteğin yanıtıdır.

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