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, tempat Anda dapat membaca documentId. Untuk informasi selengkapnya tentang permintaan dan API Dokumen metode respons, lihat Permintaan dan respons tersebut.

ID Dokumen

documentId adalah ID unik untuk dokumen dan dapat diperoleh dari URL dokumen. String ini adalah {i>string<i} tertentu yang berisi huruf, angka, dan beberapa karakter khusus. ID dokumen stabil, meskipun nama dokumen perubahan.

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 terbiasa dengan Google Drive API, documentId sesuai dengan id di resource files.

Mengelola dokumen di Google Drive

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

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

Menggunakan file Dokumen

Untuk mengambil dokumen dari Drive Saya milik pengguna, biasanya diperlukan untuk terlebih dahulu menggunakan Metode files.list untuk mengambil ID untuk file. Memanggil metode tanpa parameter apa pun 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 daftar Jenis MIME, lihat MIME yang didukung Google Workspace dan Google Drive jenis data.

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

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

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

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

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

Membandingkan metode Get dan List

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

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. Dapatkan daftar file pengguna saat Anda tidak yakin file mana yang harus Anda ubah.
docs.documents.get Mendapatkan versi terbaru dari dokumen yang ditentukan, termasuk semua pemformatan dan teks. Menampilkan instance resource documents. Dapatkan dokumen untuk ID dokumen tertentu.

Alur kerja pembuatan dokumen

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

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 Resource documents memiliki hal berikut aliran informasi:

  1. Aplikasi memanggil Metode documents.create aktif server web.
  2. Server web mengirimkan respons HTTP yang berisi sebuah instance dari membuat dokumen sebagai resource documents.
  3. Secara opsional, aplikasi memanggil documents.batchUpdate untuk melakukan kumpulan permintaan edit secara atomik guna mengisi dokumen dengan data.
  4. Server web mengirimkan respons HTTP. Beberapa metode documents.batchUpdate memberikan isi respons dengan informasi tentang permintaan yang diterapkan, sedangkan yang lain menampilkan respons kosong.

Alur kerja pembaruan dokumen

Memperbarui dokumen yang ada lebih rumit. Sebelum Anda dapat membuat sesuatu yang bermakna untuk memperbarui dokumen, Anda harus mengetahui statusnya saat ini: elemen apa yang itu, konten apa yang ada di elemen-elemen itu, dan urutan elemen di dalamnya 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 aliran informasi berikut:

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

Diagram ini tidak mempertimbangkan alur kerja yang melakukan update serentak oleh kolaborator dibuat dalam dokumen yang sama. Untuk informasi selengkapnya, lihat bagian praktik Rencanakan kolaborasi.