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 Docs 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 doküman eklemek ve ardından biçimlendirmek için birden çok 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 kod örneğinde, Docs API ile toplu işlemenin kullanımı gösterilmektedir.
İstek
Bu örnek toplu istekte aşağıdakilerin nasıl yapılacağı gösterilmektedir:
InsertTextRequest
kodunu kullanarak mevcut bir belgenin başına "Hello World" metnini1
dizinilocation
ile ekleyin.UpdateTextStyleRequest
kullanarak "Merhaba" kelimesini güncelleyin.startIndex
veendIndex
, segment içindeki biçimlendirilmiş metninrange
değerini tanımlar.textStyle
kullanarak yalnızca "Merhaba" kelimesi için yazı tipi stilini kalın, rengi ise mavi olarak ayarlayın.WriteControl
alanını kullanarak yazma isteklerinin nasıl yürütüleceğini kontrol edebilirsiniz. Daha fazla bilgi için WriteControl ile durum tutarlılığı oluşturma bölümüne bakın.
{ "requests":[ { "insertText":{ "location":{ "index":1 }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
REQUIRED_REVISION_ID değerini, yazma isteğinin uygulandığı dokümanın düzeltme kimliğiyle değiştirin.
Yanıt
Bu örnek toplu yanıtta, toplu istekteki her bir alt isteğin nasıl uygulandığıyla ilgili bilgiler gösterilmektedir. InsertTextRequest
veya UpdateTextStyleRequest
etiketleri yanıt içermediğinden [0] ve [1] sayılarındaki dizinin dizin değerleri boş küme parantezlerinden oluşur. Toplu istekte, isteklerin nasıl yürütüldüğünü gösteren WriteControl
nesnesi görüntülenir.
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }