Bu kılavuzda, Google Dokümanlar API'yi oluşturan birincil istek ve yanıt yöntemleri ve bir dokümanı toplu olarak nasıl güncelleyebileceğiniz açıklanmaktadır.
Google Dokümanlar API'sini bir HTTP isteği kullanarak veya dile özgü bir istemci kitaplığında yöntem çağırma kullanarak çağırabilirsiniz. Bunlar genel olarak eşdeğerdir.
Google Dokümanlar API'si, genellikle istek çağırmanın sonucunu içeren bir HTTP yanıtı döndürür. İstek yapmak için istemci kitaplığı kullanıldığında yanıtlar dile özgü bir şekilde döndürülür.
İstek yöntemleri
Docs API aşağıdaki yöntemleri destekler:
documents.create: Boş bir Google Dokümanlar belgesi oluşturun.documents.get: Belirtilen belgenin tam bir örneğini döndürme. Belge içeriğini, biçimlendirmeyi ve diğer özellikleri ayıklamak için döndürülen JSON'u ayrıştırabilirsiniz.documents.batchUpdate: Belgeye atomik olarak uygulanacak düzenleme isteklerinin listesini gönderin ve sonuçların listesini döndürün.
documents.get ve documents.batchUpdate yöntemleri, hedef belgeyi belirtmek için parametre olarak bir documentId gerektirir. documents.create yöntemi, oluşturulan dokümanın bir örneğini döndürür. Bu örnekten documentId değerini okuyabilirsiniz. documentId hakkında daha fazla bilgi için Doküman Kimliği başlıklı makaleyi inceleyin.
Yayınlanan dokümanları almak için documents.get yöntemini kullanamayacağınızı unutmayın. Yayınlanan herkese açık dokümanlar farklı bir URL biçimi kullanır. URL'nin yeni documentId özelliğini documents.get yöntemiyle kullanmaya çalışmak 404 HTTP durum kodu yanıtı döndürür. Yayınlanan URL'den orijinal documentId'yi alma yöntemi yoktur. Bu sorunun geçici çözümü olarak Drive API'yi kullanarak yayınlanan dokümanı paylaşılan bir dokümana kopyalayabilir ve ardından bu dosyaya erişebilirsiniz. Daha fazla bilgi için Google Dokümanlar, E-Tablolar, Slaytlar ve Formlar dosyalarını herkese açık hale getirme başlıklı makaleyi inceleyin.
Toplu güncellemeler
documents.batchUpdate yöntemi, her biri gerçekleştirilecek tek bir isteği belirten request nesnelerinin bir listesini alır. Örneğin, bir paragrafı biçimlendirip satır içi resim ekleyin. Her istek uygulanmadan önce doğrulanır ve istekler, toplu istekteki sıraya göre işlenir.
Toplu güncellemedeki tüm 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ı documents.batchUpdate yöntemleri, uygulanan istekler hakkında bilgi içeren yanıtlar sağlar. Bu yöntemler, response nesnelerinin listesini içeren bir yanıt gövdesi döndürür. Diğer isteklerin bilgi döndürmesi ve boş bir yanıt göstermesi gerekmez. Yanıt listesindeki nesneler, ilgili istekle aynı dizin sırasını kullanır.
Toplu istek göndermek için kullanılan popüler bir kalıp aşağıdaki gibidir:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Dokümanlar API çağrılarınızı toplu olarak nasıl göndereceğinizle ilgili tüm ayrıntılar için toplu isteklerle ilgili en iyi uygulamalara göz atın ve istek ve yanıt türleriyle ilgili documents.batchUpdate referans dokümanlarını inceleyin.
Toplu güncelleme işlemleri
Çeşitli toplu güncelleme isteği türleri vardır. Aşağıda, farklı kategorilere ayrılmış istek türlerinin dökümü verilmiştir.