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:
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:
- Dapatkan dokumen menggunakan metode
documents.get
, lalu simpanrevisionId
dari resourcedocuments
yang ditampilkan. - Tulis permintaan update Anda.
- Sertakan objek
WriteControl
opsional dengan salah satu dari dua opsi berikut:- Kolom
requiredRevisionId
ditetapkan kerevisionId
dokumen tempat permintaan tulis diterapkan. Jika dokumen telah 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 baru atas dokumen tersebut. Server Dokumen bertanggung jawab untuk menggabungkan konten.
- Kolom
Untuk contoh cara membuat permintaan batch menggunakan WriteControl
, lihat contoh permintaan batch ini.