Praktik terbaik untuk mendapatkan hasil terbaik

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:

Cara dokumen dapat berubah di antara panggilan metode.

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:

  1. Dapatkan dokumen menggunakan metode documents.get dan simpan revisionId dari resource documents yang ditampilkan.
  2. Tulis permintaan pembaruan Anda.
  3. Sertakan objek WriteControl opsional dengan salah satu dari dua opsi:
    1. 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.
    2. 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:

  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 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.