Praktik terbaik untuk mendapatkan hasil terbaik

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:

Bagaimana dokumen dapat berubah di antara panggilan metode.

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:

  1. Dapatkan dokumen menggunakan Metode documents.get dan simpan tindakan revisionId dari resource documents yang ditampilkan.
  2. Tulis permintaan update Anda.
  3. Menyertakan WriteControl opsional dengan salah satu dari dua opsi berikut:
    1. Kolom requiredRevisionId disetel ke revisionId dokumen tempat permintaan tulis diterapkan. Jika dokumen telah diubah karena permintaan baca API, permintaan tulis tidak diproses dan menghasilkan {i>error<i}.
    2. Kolom targetRevisionId ditetapkan ke revisionId 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.

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:

  1. Tetapkan parameter includeTabsContent ke true di Metode documents.get untuk mengambil konten dari semua tab dalam sebuah dokumen. Secara default, tidak semua tab semua konten ditampilkan.
  2. Tentukan ID tab yang akan diterapkan setiap Request ke dalam documents.batchUpdate . Setiap Request menyertakan cara menentukan tab untuk menerapkan pembaruan. Secara {i>default<i}, jika tab belum ditentukan, maka Request dalam kebanyakan kasus akan diterapkan ke tab pertama dalam dokumen. Lihat Request dokumentasi yang spesifik.