Praktik terbaik untuk mendapatkan hasil terbaik

Ada beberapa prinsip yang harus Anda ikuti saat menggunakan Google Docs API. Fitur tersebut meliputi:

  • Edit mundur untuk efisiensi
  • Merencanakan kolaborasi
  • Memastikan konsistensi status menggunakan kolom WriteControl

Bagian berikut menjelaskan prinsip-prinsip ini.

Edit mundur untuk efisiensi

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

Merencanakan kolaborasi

Status dokumen akan berubah. Di antara satu panggilan metode dan 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 banyaknya pengguna yang mengedit dokumen menggunakan UI, Google Dokumen menangani hal ini secara transparan. Namun, sebagai klien API, aplikasi Anda harus mengelola hal ini. Meskipun Anda tidak mengantisipasi kolaborasi pada dokumen, penting untuk melakukan pemrograman secara defensif dan memastikan status dokumen tetap konsisten. Salah satu cara untuk 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 otoritas atas cara permintaan tulis dijalankan.

Berikut cara menggunakannya:

  1. Dapatkan dokumen menggunakan metode documents.get, lalu simpan revisionId dari resource documents yang ditampilkan.
  2. Tulis permintaan update Anda.
  3. Sertakan objek WriteControl opsional dengan salah satu dari dua opsi berikut:
    1. Kolom requiredRevisionId ditetapkan ke revisionId dokumen tempat permintaan tulis diterapkan. Jika dokumen telah 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 ke dalam revisi baru atas dokumen tersebut. Server Dokumen bertanggung jawab untuk menggabungkan konten.

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