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 uygulamanın verimliliğini artırabilir.

Genel Bakış

Müşterinizin yaptığı her bağlantı belirli bir ek yük oluşturur. Google E-Tablolar API'si, istemcinizin birden fazla istek nesnesi yerleştirmesine olanak tanımak için toplu hale getirmeyi destekler. Bu nesnelerin her biri, gerçekleştirilecek tek bir istek türünü belirtir. Toplu istek, birden çok alt isteği tek bir sunucu çağrısında birleştirerek ve tek bir yanıt alarak performansı artırabilir.

Kullanıcıları her zaman birden çok isteği birlikte gruplandırmaya teşvik ederiz. Toplu işlem özelliğini kullanabileceğiniz bazı durum örnekleri:

  • API'yi kullanmaya yeni başladıysanız ve yüklemeniz gereken çok sayıda veri varsa
  • Birden fazla nesnede biçimlendirme gibi meta verileri veya özellikleri güncellemeniz gerekir.
  • Birçok nesneyi silmeniz gerekir.

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

Toplu güncelleme kullanırken 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ız kapsamında tek bir API isteği olarak sayılır.
  • Toplu istekler bir kez kimliği doğrulanır. Bu tek kimlik doğrulama, isteğin içindeki 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, kullanıcılar aynı toplu istekte mevcut bir dokümana metin ekleyip bu metni biçimlendirebilir.

Toplu işlem ayrıntıları

Toplu istek, örneğin bir e-tabloyu ekleyip biçimlendirmek için birden fazla alt istek içeren tek 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 (birbirine bağlı olabilecek) değişikliklerin hiçbiri uygulanmaz.

Bazı istekler, uygulanan isteklerle ilgili bilgiler içeren yanıtlar sağlar. Örneğin, nesne eklemeye yönelik tüm toplu güncelleme istekleri yanıt döndürür. Böylece, yeni eklenen nesnenin meta verilerine (ör. kimlik veya başlık) erişebilirsiniz.

Bu yaklaşımla, birden fazla alt isteği olan tek bir API toplu güncelleme isteği kullanarak Google dokümanının tamamını oluşturabilirsiniz.

Toplu isteğin biçimi

İstek, birden fazla iç içe yerleştirilmiş alt istek içeren tek bir JSON isteğidir. Bu istekte requests adlı bir özellik zorunludur. İstekler, ayrı isteklerden oluşan bir dizi halinde oluşturulur. Her istekte, istek nesnesini temsil etmek ve özelliklerini içermek için JSON kullanılır.

Toplu yanıtın biçimi

Toplu isteklerin 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, ilgili istekle aynı dizin sırasını kullanır. Bazı isteklerin yanıtı yok ve bu dizi dizinindeki yanıt boş.

Örnek

Aşağıdaki örnekte, Sheets API ile toplu işleme kullanımı gösterilmektedir.

İstek

Bu örnek toplu istekte aşağıdaki işlemlerin nasıl yapılacağı gösterilmektedir:

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

Farklı kategorilerde gruplandırılmış toplu güncelleme isteği 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ıt, toplu istekteki her alt isteğin nasıl uygulandığıyla ilgili bilgileri gösterir. UpdateCellsRequest yanıt içermediği için [1] konumundaki dizinin dizin değerinin boş küme parantezlerinden 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
            }
         }
      }
   }
]