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. Google Search Console 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: Google Search Console API için 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 Google Search Console 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, Çiftlik API'si adı verilen genel (kurgusal) bir demo API ile toplu oluşturma işleminin kullanımı gösterilmektedir. Ancak aynı kavramlar Google Search Console 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:12930812@barnyard.example.com> GET /farm/v1/animals/pony --batch_foobarbaz Content-Type: application/http Content-ID: <item2:12930812@barnyard.example.com> 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:12930812@barnyard.example.com> 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:12930812@barnyard.example.com> 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:12930812@barnyard.example.com> 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:12930812@barnyard.example.com> HTTP/1.1 304 Not Modified ETag: "etag/animals" --batch_foobarbaz--