Google Developers blogunda duyurulduğu gibi, toplu işlemeyle ilgili özel bir yaklaşım olan Global HTTP Batch uç noktası (www.googleapis.com/batch) 12 Ağustos 2020'de kullanımdan kaldırılmıştır. Gruplandırmayla ilgili diğer yaklaşımlar bu sayfanın geri kalanında da belirtildiği gibi çalışmaya devam eder. Kodunuzda Global HTTP Batch uç noktası kullanılıyorsa API'ye özel HTTP toplu uç noktaları (www.googleapis.com/batch/API/VERSION) gibi diğer yaklaşımları kullanmaya ilişkin talimatlar için blog yayınına bakın.
Bu dokümanda, istemcinizin kurması gereken HTTP bağlantılarının sayısını azaltmak için API çağrılarını toplu olarak nasıl toplu halde kullanabileceğiniz gösterilmektedir.
Bu belge özel olarak bir HTTP isteği göndererek toplu istek göndermekle ilgilidir. Bunun yerine toplu istek yapmak için Google istemci kitaplığı kullanıyorsanız istemci kitaplığı dokümanlarına bakın.
Genel bakış
İstemcinizin yaptığı her HTTP bağlantısı belirli bir ek yük ile sonuçlanır. Google Mirror API, istemcinizin tek bir HTTP isteğine birden fazla API çağrısı yapabilmesini sağlamak için toplu işlemleri destekler.
Gruplandırmayı kullanmak isteyebileceğiniz durumlara örnekler:
- API'yi kullanmaya başladınız ve yükleyeceğiniz çok fazla veri var.
- Bir kullanıcı, uygulamanız çevrimdışıyken (internetle bağlantısı kesildi) verilerde değişiklik yaptı. Bu nedenle, uygulamanızın çok sayıda güncelleme ve silme göndererek yerel verilerini sunucuyla senkronize etmesi gerekiyor.
Her durumda, her aramayı ayrı ayrı göndermek yerine tek bir HTTP isteği halinde gruplandırabilirsiniz. Dahili isteklerin tümü aynı Google API'sine gönderilmelidir.
Tek bir toplu istekte 1.000 aramayla sınırlısınız. Bundan daha fazla çağrı yapmanız gerekiyorsa birden çok toplu istek kullanın.
Not: Google Mirror API'nın toplu sistemi, OData toplu işleme sistemiyle aynı söz dizimini kullanır, ancak anlamsal farklıdır.
Toplu işlem ayrıntıları
Bir toplu istek, tek bir HTTP isteğinde birleştirilmiş birden fazla API çağrısından oluşur. Bu istekler, API keşif dokümanında belirtilen batchPath özelliğine 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 eklenmiştir.
Not: Bir araya getirilmiş n istek grubu, tek bir istek olarak değil, n istek olarak kullanım sınırınızda hesaba katılır. Toplu istek, işlenmeden önce bir dizi istek içine ayrılır.
Toplu istek biçimi
Toplu istek, multipart/mixed içerik türü kullanılarak birden çok Google Mirror 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 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ığı olabilir. Ancak parça başlıkları, bölümün başlangıcını işaretlemek için bulunur; iç içe yerleştirilmiş istekten ayrıdır. Sunucu, toplu isteği sarmaladıktan sonra parça başlıkları yoksayılır.
Her bölümün gövdesi, kendi fiilini, URL'sini, başlıklarını ve gövdesini içeren tam bir HTTP isteğidir. HTTP isteği, URL'nin yalnızca yol bölümünü içermelidir. Toplu isteklerde tam URL'lere izin verilmez.
Dış grup isteğinin HTTP üstbilgileri (Content-Type gibi Content- üstbilgileri hariç) gruptaki her istek için geçerlidir. Hem harici istekte hem de tek bir çağrıda belirli bir HTTP üst bilgisi belirtirseniz bağımsız arama üstbilgisinin değeri, harici toplu istek başlığının değerini geçersiz kılar. Tek bir aramanın üstbilgileri yalnızca söz konusu görüşmeye uygulanır.
Örneğin, belirli bir çağrı için bir Yetkilendirme üstbilgisi sağlarsanız bu üstbilgi yalnızca o arama için geçerli olur. Harici istek için bir Yetkilendirme başlığı sağlarsanız bu üstbilgi, kendi Yetkilendirme başlıklarıyla geçersiz kılınmadığı sürece ayrı ayrı tüm aramalar için geçerli olur.
Sunucu toplu isteği aldığında harici isteğin sorgu parametrelerini ve başlıklarını (uygun olduğu şekilde) uygular ve her bölüme ayrı bir HTTP isteğiymiş gibi davranır.
Toplu isteğe 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, isteklerle 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övde dahil olmak üzere tam bir HTTP yanıtı içerir. İstekteki parçalarda olduğu gibi, her yanıt bölümünün sonunda, bölümün başlangıcını belirten Content-Type başlığı bulunur.
İsteğin belirli bir bölümünde Content-ID üst bilgisi varsa yanıtın ilgili bölümünde, aşağıdaki örnekte gösterildiği gibi orijinal değer response- dizesinin önünde yer alan eşleşen bir Content-ID başlığı vardır.
Not: Sunucu, aramalarınızı herhangi bir sırada yapabilir. Bu URL'leri belirttiğiniz sırada yürütmelerine güvenmeyin. Belirli bir sırayla iki çağrının gerçekleşmesini sağlamak için bunları tek bir istekte gönderemezsiniz; bunun yerine, ilkini tek başına gönderin, ardından ikincisini göndermeden önce ilkine yanıt verilmesini bekleyin.
Örnek
Aşağıdaki örnekte Google Mirror API ile toplu işlem kullanımı gösterilmektedir.
Örnek toplu istek
POST /batch HTTP/1.1
Content-Length: content_length
content-type: multipart/mixed; boundary="===============7330845974216740156=="
accept-encoding: gzip, deflate
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_1
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_1_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_2
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_2_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_3
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_3_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==--
Örnek toplu yanıt
Bu, önceki bölümde verilen örnek isteğe verilen yanıttır.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Tue, 22 Jan 2013 18:56:00 GMT
Expires: Tue, 22 Jan 2013 18:56:00 GMT
Cache-Control: private, max-age=0
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_1
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "1234567890",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_2
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "0987654321",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_3
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "5432109876",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--