Bu belgede, istemcinizin yapması gereken bağlantı sayısını azaltmak için API çağrılarının nasıl toplu olarak gönderileceği 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ış
İstemcinizin yaptığı her bağlantı, belirli miktarda ek yüke neden olur. Google Docs API, istemcinizin birden fazla istek nesnesini (her biri gerçekleştirilecek tek bir istek türünü belirterek) tek bir toplu isteğe yerleştirmesi için toplu işlemeyi destekler. Toplu istek, birden fazla 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 fazla isteği her zaman aynı grupta toplamasını öneririz. Toplu işlemeyi kullanabileceğiniz durumlara ilişkin bazı örnekleri aşağıda 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 gerekir.
Sınırlar, yetkilendirme ve bağımlılıkla ilgili dikkat edilmesi gereken noktalar
Toplu güncellemeyi uygularken göz önünde bulundurulması gereken diğer öğelerin bir listesini aşağıda bulabilirsiniz:
- 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.
- Bir 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üğü 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 dokümanın stilini belirleyebilir.
Grup ayrıntıları
Toplu istek, örneğin bir doküman 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. Diğer bir deyişle, herhangi bir istek geçerli değilse güncellemenin tamamı başarısız olur ve (potansiyel olarak bağımlı olan) değişikliklerin hiçbiri uygulanmaz.
Bazı taleplerde, geçerli taleplerle ilgili bilgiler içeren yanıtlar bulunur. Örneğin, nesne eklemeye yönelik tüm toplu güncelleme istekleri yanıt döndürür. Böylece yeni eklenen nesnenin (ör. kimlik veya başlık) meta verilerine erişebilirsiniz.
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, bir zorunlu ö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 halinde oluşturulur. Her istek, istek nesnesini temsil etmek ve özelliklerini saklamak için JSON kullanır.
Toplu yanıt 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 bir dizide döndürülür. İsteklerden birine verilen her yanıt, karşılık gelen istekle aynı dizin sırasında olur. Bazı istekler yanıt içermiyor ve bu dizi dizinindeki yanıt boş.
Örnek
Aşağıdaki kod örneğinde, Docs API ile toplu hale getirme işlevi gösterilmektedir.
İstek
Bu örnek toplu istekte aşağıdakilerin nasıl yapılacağı gösterilmektedir:
InsertTextRequest
kullanarak, mevcut bir dokümanın başına bir dizin (location
/1
) ile "Hello World" metnini ekleyin.UpdateTextStyleRequest
kullanarak "Merhaba" kelimesini güncelleyin.startIndex
veendIndex
, segment içinde biçimlendirilmiş metninrange
değerini tanımlar.textStyle
kullanarak yalnızca "Merhaba" kelimesi için yazı tipi stilini kalın, rengi 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ıt, toplu istekteki her bir alt isteğin nasıl uygulandığına ilişkin bilgileri gösterir. InsertTextRequest
veya UpdateTextStyleRequest
bir yanıt içermediğinden, [0] ve [1] noktalarındaki dizinin dizin değerleri boş küme parantezlerinden oluşur. Toplu istek, isteklerin nasıl yürütüldüğünü gösteren WriteControl
nesnesini görüntüler.
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }