Mengelola komentar dan balasan

Komentar adalah masukan yang diberikan pengguna pada file, seperti pembaca dokumen pengolah kata yang menyarankan cara menyusun ulang kalimat. Ada dua jenis komentar: komentar yang disematkan dan komentar yang tidak disematkan. Komentar yang ditambatkan dikaitkan dengan lokasi tertentu, seperti kalimat dalam dokumen pengolah kata, dalam versi tertentu dari dokumen. Sebaliknya, komentar yang tidak ditambatkan hanya dikaitkan dengan dokumen.

Catatan: Pada file blob, Google Drive API hanya mendukung komentar yang tidak ditautkan. Komentar yang ditambatkan pada file blob atau file editor Google Dokumen tidak didukung.

Balasan dilampirkan ke komentar dan mewakili respons pengguna terhadap komentar. Drive API memungkinkan pengguna Anda menambahkan komentar dan balasan ke dokumen yang dibuat oleh aplikasi Anda. Secara keseluruhan, komentar dengan balasan dikenal sebagai diskusi.

Untuk semua metode (kecuali delete) pada resource comments, Anda harus menetapkan parameter sistemfields untuk menentukan kolom yang akan ditampilkan dalam respons. Di sebagian besar metode Drive, tindakan ini hanya diperlukan untuk menampilkan kolom non-default, tetapi wajib untuk resource comments. Jika Anda menghapus parameter, metode akan menampilkan error. Untuk mengetahui informasi selengkapnya, lihat Mengembalikan kolom tertentu.

Menambahkan komentar yang tidak terkait

Untuk menambahkan komentar yang tidak terkait ke dokumen, panggil metode create dengan parameter fileId dan resource comments yang berisi komentar.

Komentar disisipkan sebagai teks biasa, tetapi isi respons menyediakan kolom htmlContent yang berisi konten yang diformat untuk ditampilkan.

Penting: Sebaiknya periksa apakah pengguna memiliki izin yang benar untuk menambahkan komentar. Selain itu, hanya kreator komentar atau balasan yang dapat menghapus atau mengedit komentar atau balasan. Error terjadi saat pengguna dengan peran non-kreator mencoba menghapus atau mengedit komentar. Untuk menghindari error ini, periksa kolom author.me dari resource comments untuk memastikan pengguna yang membuat permintaan adalah penulis komentar, lalu verifikasi izinnya terkait komentar tersebut.

Menambahkan balasan ke komentar

Untuk menambahkan balasan ke komentar, gunakan metode replies.create pada resource replies dengan parameter fileId dan commentId. Isi permintaan menggunakan kolom content untuk menambahkan balasan.

Balasan disisipkan sebagai teks biasa, tetapi isi respons menyediakan kolom htmlContent yang berisi konten yang diformat untuk ditampilkan.

Metode ini menampilkan kolom yang tercantum di kolom fields.

Permintaan

Dalam contoh ini, kita memberikan parameter jalur fileId dan commentId serta beberapa kolom.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Isi permintaan

{
  "content": "This is a reply to a comment."
}

Menyelesaikan komentar

Komentar hanya dapat diselesaikan dengan memposting balasan ke komentar.

Untuk menyelesaikan komentar, gunakan metode replies.create pada resource replies dengan parameter fileId dan commentId.

Isi permintaan menggunakan kolom action untuk menyelesaikan komentar. Anda juga dapat menetapkan kolom content untuk menambahkan balasan yang menutup komentar.

Saat komentar diselesaikan, Drive menandai resource komentar sebagai resolved: true. Tidak seperti komentar yang dihapus, komentar yang diselesaikan dapat menyertakan kolom htmlContent atau content.

Saat aplikasi Anda menyelesaikan komentar, UI Anda harus menunjukkan bahwa komentar telah ditangani. Misalnya, aplikasi Anda dapat:

• Melarang balasan lebih lanjut dan meredupkan semua balasan sebelumnya serta komentar asli.
• Sembunyikan komentar yang diselesaikan.

Permintaan

Dalam contoh ini, kita memberikan parameter jalur fileId dan commentId serta beberapa kolom.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Isi permintaan

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

Menambahkan komentar yang ditambatkan ke revisi terbaru dokumen

Saat menambahkan komentar, Anda mungkin ingin menautkannya ke suatu area dalam file. Anchor menentukan revisi dan wilayah file yang dirujuk oleh komentar. Resource comments menentukan kolom anchor sebagai string JSON.

Catatan: Pada file blob, Drive API hanya mendukung komentar yang tidak terkait. Komentar yang ditambatkan pada file blob atau file editor Google Dokumen tidak didukung.

Penting: Penanda tidak dapat diubah, dan posisinya relatif terhadap konten dokumen tidak dapat dijamin di antara revisi. Sebaiknya gunakan penanda dalam dokumen yang posisinya tidak berubah, seperti file gambar atau dokumen hanya baca.

Untuk menambahkan komentar yang disematkan:

1. (Opsional). Panggil metode revisions.list untuk mencantumkan setiap revisionID untuk dokumen. Ikuti langkah ini hanya jika Anda ingin menyematkan komentar ke revisi selain revisi terbaru. Jika Anda ingin menggunakan revisi terbaru, gunakan head untuk revisionID.

2. Panggil metode create dengan parameter fileID, resource comments yang berisi komentar, dan string anchor JSON yang berisi revisionID (r) dan region (a).

Cara Anda menentukan wilayah bergantung pada jenis konten dokumen yang sedang Anda kerjakan. Untuk mengetahui informasi lebih lanjut, lihat Menentukan region.

Catatan: Sebaiknya periksa apakah pengguna memiliki izin yang benar untuk menambahkan komentar. Selain itu, hanya kreator komentar atau balasan yang dapat menghapus atau mengedit komentar atau balasan. Error terjadi saat seseorang dengan peran non-kreator mencoba menghapus atau mengedit komentar. Untuk menghindari error ini, periksa kolom author.me dari resource comments.

Tentukan wilayah

Seperti yang disebutkan sebelumnya, string penanda JSON berisi revisionID (r) dan region (a). Region (a) adalah array JSON yang berisi pengklasifikasi region yang menentukan format dan lokasi tempat komentar ditandai. Pengklasifikasi dapat berupa persegi panjang dua dimensi untuk gambar, baris teks dalam dokumen, atau durasi waktu dalam video. Untuk menentukan wilayah, pilih pengklasifikasi wilayah yang cocok dengan jenis konten yang ingin Anda kaitkan. Misalnya, jika konten Anda adalah teks, Anda kemungkinan akan menggunakan pengklasifikasi wilayah txt atau line.

Untuk mengetahui daftar pengklasifikasi wilayah di Drive API, lihat Pengklasifikasi wilayah.

Contoh berikut menunjukkan string anchor JSON yang menyematkan komentar ke baris di dua area terpisah dalam dokumen:

• Area pertama dimulai di baris 12 ('n':12) dan mencakup tiga baris ('l':3).
• Area kedua hanya mencakup baris 18 ('n':18, 'l':1`).

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Ganti REVISION_ID dengan head atau ID revisi tertentu.

Penting: Jika aplikasi Anda memungkinkan pengguna mengupdate dan membagikan beberapa revisi dokumen, komentar pada revisi yang lebih lama mungkin tidak lagi berlaku untuk lokasi yang ditambatkan. Oleh karena itu, Anda harus menunjukkan revisi mana yang terkait dengan setiap komentar dengan jelas di UI Anda.

Mendapatkan komentar

Untuk mendapatkan komentar pada file, gunakan metode get pada resource comments dengan parameter fileId dan commentId. Jika tidak mengetahui ID komentar, Anda dapat mencantumkan semua komentar menggunakan metode list.

Metode ini menampilkan instance resource comments.

Untuk menyertakan komentar yang dihapus dalam hasil, tetapkan parameter kueri includedDeleted ke true.

Permintaan

Dalam contoh ini, kita memberikan parameter jalur fileId dan commentId serta beberapa kolom.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

Mencantumkan komentar

Untuk mencantumkan komentar pada file, gunakan metode list pada resource comments dengan parameter fileId. Metode ini menampilkan daftar komentar.

Teruskan parameter kueri berikut untuk menyesuaikan penomoran halaman atau memfilter komentar:

• includeDeleted: Tetapkan ke true untuk menyertakan komentar yang dihapus. Komentar yang dihapus tidak menyertakan kolom htmlContent atau content.

• pageSize: Jumlah maksimum komentar yang akan ditampilkan per halaman.

• pageToken: Token halaman, diterima dari panggilan daftar sebelumnya. Berikan token ini untuk mengambil halaman berikutnya.

• startModifiedTime: Nilai minimum kolom modifiedTime untuk komentar hasil.

Permintaan

Dalam contoh ini, kita menyediakan parameter jalur fileId, parameter kueri includeDeleted, dan beberapa kolom.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

Memperbarui komentar

Untuk memperbarui komentar pada file, gunakan metode update pada resource comments dengan parameter fileId dan commentId. Isi permintaan menggunakan kolom content untuk memperbarui komentar.

Kolom boolean resolved pada resource comments bersifat hanya baca. Komentar hanya dapat diselesaikan dengan memposting balasan ke komentar. Untuk mengetahui informasi selengkapnya, lihat Menyelesaikan komentar.

Metode ini akan menampilkan kolom yang tercantum dalam parameter kueri fields.

Permintaan

Dalam contoh ini, kita memberikan parameter jalur fileId dan commentId serta beberapa kolom.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

Isi permintaan

{
  "content": "This comment is now updated."
}

Menghapus komentar

Untuk menghapus komentar pada file, gunakan metode delete pada resource comments dengan parameter fileId dan commentId.

Saat komentar dihapus, Drive menandai resource komentar sebagai deleted: true. Komentar yang dihapus tidak menyertakan kolom htmlContent atau content.

Permintaan

Dalam contoh ini, kita memberikan parameter jalur fileId dan commentId.

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID