Praktik terbaik untuk mendapatkan hasil terbaik

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

  • Edit mundur agar efisien
  • Rencanakan kolaborasi
  • Memastikan konsistensi status menggunakan kolom WriteControl

Bagian berikut menjelaskan prinsip-prinsip ini.

Edit mundur agar efisien

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

Rencanakan kolaborasi

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

Bagaimana 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 menangani hal ini 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. Salah satu cara untuk 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 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 ke dalam revisi dokumen yang baru. Server Dokumen bertanggung jawab untuk menggabungkan konten.

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