Toplu işlemeye yönelik belirli bir yaklaşım olan Global HTTP Batch uç noktası (www.googleapis.com/batch), 12 Ağustos 2020'de Google Developers blogunda duyurulduğu üzere kullanımdan kaldırılmıştır. Bu sayfanın geri kalanında belirtildiği gibi, toplu işlemeye yönelik diğer yaklaşımlar da ç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 geçişle ilgili 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ı bir araya nasıl getirebileceğiniz gösterilmektedir.
Bu belge, özellikle HTTP isteği göndererek toplu istek göndermeyle ilgilidir. Bunun yerine toplu istek yapmak için bir 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ü beraberinde getirir. Google Reklam Deneyimi Raporu API'si, istemcinizin tek bir HTTP isteğine birkaç API çağrısı yapmasını sağlamak için toplu işlemleri destekler.
Gruplandırma kullanmak isteyebileceğiniz durumlara örnekler:
- API'yi kullanmaya yeni başladınız ve yükleyeceğiniz çok sayıda veri var.
- Bir kullanıcı, uygulamanız çevrimdışıyken (internetle bağlantısı kesildi) verilerde değişiklik yaptı. Bu nedenle çok sayıda güncelleme ve silme işlemi yaparak uygulamanızın yerel verilerini sunucuyla senkronize etmesi gerekiyor.
Her durumda, her aramayı ayrı ayrı göndermek yerine tek bir HTTP isteği altında gruplandırabilirsiniz. Dahili isteklerin tümü aynı Google API'ye gitmelidir.
Tek bir toplu istekte 1.000 aramayla sınırlısınız. Bundan daha fazla arama yapmanız gerekiyorsa birden fazla toplu istek kullanın.
Not: Google Reklam Deneyimi Raporu API'sinin toplu sistemi, OData toplu işleme sistemiyle aynı söz dizimini kullanır ancak anlamsal açıdan farklıdır.
Toplu işlem ayrıntıları
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 öğesine gönderilebilir. Varsayılan yol /batch/api_name/api_version şeklindedir. Bu bölümde, toplu söz dizimi ayrıntılı bir şekilde açıklanmaktadır; daha sonra bir örnek verilmiştir.
Not: Bir araya getirilmiş n istek grubu, tek bir istek olarak değil n istek olarak kullanım sınırınıza dahil edilir. Toplu istek, işlenmeden önce bir dizi istek için ayrılır.
Toplu isteğin biçimi
Toplu istek, multipart/mixed içerik türü kullanılarak birden fazla Google Reklam Deneyimi Raporu 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 üst bilgisi ile başlar. Ayrıca isteğe bağlı bir Content-ID üstbilgisi de olabilir. Bununla birlikte, parça başlıkları parçanın başlangıcını işaretlemek için kullanılır ve iç içe yerleştirilmiş istekten ayrıdır. Sunucu, toplu isteği sarmalayarak ayrı isteklere getirdikten sonra, bölüm başlıkları yoksayılır.
Her bölümün gövdesi, kendi filiğini, URL'sini, üstbilgilerini ve gövdesini içeren tam bir HTTP isteğidir. HTTP isteği, URL'nin yalnızca yol kısmını içermelidir. Toplu isteklerde tam URL'lere izin verilmez.
Harici toplu isteğin HTTP üstbilgileri (Content-Type gibi Content- üstbilgileri hariç) gruptaki her istek için geçerlidir. Hem dış istekte hem de tek bir aramada belirli bir HTTP üstbilgisi belirtirseniz her bir bağımsız arama üstbilgisi değeri, harici toplu istek üstbilgisinin değerini geçersiz kılar. Tek bir aramanın üstbilgileri yalnızca söz konusu aramaya uygulanır.
Örneğin, belirli bir arama için Yetkilendirme üst bilgisi sağlarsanız bu üstbilgi yalnızca söz konusu arama için geçerli olur. Harici istek için bir Yetkilendirme başlığı sağlarsanız bu başlık, kendi Yetkilendirme başlıklarıyla geçersiz kılınmadığı sürece her bir çağrı 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 bölüme uygular ve daha sonra her bölümü ayrı bir HTTP isteğiymiş gibi işler.
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 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, üstbilgiler 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ünden önce parçanın başlangıcını belirten bir 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, ilk olarak response- dizesinin önünde yer alan orijinal değerle eşleşen bir Content-ID üst bilgisi bulunur.
Not: Sunucu, çağrılarınızı istediğiniz sırayla gerçekleştirebilir. Belirttiğiniz sırayla bunların yürütülmesine güvenmeyin. Belirli bir sırada iki çağrının gerçekleşmesini sağlamak istiyorsanız bunları tek bir istekte gönderemezsiniz. Bunun yerine, ilk çağrıyı tek başına gönderebilir, ardından ikincisini göndermeden önce ilkinin yanıtını beklersiniz.
Örnek
Aşağıdaki örnekte, Google Reklam Deneyimi Raporu API'siyle toplu kullanımı gösterilmektedir.
Örnek toplu istek
POST /batch/v1?key=key HTTP/1.1 Content-Type: multipart/mixed; boundary=batch_aer --batch_aer Content-Type: application/http Content-ID: id1 GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1 --batch_aer Content-Type: application/http Content-ID: id2 GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1 --batch_aer--
Örnek toplu yanıt
Bu, önceki bölümdeki örnek isteğin yanıtıdır.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_aer
--batch_aer
Content-Type: application/http
Content-ID: response-id1
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site1",
"mobileSummary": {
"lastChangeTime": "2019-02-05T09:46:26.521747Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2019-02-07T23:07:29.017206Z",
"betterAdsStatus": "FAILING",
"enforcementTime": "2018-02-15T15:00:00Z",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
"filterStatus": "ON"
}
}
--batch_aer
Content-Type: application/http
Content-ID: response-id2
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site2",
"mobileSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
"filterStatus": "OFF"
}
}
--batch_aer--