Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Ada beberapa prinsip yang harus Anda ikuti saat menggunakan Google Dokumen API.
Ini mencakup:
Mengedit secara terbalik untuk efisiensi
Merencanakan kolaborasi
Memastikan konsistensi status menggunakan kolom
WriteControl
Mempertimbangkan tab
Bagian berikut menjelaskan prinsip-prinsip ini.
Mengedit secara terbalik untuk efisiensi
Dalam satu panggilan ke metode
documents.batchUpdate, urutkan permintaan Anda dalam
urutan menurun lokasi indeks. Hal ini menghilangkan kebutuhan untuk menghitung perubahan indeks karena penyisipan dan penghapusan.
Merencanakan kolaborasi
Perkirakan status dokumen akan berubah. Di antara satu panggilan metode dan panggilan metode lainnya, kolaborator lain dapat memperbarui dokumen, seperti yang ditunjukkan dalam diagram berikut:
Hal ini dapat menyebabkan error jika indeks Anda salah. Dengan beberapa pengguna yang mengedit dokumen menggunakan UI, Google Dokumen akan menanganinya secara transparan. Namun,
sebagai klien API, aplikasi Anda harus mengelola hal ini. Meskipun Anda tidak mengantisipasi kolaborasi pada dokumen, penting untuk memprogram secara defensif dan memastikan status dokumen tetap konsisten. Untuk salah satu cara memastikan konsistensi, tinjau bagian WriteControl.
Menetapkan konsistensi status dengan WriteControl
Saat membaca lalu memperbarui dokumen, Anda dapat mengontrol perilaku penanganan perubahan yang bersaing menggunakan kolom WriteControl dalam metode documents.batchUpdate. WriteControl memberikan otoritas
atas cara permintaan tulis dieksekusi.
Berikut cara menggunakannya:
Dapatkan dokumen menggunakan metode documents.get dan simpan revisionId dari resource documents yang ditampilkan.
Tulis permintaan pembaruan Anda.
Sertakan objek WriteControl
opsional dengan salah satu dari dua opsi:
Kolom requiredRevisionId ditetapkan ke revisionId dari dokumen yang diterapkan permintaan penulisan. Jika dokumen diubah sejak permintaan baca API, permintaan tulis tidak diproses dan akan menampilkan error.
Kolom targetRevisionId ditetapkan ke revisionId dokumen tempat permintaan tulis diterapkan. Jika dokumen diubah sejak permintaan baca API, perubahan permintaan tulis diterapkan terhadap perubahan kolaborator. Hasil permintaan penulisan menggabungkan perubahan permintaan penulisan dan perubahan kolaborator ke dalam revisi baru dokumen. Server Dokumen bertanggung jawab
untuk menggabungkan konten.
Untuk contoh cara membuat permintaan batch menggunakan WriteControl, lihat
contoh permintaan batch ini.
Mempertimbangkan tab
Satu dokumen dapat berisi beberapa tab,
yang memerlukan penanganan khusus dalam permintaan API Anda.
Berikut hal yang perlu diingat:
Tetapkan parameter includeTabsContent ke true dalam metode
documents.get
untuk mengambil konten dari semua tab dalam dokumen. Secara default, tidak semua konten tab ditampilkan.
Tentukan ID tab yang akan diterapkan setiap Request
di metode
documents.batchUpdate. Setiap
Request
mencakup cara untuk menentukan tab yang akan diterapkan update-nya. Secara default, jika
tab tidak ditentukan, Request
akan diterapkan pada tab pertama dalam dokumen pada sebagian besar kasus. Lihat dokumentasi
Requests
untuk mengetahui detailnya.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Informasi yang saya butuhkan tidak ada","missingTheInformationINeed","thumb-down"],["Terlalu rumit/langkahnya terlalu banyak","tooComplicatedTooManySteps","thumb-down"],["Sudah usang","outOfDate","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Masalah kode / contoh","samplesCodeIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 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)"]]
