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 E-Tablolar 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 işlemleri destekler. Toplu istek, birden fazla alt isteği sunucuya tek bir çağrıda birleştirip 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 e-tablo 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. 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 nesnesine ait tam yanıtı 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 örnekte, E-Tablolar API'si ile toplu işlemlerin kullanımı gösterilmektedir.

İstek

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

Kullanıcılar, isteğe e-tablo kimliğini ekleyerek aynı API çağrısındaki diğer alt istekler için e-tablo kimliğini kullanabilir. Bu, yazma-okuma-yazma döngüsünü önleyerek performansı artırır.

Farklı kategorilere ayrılmış toplu güncelleme istek türlerinin listesi için Toplu güncelleme işlemleri bölümündeki tabloya bakın.

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

Yanıt

Bu örnek toplu yanıtta, toplu istekteki her alt isteğinin nasıl uygulandığıyla ilgili bilgiler gösterilmektedir. UpdateCellsRequest yanıt içermediğinden [1] konumundaki dizinin dizin değerinin boş parantezlerden oluştuğunu unutmayın.

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]