Mengelola komentar dan balasan

Komentar adalah masukan yang diberikan pengguna pada file, seperti pembaca dokumen pengolahan kata yang menyarankan cara menyusun ulang kalimat. Ada dua jenis komentar: komentar anchor dan komentar tanpa anchor. Komentar anchor dikaitkan dengan lokasi tertentu, seperti kalimat dalam dokumen pemrosesan kata, dalam versi dokumen tertentu. Sebaliknya, komentar tanpa anchor hanya dikaitkan dengan dokumen.

Catatan: Pada file blob, Google Drive API hanya mendukung komentar tanpa anchor. Komentar anchor di file blob atau file editor Google Dokumen tidak didukung.

Balasan dilampirkan pada 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 disebut sebagai diskusi.

Menambahkan komentar tanpa anchor

Untuk menambahkan komentar tanpa anchor 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 periksa apakah 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 resource comments untuk memastikan pengguna yang membuat permintaan adalah penulis komentar, lalu verifikasi izin mereka secara relatif terhadap komentar.

Menambahkan balasan ke komentar

Untuk menambahkan balasan atas 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 anchor ke revisi terbaru dokumen

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

Catatan: Pada file blob, Drive API hanya mendukung komentar tanpa anchor. Komentar anchor di file blob atau file editor Google Dokumen tidak didukung.

Penting: Anchor tidak dapat diubah, dan posisinya terkait dengan 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 anchor:

1. (Opsional). Panggil metode revisions.list guna mencantumkan setiap revisionID untuk dokumen. Hanya ikuti langkah ini jika Anda ingin menambatkan komentar ke revisi apa pun 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 Anda menentukan region bergantung pada jenis konten dokumen yang sedang Anda kerjakan. Untuk informasi selengkapnya, lihat Menentukan wilayah.

Catatan: Sebaiknya periksa apakah 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 pada resource komentar.

Menentukan wilayah

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 dapat berbentuk 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 jadikan anchor. Misalnya, jika konten Anda berupa 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 menambatkan komentar ke baris di dua area dokumen yang terpisah:

• Area pertama dimulai pada 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 mengizinkan pengguna memperbarui dan membagikan beberapa revisi dokumen, komentar pada revisi yang lebih lama mungkin tidak lagi berlaku untuk lokasi ditambatkan. Oleh karena itu, Anda harus menunjukkan ke revisi mana setiap komentar jelas dimiliki di UI Anda.

Menyelesaikan komentar

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

Saat aplikasi Anda menetapkan properti resolved ke true, UI Anda harus menunjukkan bahwa komentar telah ditangani. Misalnya, aplikasi Anda mungkin:

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

Menghapus komentar

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

Cantumkan komentar

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