Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
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:
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, savunmalı bir şekilde 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:
documents.get yöntemini kullanarak dokümanı alın ve döndürülen documents kaynağından revisionId öğesini kaydedin.
Güncelleme isteklerinizi oluşturun.
İki seçenekten birini içeren isteğe bağlı bir WriteControl nesnesi ekleyin:
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.
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 belgede birden fazla sekme bulunabilir. Bu sekmeler, API isteklerinizde özel şekilde ele alınmalıdır.
Aşağıdakileri unutmayın:
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.
Her Request öğesinin uygulanacağı sekmelerin kimliklerini documents.batchUpdate yönteminde 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.
[[["Anlaması kolay","easyToUnderstand","thumb-up"],["Sorunumu çözdü","solvedMyProblem","thumb-up"],["Diğer","otherUp","thumb-up"]],[["İhtiyacım olan bilgiler yok","missingTheInformationINeed","thumb-down"],["Çok karmaşık / çok fazla adım var","tooComplicatedTooManySteps","thumb-down"],["Güncel değil","outOfDate","thumb-down"],["Çeviri sorunu","translationIssue","thumb-down"],["Örnek veya kod sorunu","samplesCodeIssue","thumb-down"],["Diğer","otherDown","thumb-down"]],["Son güncelleme tarihi: 2025-08-01 UTC."],[],[],null,["There are several principles you should follow when using the Google Docs API.\nThese include:\n\n- Edit backwards for efficiency\n- Plan for collaboration\n- Ensure state consistency using the [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) field\n- Take tabs into account\n\nThe following sections explain these principles.\n\nEdit backwards for efficiency\n\nWithin a single call to the\n[`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate)\nmethod, order your requests in\n*descending order* of index location. This eliminates the need to compute the\nindex changes due to insertions and deletions.\n\nPlan for collaboration\n\nExpect the document state to change. Between one method call and another, other\ncollaborators might update the document, as shown in the following diagram:\n\nThis can lead to errors if your indexes are wrong. With multiple users editing a\ndocument using the UI, Google Docs takes care of this transparently. However,\nas an API client your app must manage this. Even if you don't anticipate\ncollaboration on the document, it's important to program defensively and make\nsure the document state remains consistent. For one way to ensure consistency,\nreview the [`WriteControl`](#establish-state-consistency) section.\n\nEstablish state consistency with WriteControl\n\nWhen you read and then update a document, you can control the behavior of how\ncompeting changes are handled using the\n[`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol)\nfield in the `documents.batchUpdate` method. `WriteControl` provides authority\nover how write requests are executed.\n\nHere's how you use it:\n\n1. Get the document using the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method and save the [`revisionId`](/workspace/docs/api/reference/rest/v1/documents#Document.FIELDS.revision_id) from the returned `documents` resource.\n2. Compose your update requests.\n3. Include an optional [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) object with one of two options:\n 1. The `requiredRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request isn't processed and it returns an error.\n 2. The `targetRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request changes are applied against the collaborator changes. The result of the write request incorporates both the write request changes and the collaborator changes into a new revision of the document. The Docs server is responsible for merging the content.\n\nFor an example of how to construct a batch request using `WriteControl`, see\nthis [batch request example](/workspace/docs/api/how-tos/batch#example).\n\nTake tabs into account\n\nA single document can contain multiple [tabs](/workspace/docs/api/how-tos/tabs),\nwhich require specific handling in your API requests.\n\nHere's what to remember:\n\n1. Set the `includeTabsContent` parameter to `true` in the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method to retrieve the content from all tabs in a document. By default, not all tab contents are returned.\n2. Specify the ID(s) of the tab(s) to apply each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) to in the [`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate) method. Each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) includes a way to specify the tabs to apply the update to. By default, if a tab is not specified, the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) will in most cases be applied to the first tab in the document. Refer to the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request)s documentation for specifics.\n\nRelated topics\n\n- [Batch requests](/workspace/docs/api/how-tos/batch)\n- [Requests and responses](/workspace/docs/api/concepts/request-response)\n- [Work with tabs](/workspace/docs/api/how-tos/tabs)"]]
