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
  • WriteControl alanını kullanarak durum tutarlılığını sağlama
  • Sekmeleri dikkate alın

Aşağıdaki bölümlerde bu ilkeler açıklanmaktadı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. Diğer ortak çalışanlar, bir yöntem çağrısı ile diğer bir yöntem arasında aşağıdaki şemada gösterildiği gibi belgeyi güncelleyebilir:

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

Dizinleriniz yanlışsa bu durum hatalara yol açabilir. 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ığı oluşturma

Bir dokümanı okuyup daha sonra güncellediğinizde documents.batchUpdate yöntemindeki WriteControl alanını kullanarak rakip değişikliklerin nasıl işleneceğini kontrol edebilirsiniz. WriteControl, yazma isteklerinin yürütülme şekli 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 belge değiştirilirse yazma isteği işlenmez ve hata döndürür.
    2. targetRevisionId alanı, yazma isteğinin uygulandığı belgenin 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.

Aşağıdakileri unutmayın:

  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 bir Request öğesinin uygulanacağı sekmelerin kimliklerini belirtin. Her Request, güncellemenin uygulanacağı sekmeleri belirtmenin bir yolunu 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ına bakın.