Mengelola komentar dan balasan

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

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

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

Menetapkan parameter fields diperlukan untuk mencantumkan kolom yang akan ditampilkan dalam respons saat memanggil setiap metode yang tercantum di resource comments. Jika Anda menghilangkan parameter, metode akan menampilkan error. Untuk menampilkan kolom yang tepat yang Anda perlukan, lihat Menampilkan kolom tertentu.

Menambahkan komentar yang tidak terikat

Untuk menambahkan komentar yang tidak ditautkan 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 pastikan pengguna memiliki izin yang benar untuk menambahkan komentar. Selain itu, hanya pembuat komentar atau balasan yang dapat menghapus atau mengedit komentar atau balasan. Error terjadi saat pengguna dalam 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 izin mereka terkait komentar.

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.

Tampilkan contoh

Permintaan

Dalam contoh ini, kita menyediakan 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 me-resolve komentar, gunakan metode replies.create() pada resource replies dengan parameter fileId dan commentId.

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

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

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

• Tidak mengizinkan balasan lebih lanjut dan meredupkan semua balasan sebelumnya beserta komentar asli.
• Sembunyikan komentar yang diselesaikan.

Tampilkan contoh

Permintaan

Dalam contoh ini, kita menyediakan 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 ditautkan ke revisi terbaru dokumen

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

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

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

Untuk menambahkan komentar yang ditautkan:

1. (Opsional). Panggil metode revisions.list() untuk menampilkan daftar setiap revisionID untuk dokumen. Hanya ikuti langkah ini jika Anda ingin mengaitkan 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 Anda gunakan. Untuk informasi lebih lanjut, lihat Menentukan region.

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

Menentukan region

Seperti yang disebutkan sebelumnya, string anchor JSON berisi revisionID (r) dan region (a). Region (a) adalah array JSON yang berisi pengklasifikasi region yang menentukan format dan lokasi tempat komentar ditautkan. Pengklasifikasi mungkin 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 anchor. Misalnya, jika konten Anda berupa teks, Anda kemungkinan akan menggunakan pengklasifikasi wilayah txt atau line.

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

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

• Area pertama dimulai pada baris 12 ('n':12) dan meluas hingga 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 memperbarui dan membagikan beberapa revisi dokumen, komentar pada revisi lama mungkin tidak lagi berlaku untuk lokasi yang ditautkan. Oleh karena itu, Anda harus menunjukkan revisi mana yang terkait dengan setiap komentar dengan jelas di UI.

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.

Tampilkan contoh

Permintaan

Dalam contoh ini, kita menyediakan 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.

Tampilkan contoh

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.

Metode ini menampilkan kolom yang tercantum dalam parameter kueri fields.

Tampilkan contoh

Permintaan

Dalam contoh ini, kita menyediakan 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 akan menandai resource komentar sebagai deleted: true. Komentar yang dihapus tidak menyertakan kolom htmlContent atau content.

Tampilkan contoh

Permintaan

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

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