Bu dokümanda, 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 kurduğu her HTTP bağlantısı belirli miktarda ek yük oluşturur. Kişiler API'si, istemcinizin tek bir HTTP isteğine birden fazla API çağrısı eklemesine olanak tanımak için gruplandırmayı destekler.
Gruplandırmayı kullanmak isteyebileceğiniz durumlara örnekler:
- API'yi kullanmaya yeni başladıysanız ve yüklemeniz gereken çok fazla veri varsa.
- Bir kullanıcı, uygulamanız çevrimdışıyken (İnternet'e bağlı değilken) 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 1.000 çağrıyla sınırlısınızdır. Bundan daha fazla arama yapmanız gerekiyorsa birden fazla toplu istek kullanın.
Not: People 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 People 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 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 çağrı için bir Yetkilendirme başlığı sağlarsanız bu başlık yalnızca söz konusu çağrı 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 üst bilgisi varsa yanıtın ilgili bölümünde de eşleşen bir Content-ID üst bilgisi bulunur. Bu üst bilgide, orijinal değerin önünde response- dizesi yer alır (aşağıdaki örnekte gösterildiği gibi).
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, People API ile toplu işlemlerin kullanımı gösterilmektedir.
Örnek toplu istek
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--
Örnek toplu yanıt
Bu, önceki bölümdeki örnek isteğe verilen yanıttır.
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--