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:
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:
- Dapatkan dokumen menggunakan metode
documents.get
dan simpanrevisionId
dari resourcedocuments
yang ditampilkan. - Tulis permintaan update Anda.
- Sertakan objek
WriteControl
opsional dengan salah satu dari dua opsi:- Kolom
requiredRevisionId
ditetapkan kerevisionId
dokumen tempat permintaan tulis diterapkan. Jika dokumen diubah sejak permintaan baca API, permintaan tulis tidak akan diproses dan akan menampilkan error. - Kolom
targetRevisionId
ditetapkan kerevisionId
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.
- Kolom
Untuk contoh cara membuat permintaan batch menggunakan WriteControl
, lihat
contoh permintaan batch ini.