Toplu istekler

Bu belgede, istemcinizin yapması gereken bağlantı sayısını azaltmak için API çağrılarının nasıl toplu olarak gönderileceği 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ış

İstemcinizin yaptığı her bağlantı, belirli miktarda ek yüke neden olur. Google Slaytlar API'si, istemcinizin gerçekleştirilecek tek bir istek türünü belirten birden fazla istek nesnesini tek bir toplu isteğe yerleştirebilmesi için toplu işlemeyi 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, birden fazla isteği her zaman aynı grupta toplamasını öneririz. Toplu işlemeyi kullanabileceğiniz durumlara ilişkin bazı örnekleri aşağıda 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 gerekir.

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

Toplu güncellemeyi uygularken göz önünde bulundurulması gereken diğer öğelerin bir listesini aşağıda bulabilirsiniz:

  • 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.
  • Bir toplu isteğin kimliği bir kez doğrulanır. Bu tekli kimlik doğrulama, istekteki tüm toplu güncelleme nesneleri için geçerlidir.
  • Sunucu, alt istekleri toplu istekte göründüğü 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 dokümanın stilini belirleyebilir.

Grup ayrıntıları

Toplu istek, örneğin sunu ekleyip biçimlendirmek için birden fazla alt isteği 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. Diğer bir deyişle, herhangi bir istek geçerli değilse güncellemenin tamamı başarısız olur ve (potansiyel olarak bağımlı olan) değişikliklerin hiçbiri uygulanmaz.

Bazı taleplerde, geçerli taleplerle ilgili bilgiler içeren yanıtlar bulunur. Ö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ğini kullanarak tüm Google belgesini oluşturabilirsiniz.

Toplu isteğin biçimi

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

Toplu yanıt 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 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ı istekler yanıt içermiyor ve bu dizi dizinindeki yanıt boş.

Örnek

Aşağıdaki kod örneğinde, Slaytlar API ile toplu hale getirme işlevi gösterilmektedir.

İstek

Bu örnek toplu istekte aşağıdakilerin nasıl yapılacağı 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ıt, toplu istekteki her bir alt isteğin nasıl uygulandığına ilişkin bilgileri gösterir. InsertTextRequest yönteminin bir yanıt içermediğini, bu nedenle dizinin [2] konumundaki dizin değerinin boş kümeli küme ayraçlarından oluştuğunu unutmayın. Toplu istek, yazma isteklerinin nasıl yürütüldüğünü gösteren WriteControl özelliğini gösterir.

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