En iyi sonuçlar için en iyi uygulamalar

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

  • Verimliliği artırmak için geriye dönük düzenleme
  • Ortak çalışma için planlama yapma
  • WriteControl alanını kullanarak durum tutarlılığını sağlama
  • Sekmeleri dikkate alın

Bu ilkeler aşağıdaki bölümlerde açıklanmıştır.

Verimliliği artırmak için geriye dönük düzenleme

documents.batchUpdate yöntemine tek bir çağrıda, isteklerinizi dizin konumuna göre azalan düzende sıralayın. Bu sayede, ekleme ve silme işlemlerinden kaynaklanan dizin değişikliklerini hesaplama ihtiyacı ortadan kalkar.

Ortak çalışma için planlama yapma

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. Aşağıdaki şemada bu durum gösterilmektedir:

Bir belge, yöntem çağrıları arasında nasıl değişebilir?

Dizinleriniz yanlışsa bu durum hatalara neden olabilir. Birden fazla kullanıcının kullanıcı arayüzünü kullanarak bir dokümanı düzenlediği durumlarda Google Dokümanlar bu işlemi şeffaf bir şekilde yönetir. Ancak API istemcisi olarak uygulamanızın bunu yönetmesi gerekir. Dokümanda ortak çalışma yapmayı planlamasanız bile, savunma amaçlı programlama yapmak ve doküman durumunun tutarlı kalmasını sağlamak önemlidir. Tutarlılığı sağlamanın bir yolu için WriteControl bölümünü inceleyin.

WriteControl ile durum tutarlılığı sağlama

Bir dokümanı okuyup güncellediğinizde, documents.batchUpdate yöntemindeki WriteControl alanını kullanarak çakışan değişikliklerin nasıl ele alınacağını 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ğından revisionId'i 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 değerine ayarlanır. API okuma isteğinden sonra doküman değiştirildiyse yazma isteği işlenmez ve hata döndürülür.
    2. targetRevisionId alanı, yazma isteğinin uygulandığı dokümanın revisionId değerine ayarlanır. API okuma isteğinden sonra dokümanda değişiklik yapıldıysa yazma isteği değişiklikleri, ortak çalışan değişikliklerine 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 düzeltmesine dahil eder. İçerikleri birleştirme işlemi Dokümanlar sunucusu tarafından gerçekleştirilir.

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

Sekmeleri dikkate alın

Tek bir belge, API isteklerinizde özel işlem gerektiren birden fazla sekme içerebilir.

Unutulmaması gerekenler:

  1. Bir dokümandaki tüm sekmelerdeki içeriği almak için documents.get yönteminde includeTabsContent parametresini true olarak ayarlayın. Varsayılan olarak, tüm sekme içerikleri döndürülmez.
  2. documents.batchUpdate yönteminde her Request öğesinin uygulanacağı sekmelerin kimliklerini belirtin. Her Request, güncellemenin uygulanacağı sekmeleri belirtme yöntemi içerir. Varsayılan olarak, bir sekme belirtilmezse Request çoğu durumda dokümandaki ilk sekmeye uygulanır. Ayrıntılar için Request dokümanlarını inceleyin.