Praktik terbaik untuk mendapatkan hasil terbaik

Ada beberapa prinsip yang harus Anda ikuti saat menggunakan Google Dokumen API. Ini mencakup:

  • Mengedit mundur untuk efisiensi
  • Merencanakan kolaborasi
  • Memastikan konsistensi status menggunakan kolom WriteControl
  • Pertimbangkan tab

Bagian berikut menjelaskan prinsip-prinsip ini.

Mengedit mundur untuk efisiensi

Dalam satu panggilan ke metode documents.batchUpdate, urutkan permintaan Anda dalam urutan menurun lokasi indeks. Dengan demikian, Anda tidak perlu menghitung perubahan indeks karena penyisipan dan penghapusan.

Merencanakan kolaborasi

Status dokumen akan berubah. Di antara satu panggilan metode dan panggilan lainnya, collaborator lain mungkin memperbarui dokumen, seperti yang ditunjukkan dalam diagram berikut:

Cara dokumen dapat berubah di antara panggilan metode.

Hal ini dapat menyebabkan error jika indeks Anda salah. Dengan beberapa pengguna mengedit dokumen menggunakan UI, Google Dokumen akan menanganinya secara transparan. Namun, sebagai klien API, aplikasi Anda harus mengelolanya. 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 cara penanganan perubahan yang bersaing menggunakan kolom WriteControl dalam metode documents.batchUpdate. WriteControl memberikan otorisasi terhadap cara permintaan tulis dieksekusi.

Berikut cara menggunakannya:

  1. Dapatkan dokumen menggunakan metode documents.get dan simpan revisionId dari resource documents yang ditampilkan.
  2. Tulis permintaan update Anda.
  3. Sertakan objek WriteControl opsional dengan salah satu dari dua opsi:
    1. Kolom requiredRevisionId ditetapkan ke revisionId dokumen tempat permintaan tulis diterapkan. Jika dokumen diubah sejak permintaan baca API, permintaan tulis tidak akan diproses dan akan menampilkan error.
    2. Kolom targetRevisionId ditetapkan ke revisionId dokumen tempat permintaan tulis diterapkan. Jika dokumen diubah sejak permintaan baca API, perubahan permintaan tulis akan diterapkan terhadap perubahan kolaborator. Hasil permintaan tulis menggabungkan perubahan permintaan tulis dan perubahan kolaborator menjadi revisi baru dokumen. Server Dokumen bertanggung jawab untuk menggabungkan konten.

Untuk contoh cara membuat permintaan batch menggunakan WriteControl, lihat contoh permintaan batch ini.

Pertimbangkan tab

Satu dokumen dapat berisi beberapa tab, yang memerlukan penanganan khusus dalam permintaan API Anda.

Berikut hal yang perlu diingat:

  1. Tetapkan parameter includeTabsContent ke true dalam metode documents.get untuk mengambil konten dari semua tab dalam dokumen. Secara default, tidak semua konten tab ditampilkan.
  2. Tentukan ID tab untuk menerapkan setiap Request dalam metode documents.batchUpdate. Setiap Request menyertakan cara untuk menentukan tab tempat update akan diterapkan. Secara default, jika tab tidak ditentukan, Request pada umumnya akan diterapkan ke tab pertama dalam dokumen. Lihat dokumentasi Request untuk mengetahui detailnya.