En iyi sonuçlar için en iyi uygulamalar

Google Dokümanlar API'sini kullanırken uymanız gereken birkaç ilke vardır. Bunlardan bazıları:

  • Verimlilik için geriye doğru düzenleme
  • Ortak çalışma planı
  • WriteControl alanını kullanarak durum tutarlılığını sağlama
  • Sekmeleri hesaba katma

Aşağıdaki bölümlerde bu ilkeler açıklanmaktadır.

Verimlilik için geriye doğru düzenleme

documents.batchUpdate yöntemine yapılan tek bir çağrı içinde, isteklerinizi dizin konumuna göre azalan sırada düzenleyin. Bu sayede, ekleme ve silme işlemlerinden kaynaklanan dizin değişikliklerini hesaplamaya gerek kalmaz.

Ortak çalışma planı

Doküman durumunun değişmesini bekleyin. Bir yöntem çağrısı ile diğeri arasında, diğer ortak çalışanlar dokümanı güncelleyebilir. Bu durum aşağıdaki şemada gösterilmiştir:

Bir dokümanın yöntem çağrıları arasında nasıl değişebileceği.

Bu durum, dizinleriniz yanlışsa hatalara yol açabilir. Birden fazla kullanıcı, kullanıcı arayüzünü kullanarak bir dokümanı düzenlediğinde Google Dokümanlar bu işlemi şeffaf bir şekilde gerçekleştirir. Ancak uygulamanız, API istemcisi olarak bunu yönetmelidir. Doküman üzerinde işbirliği yapmayı düşünmeseniz bile savunma amaçlı programlama yapmanız ve doküman durumunun tutarlı kalmasını sağlamanız önemlidir. Tutarlılığı sağlamanın bir yolu için WriteControl bölümünü inceleyin.

WriteControl ile durum tutarlılığı oluşturma

Bir dokümanı okuyup güncellediğinizde, documents.batchUpdate yöntemindeki WriteControl alanı ile çakışan değişikliklerin nasıl işleneceğini kontrol edebilirsiniz. WriteControl, yazma isteklerinin nasıl yürütüleceği konusunda yetki sağlar.

Nasıl kullanacağınız aşağıda açıklanmıştır:

  1. documents.get yöntemini kullanarak belgeyi alın ve döndürülen documents kaynağındaki revisionId öğesini kaydedin.
  2. Güncelleme isteklerinizi oluşturun.
  3. İki seçenekten birini içeren isteğe bağlı bir WriteControl nesnesi ekleyin:
    1. requiredRevisionId alanı, yazma isteğinin uygulandığı belgenin revisionId olarak ayarlanır. API okuma isteğinden sonra dokümanda değişiklik yapıldıysa yazma isteği işlenmez ve hata döndürülür.
    2. targetRevisionId alanı, yazma isteğinin uygulandığı dokümanın revisionId olarak ayarlanır. Doküman, API okuma isteğinden sonra değiştirildiyse yazma isteği değişiklikleri, ortak çalışan değişikliklerine göre uygulanır. Yazma isteğinin sonucu, hem yazma isteği değişikliklerini hem de ortak çalışan değişikliklerini dokümanın yeni bir revizyonuna dahil eder. İçeriği birleştirmekten Dokümanlar sunucusu sorumludur.

WriteControl kullanarak toplu istek oluşturma örneği için bu toplu istek örneğine bakın.

Sekmeleri hesaba katma

Tek bir belgede birden fazla sekme bulunabilir. Bu sekmeler, API isteklerinizde özel işlem gerektirir.

Unutulmaması gerekenler:

  1. Bir dokümandaki tüm sekmelerden içerik almak için kullanılan documents.get yönteminde includeTabsContent parametresini true olarak ayarlayın. Varsayılan olarak, tüm sekme içerikleri döndürülmez.
  2. Her Request öğesinin uygulanacağı sekmelerin kimliklerini documents.batchUpdate yönteminde belirtin. Her Request, güncellemenin uygulanacağı sekmeleri belirtmenin bir yolunu içerir. Varsayılan olarak, sekme belirtilmezse Request çoğu durumda dokümandaki ilk sekmeye uygulanır. Ayrıntılı bilgi için Requests dokümanlarına bakın.