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ş-dönüşlerini azaltarak ve işleme hızını artırarak bir 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, 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 yapılan 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 birlikte gruplandırmasını öneririz. Gruplandırmayı kullanabileceğiniz durumlara ilişkin bazı örnekleri burada bulabilirsiniz:

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

Sınırlar, yetkilendirme ve bağımlılık hakkında dikkat edilmesi gereken noktalar

Aşağıda, toplu güncelleme yöntemini kullanırken 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 tekli 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 dokümanın stilini belirleyebilir.

Grup ayrıntıları

Toplu istek, örneğin bir sunuyu eklemek ve biçimlendirmek için birden çok 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 ana yöntem olarak uygulanır. Yani herhangi bir istek geçerli değilse güncellemenin tamamı başarısız olur ve (potansiyel olarak bağımlı) değişikliklerin hiçbiri uygulanmaz.

Bazı isteklerde, uygulanan istekler hakkında bilgi içeren yanıtlar bulunur. Ö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 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, tek bir gerekli ö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 şeklinde oluşturulur. Her istek, istek nesnesini temsil etmek ve özelliklerini eklemek 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 bir yanıtını içerir.

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

Örnek

Aşağıdaki kod örneğinde, Slides API ile grup oluşturma işlemi 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 istek içindeki her bir alt isteğin nasıl uygulandığıyla ilgili bilgileri gösterir. InsertTextRequest yönteminin bir yanıt içermediğini, bu nedenle [2]'deki dizinin dizin değerinin boş küme parantezlerinden 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
   }
}