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 halde 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 tek bir çağrıda birleştirerek ve tek bir yanıt 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ıklarla 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.
  • Toplu isteklerin 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 yapılan 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 eklemeyle ilgili tüm toplu güncelleme istekleri, yeni eklenen nesnenin kimliği veya başlığı gibi meta verilerine erişebilmeniz için yanıt döndürür.

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ı zorunlu bir özelliğe sahip birden fazla iç içe yerleştirilmiş alt istek içeren tek bir JSON isteğidir. İstekler, tek tek isteklerden oluşan bir dizi halinde oluşturulur. Her istek, istek nesnesini temsil etmek ve özelliklerini içermek 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 nesnesinin tam yanıtını içerir.

Ana JSON nesnesinin özelliği replies olarak adlandırılır. Yanıtlar bir dizi halinde döndürülür. İsteklerden birine verilen her yanıt, ilgili istekle aynı dizin sırasını alır. 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ğıdakiler 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 "Merhaba" kelimesinin yazı tipi stilini kalın, rengini 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 başlıklı makaleyi inceleyin.

{
   "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ıtta, toplu istekteki her alt isteğin nasıl uygulandığıyla ilgili bilgiler gösterilmektedir. Ne InsertTextRequest ne de UpdateTextStyleRequest yanıt içermediğinden, [0] ve [1] konumlarındaki dizinin dizin değerleri boş köşeli parantezlerden 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`
}