Dokumen

Panduan ini memperkenalkan konsep seperti metode utama yang membentuk Google Docs API, cara mengakses dokumen, dan alur kerja saat membuat dokumen.

Metode API

Resource documents menyediakan metode yang Anda gunakan untuk memanggil Docs API. Metode berikut memungkinkan Anda membuat, membaca, dan memperbarui dokumen Dokumen:

Metode documents.get dan documents.batchUpdate memerlukan documentId sebagai parameter untuk menentukan dokumen target. Metode documents.create menampilkan instance dokumen yang dibuat, yang dapat Anda gunakan untuk membaca documentId. Untuk mengetahui informasi selengkapnya tentang metode permintaan dan respons Docs API, lihat Permintaan dan respons.

ID Dokumen

documentId adalah ID unik untuk dokumen dan dapat diturunkan dari URL dokumen. ID ini adalah string tertentu yang berisi huruf, angka, dan beberapa karakter khusus. ID dokumen bersifat stabil, meskipun nama dokumen berubah.

https://docs.google.com/document/d/DOCUMENT_ID/edit

Ekspresi reguler berikut dapat digunakan untuk mengekstrak documentId dari URL Google Dokumen:

/document/d/([a-zA-Z0-9-_]+)

Jika Anda sudah memahami Google Drive API, documentId akan sesuai dengan id di resource files.

Mengelola dokumen di Google Drive

File Dokumen disimpan di Google Drive, layanan penyimpanan berbasis cloud kami. Meskipun Docs API memiliki metodenya sendiri yang terpisah, sering kali Anda juga perlu menggunakan metode Google Drive API untuk berinteraksi dengan file Dokumen pengguna. Misalnya, untuk menyalin file Dokumen, gunakan metode files.copy Drive API. Untuk mengetahui informasi selengkapnya, lihat Menyalin dokumen yang ada.

Secara default, saat menggunakan Docs API, dokumen baru akan disimpan ke folder utama pengguna di Drive. Ada opsi untuk menyimpan file ke folder Drive. Untuk mengetahui informasi selengkapnya, lihat Bekerja dengan folder Google Drive.

Bekerja dengan file Dokumen

Untuk mengambil dokumen dari Drive Saya pengguna, sering kali Anda harus menggunakan metode Drive files.list terlebih dahulu untuk mengambil ID file. Memanggil metode tanpa parameter akan menampilkan daftar semua file dan folder, termasuk ID, untuk pengguna.

Jenis MIME dokumen menunjukkan jenis dan format data. Format jenis MIME untuk Dokumen adalah application/vnd.google-apps.document. Untuk mengetahui daftar jenis MIME, lihat Jenis MIME yang didukung Google Workspace dan Google Drive.

Untuk menelusuri berdasarkan jenis MIME hanya untuk file Dokumen dalam Drive Saya, tambahkan filter string kueri berikut:

q: mimeType = 'application/vnd.google-apps.document'

Untuk mengetahui informasi selengkapnya tentang filter string kueri, lihat Menelusuri file dan folder.

Setelah mengetahui documentId, gunakan metode documents.get untuk mengambil instance lengkap dokumen yang ditentukan. Untuk mengetahui informasi selengkapnya, lihat Permintaan dan respons.

Untuk mengekspor konten byte dokumen Google Workspace, gunakan metode files.export Drive dengan documentId file yang akan diekspor dan jenis MIME ekspor yang benar. Untuk mengetahui informasi selengkapnya, lihat Mengekspor konten dokumen Google Workspace.

Membandingkan metode Get dan List

Tabel berikut menjelaskan perbedaan antara metode Drive dan Dokumen, serta data yang ditampilkan dengan setiap metode:

Operator Deskripsi Penggunaan
drive.files.get Mendapatkan metadata file berdasarkan ID. Menampilkan instance resource files. Mendapatkan metadata untuk file tertentu.
drive.files.list Mendapatkan file pengguna. Menampilkan daftar file. Mendapatkan daftar file pengguna jika Anda tidak yakin file mana yang harus diubah.
docs.documents.get Mendapatkan versi terbaru dokumen yang ditentukan, termasuk semua pemformatan dan teks. Menampilkan instance resource documents. Mendapatkan dokumen untuk ID dokumen tertentu.

Alur kerja pembuatan dokumen

Membuat dan mengisi dokumen baru sangat mudah, karena tidak ada konten yang ada yang perlu dikhawatirkan dan tidak ada kolaborator yang dapat mengubah status dokumen. Secara konseptual, hal ini berfungsi seperti yang ditunjukkan dalam diagram urutan berikut:

Alur kerja untuk membuat dan mengisi dokumen baru.
Gambar 1. Alur kerja untuk membuat dan mengisi dokumen baru.

Pada Gambar 1, pengguna yang berinteraksi dengan documentsresource memiliki alur informasi berikut:

  1. Aplikasi memanggil documents.create metode di server web.
  2. Server web mengirimkan respons HTTP yang berisi instance dokumen yang dibuat sebagai resource documents.
  3. Secara opsional, aplikasi memanggil metode documents.batchUpdate untuk melakukan serangkaian permintaan edit secara atomik guna mengisi dokumen dengan data.
  4. Server web mengirimkan respons HTTP. Beberapa metode documents.batchUpdate menyediakan isi respons dengan informasi tentang permintaan yang diterapkan, sedangkan metode lainnya menampilkan respons kosong.

Alur kerja pembaruan dokumen

Memperbarui dokumen yang ada lebih kompleks. Sebelum dapat melakukan panggilan yang bermakna untuk memperbarui dokumen, Anda harus mengetahui statusnya saat ini: elemen apa yang membentuknya, konten apa yang ada dalam elemen tersebut, dan urutan elemen dalam dokumen. Diagram urutan berikut menunjukkan cara kerjanya:

Alur kerja untuk memperbarui dokumen.
Gambar 2. Alur kerja untuk memperbarui dokumen.

Pada Gambar 2, pengguna yang berinteraksi dengan resource documents memiliki alur informasi berikut:

  1. Aplikasi memanggil metode documents.get di server web, dengan documentId file yang akan ditemukan.
  2. Server web mengirimkan respons HTTP yang berisi instance dokumen yang ditentukan sebagai resource documents. JSON yang ditampilkan berisi konten, pemformatan, dan fitur lainnya dari dokumen.
  3. Aplikasi mengurai JSON sehingga pengguna dapat menentukan konten atau format yang akan diperbarui.
  4. Aplikasi memanggil metode documents.batchUpdate untuk melakukan serangkaian permintaan edit secara atomik guna memperbarui dokumen.
  5. Server web mengirimkan respons HTTP. Beberapa metode documents.batchUpdate menyediakan isi respons dengan informasi tentang permintaan yang diterapkan, sedangkan metode lainnya menampilkan respons kosong.

Diagram ini tidak mempertimbangkan alur kerja saat pembaruan serentak oleh kolaborator lain dilakukan dalam dokumen yang sama. Untuk mengetahui informasi selengkapnya, lihat bagian praktik terbaik Merencanakan kolaborasi.