Toplu istekler

Bu dokümanda, istemcinizin kurması gereken bağlantı sayısını azaltmak için API çağrılarının nasıl toplu olarak yapılacağı gösterilmektedir. Toplu işlem, ağ gidiş dönüşlerini azaltarak ve işleme hızını artırarak uygulamanın verimliliğini artırabilir.

Genel Bakış

Müşterinizin kurduğu her bağlantı belirli miktarda ek maliyete neden olur. Google Docs API, istemcinizin tek bir toplu istek içine her biri gerçekleştirilecek tek bir istek türünü belirten birden fazla istek nesnesi yerleştirmesine olanak tanımak için toplu hale getirmeyi destekler. Toplu istek, birden fazla alt isteği sunucuya yapılan tek bir çağrıda birleştirerek tek bir yanıtı geri alarak performansı artırabilir.

Kullanıcıların her zaman birden fazla isteği birlikte göndermesini öneririz. Gruplandırmayı kullanabileceğiniz durumlara dair bazı örnekleri aşağıda bulabilirsiniz:

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

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

Toplu güncelleme yaparken dikkate almanız gereken diğer öğelerin listesini aşağıda bulabilirsiniz:

  • Tüm alt istekler dahil olmak üzere her toplu istek, kullanım sınırınıza yönelik bir API isteği olarak sayılır.
  • Bir 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, kullanıcılar aynı toplu istekte mevcut bir dokümana metin ekleyip bu metne stil uygulayabilir.

Toplu işlem ayrıntıları

Toplu istek, örneğin bir belge ekleyip biçimlendirmek için birden fazla 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 atomik olarak uygulanır. Yani, herhangi bir istek geçerli değilse güncellemenin tamamı başarısız olur ve (bağlı olabilecek) değişikliklerin hiçbiri uygulanmaz.

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

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

Toplu istek biçimi

İstek, requests adlı tek bir zorunlu özelliğe sahip birden fazla iç içe yerleştirilmiş alt istek içeren tek bir JSON isteğidir. İstekler, ayrı isteklerden oluşan bir dizi halinde oluşturulur. Her istek, istek nesnesini temsil etmek ve özelliklerini eklemek için JSON kullanır.

Toplu yanıtın biçimi

Toplu istek için yanıt biçimi, istek biçimine benzer. Sunucunun yanıtı, tek yanıt nesnesine ait tam yanıtı içerir.

Ana JSON nesnesinin özelliği replies olarak adlandırılır. Yanıtlar bir dizide döndürülür. İsteklerden birine verilen her yanıt, karşılık gelen istekle aynı dizin sırasında olur. Bazı isteklerin yanıtı yoktur ve söz konusu dizi dizinindeki yanıt boştur.

Örnek

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

İstek

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

  • InsertTextRequest kullanarak mevcut bir dokümanın başına "Merhaba Dünya" metnini 1 dizinli location olarak ekleyin.

  • UpdateTextStyleRequest simgesini 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 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,
               "tabId":TAB_ID
            },
            "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"
  }
}

TAB_ID ve REQUIRED_REVISION_ID değerlerini, yazma isteğinin uygulandığı belgenin sırasıyla sekme kimliği ve revizyon kimliğiyle değiştirin.

Yanıt

Bu örnek toplu yanıt, toplu istekteki her bir alt isteğin nasıl uygulandığına ilişkin bilgileri gösterir. InsertTextRequest veya UpdateTextStyleRequest bir yanıt içermediğinden, [0] ve [1] noktalarındaki dizinin dizin değerleri boş küme parantezlerinden oluşur. Toplu istek, isteklerin nasıl yürütüldüğünü gösteren WriteControl nesnesini görüntüler.

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