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 anchor dan komentar tanpa link. Link anchor komentar dikaitkan dengan lokasi tertentu, seperti kalimat dalam dokumen pengolah kata, dalam versi tertentu dari sebuah dokumen. Sebaliknya, komentar yang tidak ditautkan hanya terkait dengan dokumen.

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

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

Menambahkan komentar tanpa penempatan

Untuk menambahkan komentar tanpa tautan 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 berisi konten yang diformat untuk ditampilkan.

Penting: Sebaiknya periksa apakah pengguna memiliki izin yang benar untuk menambahkan data 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 kesalahan ini, periksa {i>field <i}author.me pada resource comments untuk memastikan pengguna yang membuat permintaan adalah penulis komentar, lalu memverifikasi izin terkait komentar.

Menambahkan balasan pada 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 memberikan Kolom htmlContent berisi konten yang diformat untuk ditampilkan.

Menambahkan komentar anchor ke revisi dokumen yang terakhir

Saat menambahkan komentar, Anda mungkin ingin menambatkannya ke suatu wilayah dalam file. Channel anchor menentukan revisi dan region file dalam file tempat komentar pengguna. Resource comments menentukan Kolom anchor sebagai string JSON.

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

Penting: Anchor tidak dapat diubah, dan posisinya sesuai dengan konten dokumen tidak dapat dijamin di antara revisi. Sebaiknya gunakan anchor dalam dokumen yang posisinya tidak berubah, seperti {i>file<i} gambar atau {i>read-only<i} yang informatif serta dipersonalisasi.

Untuk menambahkan komentar anchor:

1. (Opsional). Panggil 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, comments resource 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 kerjakan kami. 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 kesalahan ini, periksa {i>field <i}author.me pada resource comments.

Menentukan wilayah

Seperti yang disebutkan sebelumnya, string anchor JSON berisi revisionID (r) dan region (a). Wilayah (a) adalah array JSON yang berisi pengklasifikasi wilayah menentukan format dan lokasi tempat komentar ditambatkan. Pengklasifikasi bisa berupa persegi panjang dua dimensi untuk sebuah gambar, baris teks dalam dokumen, atau durasi waktu dalam video. Untuk menentukan wilayah, pilih wilayah pengklasifikasi yang cocok dengan jenis konten yang Anda coba kaitkan. Sebagai misalnya, jika konten Anda adalah teks, Anda kemungkinan akan menggunakan txt atau pengklasifikasi wilayah line.

Untuk daftar pengklasifikasi wilayah di Drive API, lihat Wilayah pengklasifikasi.

Contoh berikut menunjukkan string anchor JSON yang menambatkan komentar ke baris dalam 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 dari revisi.

Penting: Jika aplikasi Anda mengizinkan pengguna untuk mengupdate dan membagikan beberapa revisi komentar pada revisi lama mungkin tidak lagi berlaku untuk lokasi HTTP/HTTPS. Oleh karena itu, Anda harus menunjukkan revisi yang dimiliki setiap komentar dengan jelas di UI Anda.

Menyelesaikan komentar

Gunakan metode comment.update untuk menetapkan properti resolved di comments resource ke true bila komentar telah dialamatkan.

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

• Larang balasan lebih lanjut dan redupkan semua balasan sebelumnya plus yang asli komentar Anda.
• Sembunyikan komentar yang terselesaikan.

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 membuat daftar komentar. Jika Anda ingin menyertakan komentar yang dihapus dalam hasil, setel includedDeleted menjadi true.