Ada beberapa prinsip yang harus Anda ikuti saat menggunakan Google Docs API. Ini mencakup:
- Edit mundur agar efisien
- Rencanakan kolaborasi
- Pastikan konsistensi status menggunakan
WriteControl
kolom - Pertimbangkan tab
Bagian berikut menjelaskan prinsip-prinsip ini.
Edit mundur agar efisien
Dalam satu panggilan ke
documents.batchUpdate
, urutkan permintaan Anda dengan
urutan menurun lokasi indeks. Dengan cara ini, Anda tidak perlu menghitung
perubahan indeks karena penyisipan dan penghapusan.
Rencanakan kolaborasi
Status dokumen akan berubah. Di antara satu panggilan metode dan yang lainnya, lainnya dapat memperbarui dokumen, seperti yang ditunjukkan dalam diagram berikut:
Hal ini dapat menyebabkan error jika indeks Anda salah. Dengan beberapa pengguna mengedit
menggunakan UI, Google Dokumen akan menanganinya secara transparan. Namun,
sebagai klien API, aplikasi Anda harus mengelola hal ini. Bahkan jika 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
Ketika Anda membaca kemudian memperbarui dokumen, Anda
dapat mengontrol perilaku bagaimana
perubahan yang bersaing
ditangani menggunakan
WriteControl
kolom dalam metode documents.batchUpdate
. WriteControl
menyediakan otoritas
mengenai bagaimana permintaan tulis dijalankan.
Berikut cara menggunakannya:
- Dapatkan dokumen menggunakan
Metode
documents.get
dan simpan tindakanrevisionId
dari resourcedocuments
yang ditampilkan. - Tulis permintaan update Anda.
- Menyertakan
WriteControl
opsional dengan salah satu dari dua opsi berikut:- Kolom
requiredRevisionId
disetel kerevisionId
dokumen tempat permintaan tulis diterapkan. Jika dokumen telah diubah karena permintaan baca API, permintaan tulis tidak diproses dan menghasilkan {i>error<i}. - Kolom
targetRevisionId
ditetapkan kerevisionId
dokumen tempat diterapkannya permintaan tulis. Jika dokumen telah diubah sejak permintaan baca API, perubahan permintaan tulis diterapkan terhadap perubahan oleh kolaborator. Hasil permintaan tulis menggabungkan permintaan tulis berubah dan kolaborator berubah menjadi revisi dokumen. Server Dokumen bertanggung jawab untuk menggabungkan konten.
- Kolom
Untuk contoh cara membuat permintaan batch menggunakan WriteControl
, lihat
contoh permintaan batch ini.
Pertimbangkan tab
Satu dokumen dapat berisi beberapa tab, yang memerlukan penanganan khusus dalam permintaan API Anda.
Berikut yang perlu diingat:
- Tetapkan parameter
includeTabsContent
ketrue
di Metodedocuments.get
untuk mengambil konten dari semua tab dalam sebuah dokumen. Secara default, tidak semua tab semua konten ditampilkan. - Tentukan ID tab yang akan diterapkan setiap
Request
ke dalamdocuments.batchUpdate
. SetiapRequest
menyertakan cara menentukan tab untuk menerapkan pembaruan. Secara {i>default<i}, jika tab belum ditentukan, makaRequest
dalam kebanyakan kasus akan diterapkan ke tab pertama dalam dokumen. LihatRequest
dokumentasi yang spesifik.