Koleksiyonlar ile düzeninizi koruyun
İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
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 hesaplama ihtiyacı ortadan kalkar.
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:
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:
documents.get yöntemini kullanarak dokümanı alın ve döndürülen documents kaynağındaki 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 olarak ayarlanır. Doküman, API okuma isteğinden sonra 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 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.
Tek bir belge birden fazla sekme içerebilir. Bu sekmeler, API isteklerinizde özel işlem gerektirir.
Unutulmaması gerekenler:
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.
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.
[[["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-29 UTC."],[],[],null,["# Best practices for best results\n\nThere 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-----------------------------\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----------------------\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---------------------------------------------\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----------------------\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\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)"]]
