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 Slaytlar 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 sunu 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, Slaytlar API'si ile toplu işlemlerin kullanımı gösterilmektedir.

İstek

Bu örnek toplu istekte aşağıdakiler gösterilmektedir:

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

Yanıt

Bu örnek toplu yanıtta, toplu istekteki her alt isteğin nasıl uygulandığıyla ilgili bilgiler gösterilmektedir. InsertTextRequest yönteminin yanıt içermediğini, bu nedenle [2] konumundaki dizinin dizin değerinin boş köşeli parantezlerden oluştuğunu unutmayın. Toplu istek, yazma isteklerinin nasıl yürütüldüğünü gösteren WriteControl mülkünü gösterir.

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}