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ş gelişlerini azaltarak ve işleme hızını artırarak uygulamaların verimliliğini artırabilir.

Genel bakış

İstemcinizin her bağlantı belirli miktarda ek yüke neden olur. Google Sheets API, 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 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 aynı anda gruplandırmasını öneririz. Gruplama işlemini kullanabileceğiniz durumlara ilişkin bazı örnekleri burada 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 gerekiyor.

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

Aşağıda, toplu güncellemenin uygulanması sırasında 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 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 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 stilini değiştirebilir.

Grup ayrıntıları

Toplu istek, örneğin bir e-tablo 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 yerel olarak uygulanır. Yani bir istek geçerli değilse güncellemenin tamamı başarısız olur ve (muhtemelen bağımlı olabilecek) değişikliklerin hiçbiri uygulanmaz.

Bazı isteklerde, uygulanan istekler hakkında bilgi içeren yanıtlar sunulur. Ö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 çok alt istek içeren tek bir API toplu güncelleme isteği kullanarak Google dokümanının tamamını oluşturabilirsiniz.

Toplu istek 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, bağımsız istekler dizisi şeklinde oluşturulur. Her istek, istek nesnesini temsil etmek ve özelliklerini içermek 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 yanıtını içerir.

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

Örnek

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

İstek

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

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

Farklı kategoriler halinde 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ıtta, toplu istekteki her bir alt isteğin nasıl uygulandığıyla ilgili bilgiler gösterilmektedir. UpdateCellsRequest bir yanıt içermediğinden, [1] aralığındaki 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
            }
         }
      }
   }
]