Toplu İstek Gönderme

Bu belgede, istemcinizin kurması gereken HTTP bağlantılarının sayısını azaltmak için API çağrılarının nasıl birlikte gönderileceği gösterilmektedir.

Bu doküman, ö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ığının dokümanlarına bakın.

Genel Bakış

İstemcinizin kurduğu her HTTP bağlantısı belirli miktarda ek yük oluşturur. Google Search Console API, 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 (internet bağlantısı kesilmişken) verilerde değişiklik yaptığından, uygulamanızın çok sayıda güncelleme ve silme göndererek yerel verilerini sunucuyla senkronize etmesi gerekir.

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 en fazla 1.000 çağrı gönderebilirsiniz. Bundan daha fazla arama yapmanız gerekiyorsa birden fazla toplu istek kullanın.

Not: Google Search Console 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, API keşif dokümanında belirtilen batchPath öğesine gönderilebilecek bir HTTP isteğinde birleştirilen birden çok 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. Ardından bir örnek verilmiştir.

Not: Gruplandırılmış n istekleri, kullanım sınırınıza tek bir istek olarak değil n isteği olarak dahil edilir. Toplu istek, işlenmeden önce bir dizi isteğe ayrılır.

Toplu istek biçimi

Toplu istek, multipart/mixed içerik türünü kullanan birden fazla 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 parça kendi Content-Type: application/http HTTP başlığıyla başlar. Ayrıca isteğe bağlı bir Content-ID başlığı da olabilir. Bununla birlikte, bölüm başlıkları yalnızca bölümün başlangıcını belirtmek için bulunur; 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 bölümü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 kısmı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 arama için bir Yetkilendirme üst bilgisi sağlarsanız bu üstbilgi yalnızca söz konusu arama 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ğin sorgu parametrelerini ve başlıklarını (uygun şekilde) her bölüme uygular ve daha sonra, her bir bölümü ayrı bir HTTP isteğiymiş gibi değerlendirir.

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ümlerde olduğu gibi, her yanıt bölümünün önünde, bölümün başlangıcını işaret eden 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 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, Farm API adlı genel (hayali) bir demo API ile toplu işlemlerin kullanımı gösterilmektedir. Ancak Google Search Console API için de aynı kavramlar 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:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

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:[e-mail]>

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:[e-mail]>

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:[e-mail]>

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:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--