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 bir HTTP isteği göndererek toplu istek oluşturmakla ilgilidir. 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 oluşturduğu her HTTP bağlantısı belirli bir miktarda ek yüke neden olur. People API, istemcinizin tek bir HTTP isteğine birkaç API çağrısı koymasına olanak tanımak için toplu işlemi destekler.
Gruplandırmayı kullanmak isteyebileceğ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 (internetten bağlantısı kesilirken) verilerde değişiklik yapmıştır. Bu nedenle, uygulamanızın çok sayıda güncelleme ve silme göndererek yerel verilerini sunucuyla senkronize etmesi gerekir.
Her durumda, her bir çağrıyı ayrı ayrı göndermek yerine bunları tek bir HTTP isteğinde gruplayabilirsiniz. Dahili istekler aynı Google API'ye yönlendirilmelidir.
Tek bir toplu istekte en fazla 1.000 çağrı yapabilirsiniz. Bundan daha fazla çağrı yapmanız gerekiyorsa birden çok toplu istek kullanın.
Not: People 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, API keşif belgesinde belirtilen batchPath
öğesine gönderilebilen bir HTTP isteğinde birleştirilen birden fazla API çağrısından oluşur. 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 vardır.
Not: Toplu olarak toplanan bir n istek kümesi, 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 isteğin biçimi
Toplu istek, multipart/mixed
içerik türünü kullanan birden çok 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 bölüm kendi Content-Type: application/http
HTTP başlığıyla başlar. Ayrıca, isteğe bağlı bir Content-ID
başlığı da içerebilir. Bununla birlikte, parça başlıkları yalnızca bölümün başlangıcını işaretlemek için yer alır; iç içe yerleştirilmiş istekten ayrıdır. Sunucu, toplu isteğin sarmalamasını ayrı istekler şeklinde açtıktan sonra parça başlıkları yok sayılır.
Her bölümün gövdesi, kendi yüklemi, URL'si, başlıkları ve gövdesi ile birlikte 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 başlığı 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 arama için geçerlidir.
Örneğin, belirli bir çağrı için bir Yetkilendirme başlığı 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 başlık, kendi Yetkilendirme başlıklarıyla geçersiz kılınmadığı sürece tüm çağrılar için geçerli olur.
Sunucu toplu isteği aldığında, dış isteğin sorgu parametrelerini ve başlıklarını (uygun olduğu şekilde) her bir parçaya uygular ve ardından her bölümü ayrı bir HTTP isteğiymiş gibi ele alır.
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 parça, isteklerle aynı sırayla toplu istekteki isteklerden birine verilen yanıttır.
İstekteki bölümler gibi, her yanıt bölümü de durum kodu, başlıklar ve gövdeyi içeren eksiksiz bir HTTP yanıtı içerir. İstekteki bölümlerde olduğu 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 bölümünde Content-ID
başlığı varsa yanıtın ilgili bölümü, aşağıdaki örnekte gösterildiği gibi önünde response-
dizesinden önce gelen orijinal değer ile eşleşen bir Content-ID
başlığına sahiptir.
Not: Sunucu, çağrılarınızı herhangi bir sırada gerçekleştirebilir. Bu kodların sizin belirttiğiniz sırayla yürütüldüğüne güvenin. Belirli bir sırada iki çağrının gerçekleşmesini istiyorsanız bunları tek bir istekte gönderemezsiniz. Bunun yerine, ilki tek başına gönderin, ardından ikinciyi göndermeden önce ilkinin yanıtını bekleyin.
Örnek
Aşağıdaki örnekte, People API ile toplu işlemenin 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ümde yer alan örnek isteğin yanıtıdı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--