Toplu istekler

Bu belgede, istemcinizin kurması gereken bağlantı sayısını azaltmak için API çağrılarını nasıl toplu hale getireceğiniz gösterilmektedir. Toplu işlem, ağ gidiş gelişlerini azaltarak ve işleme hızını artırarak uygulamaların verimliliğini artırabilir.

Genel bakış

İstemcinizin her bağlantı belirli miktarda ek yüke neden olur. Google Docs API, istemcinizin her biri gerçekleştirilecek tek bir istek türünü belirten birden fazla istek nesnesini tek bir toplu isteğe yerleştirmesini sağlamak için toplu işlemi destekler. Toplu istek, birden çok alt isteği sunucuya tek bir çağrıda birleştirerek tek bir yanıtı geri alarak performansı artırabilir.

Kullanıcıların birden çok isteği her zaman aynı anda gruplandırmasını öneririz. Gruplama işlemini kullanabileceğiniz durumlara ilişkin bazı örnekleri burada bulabilirsiniz:

  • API'yi kullanmaya yeni başladınız ve yüklemeniz gereken çok fazla veri var.
  • Birden fazla nesnede meta verileri veya biçimlendirme gibi özellikleri güncellemeniz gerekir.
  • Çok sayıda nesneyi silmeniz gerekiyor.

Sınırlar, yetkilendirme ve bağımlılıkla ilgili dikkat edilmesi gereken noktalar

Aşağıda, toplu güncellemenin uygulanması sırasında göz önünde bulundurulması gereken diğer öğelerin bir listesi verilmiştir:

  • Tüm alt istekler dahil olmak üzere her toplu istek, kullanım sınırınız kapsamında bir API isteği olarak sayılır.
  • Toplu isteğin kimliği bir kez doğrulanır. Bu tek kimlik doğrulama, istekteki tüm toplu güncelleme nesneleri için geçerlidir.
  • Sunucu, alt istekleri toplu istekte göründükleri sırayla işler. Sonraki alt istekler, önceki alt istekler sırasında gerçekleştirilen işlemlere bağlı olabilir. Örneğin, aynı toplu istekte kullanıcılar mevcut bir dokümana metin ekleyebilir ve ardından stilini değiştirebilir.

Grup ayrıntıları

Toplu istek, örneğin bir doküman eklemek ve ardından biçimlendirmek için birden çok alt istek içeren bir batchUpdate yöntem çağrısından oluşur.

Her istek uygulanmadan önce doğrulanır. Toplu güncellemedeki tüm alt istekler yerel olarak uygulanır. Yani bir istek geçerli değilse güncellemenin tamamı başarısız olur ve (muhtemelen bağımlı olabilecek) değişikliklerin hiçbiri uygulanmaz.

Bazı isteklerde, uygulanan istekler hakkında bilgi içeren yanıtlar sunulur. Örneğin, nesne eklemeye yönelik tüm toplu güncelleme istekleri, yeni eklenen nesnenin kimlik veya başlık gibi meta verilerine erişebilmeniz için yanıt döndürür.

Bu yaklaşımla, birden çok alt istek içeren tek bir API toplu güncelleme isteği kullanarak Google dokümanının tamamını oluşturabilirsiniz.

Toplu istek biçimi

İstek, tek bir gerekli özelliğe sahip birden çok iç içe yerleştirilmiş alt istek içeren tek bir JSON isteğidir: requests. İstekler, bağımsız istekler dizisi şeklinde oluşturulur. Her istek, istek nesnesini temsil etmek ve özelliklerini içermek için JSON kullanır.

Toplu yanıtın biçimi

Toplu isteğin yanıt biçimi, istek biçimine benzer. Sunucunun yanıtı, tek yanıt nesnesinin tam yanıtını içerir.

Ana JSON nesnesinin özelliği replies olarak adlandırılır. Yanıtlar, isteklerden birine verilen her yanıtın karşılık gelen istekle aynı dizin sırasını işleyecek şekilde bir dizi halinde döndürülür. Bazı isteklerin yanıtı yok ve bu dizi dizinindeki yanıt boş.

Örnek

Aşağıdaki kod örneğinde, Docs API ile toplu işlemenin kullanımı gösterilmektedir.

İstek

Bu örnek toplu istekte aşağıdakilerin nasıl yapılacağı gösterilmektedir:

  • InsertTextRequest kodunu kullanarak mevcut bir belgenin başına "Hello World" metnini 1 dizini location ile ekleyin.

  • UpdateTextStyleRequest kullanarak "Merhaba" kelimesini güncelleyin. startIndex ve endIndex, segment içindeki biçimlendirilmiş metnin range değerini tanımlar.

  • textStyle kullanarak yalnızca "Merhaba" kelimesi için yazı tipi stilini kalın, rengi ise mavi olarak ayarlayın.

  • WriteControl alanını kullanarak yazma isteklerinin nasıl yürütüleceğini kontrol edebilirsiniz. Daha fazla bilgi için WriteControl ile durum tutarlılığı oluşturma bölümüne bakın.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

REQUIRED_REVISION_ID değerini, yazma isteğinin uygulandığı dokümanın düzeltme kimliğiyle değiştirin.

Yanıt

Bu örnek toplu yanıtta, toplu istekteki her bir alt isteğin nasıl uygulandığıyla ilgili bilgiler gösterilmektedir. InsertTextRequest veya UpdateTextStyleRequest etiketleri yanıt içermediğinden [0] ve [1] sayılarındaki dizinin dizin değerleri boş küme parantezlerinden oluşur. Toplu istekte, isteklerin nasıl yürütüldüğünü gösteren WriteControl nesnesi görüntülenir.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}