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 anchor 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.

Menambahkan komentar tanpa penempatan

Untuk menambahkan komentar yang tidak ditautkan ke dokumen, panggil metode comments.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 dengan komentar tersebut.

Menambahkan balasan ke komentar

Untuk menambahkan balasan ke komentar, panggil metode replies.create dengan komentar, parameter fileId, dan resource replies yang berisi balasan.

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

Menambahkan komentar yang ditautkan ke revisi terbaru dokumen

Saat menambahkan komentar, Anda mungkin ingin menautkannya ke wilayah dalam file. Anchor 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 mencantumkan 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 comments.create dengan parameter fileID, resource comments yang berisi komentar, dan string anchor JSON yang berisi revisionID (r) dan region (a).

Cara menentukan wilayah bergantung pada jenis konten dokumen yang Anda kerjakan. 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 adalah 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 dokumen yang terpisah:

• Area pertama dimulai di baris 12 ('n':12) dan diperluas selama 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.

Menyelesaikan komentar

Gunakan metode comment.update untuk menetapkan properti resolved dalam resource comments ke true saat komentar telah direspons.

Saat aplikasi Anda menetapkan properti resolved ke true, 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.

Menghapus komentar

Gunakan metode comments.delete untuk menghapus komentar. Saat komentar dihapus, Drive akan menandai resource komentar sebagai "deleted": "true".

Mencantumkan komentar

Gunakan metode comments.list untuk mencantumkan komentar. Jika Anda ingin menyertakan komentar yang dihapus dalam hasil, tetapkan kolom includedDeleted ke true.