Mengelola komentar dan balasan

Komentar adalah masukan yang diberikan pengguna pada file, seperti pembaca dokumen pengolah kata yang menyarankan cara mengubah 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.

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

Menggunakan parameter kolom

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

Batasan komentar

Batasan berikut diterapkan saat menggunakan komentar yang ditautkan dan tidak ditautkan dengan Drive API:

Jenis komentar	Jenis file
Ditautkan	Developer dapat menentukan formatnya sendiri untuk spesifikasi anchor. Anchor disimpan dan ditampilkan saat mengambil komentar, tetapi aplikasi editor Google Workspace memperlakukan komentar ini sebagai komentar yang tidak ditautkan.
Tidak ditautkan	Didukung di dokumen Google Workspace, yang akan menampilkannya dalam tampilan "Semua Komentar". Komentar yang tidak ditautkan tidak ditampilkan pada PDF yang dirender di penampil pratinjau file Drive, meskipun disimpan dan dapat diambil melalui Drive API.

Menambahkan komentar yang ditautkan ke revisi terbaru dokumen

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

Penting: Anchor tidak dapat diubah, dan posisinya relatif terhadap konten dokumen tidak dapat dijamin antar-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 list pada resource revisions untuk mencantumkan setiap revisionID untuk dokumen. Hanya ikuti langkah ini jika Anda ingin menautkan komentar ke revisi selain revisi terbaru. Jika Anda ingin menggunakan revisi terbaru, gunakan head untuk revisionID.

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

Contoh kode berikut menunjukkan cara membuat komentar yang ditautkan:

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

Drive API menampilkan instance objek resource comments yang menyertakan string anchor.

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 dengan peran non-pembuat mencoba menghapus atau mengedit komentar. Untuk menghindari error ini, periksa kolom author.me dari resource komentar.

Menambahkan komentar yang tidak ditautkan

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

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

Contoh kode berikut menunjukkan cara membuat komentar yang tidak ditautkan:

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

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 dengan peran non-pembuat 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 relatif terhadap komentar.

Menambahkan balasan ke komentar

Untuk menambahkan balasan ke komentar, gunakan metode 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, kami 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 create metode pada replies resource 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 comments 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 mungkin:

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

Permintaan

Dalam contoh ini, kami 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."
}

Mendapatkan komentar

Untuk mendapatkan komentar pada file, gunakan get metode pada comments resource dengan fileId dan commentId parameter. 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 includedDeleted parameter kueri ke true.

Permintaan

Dalam contoh ini, kami 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 comments resource dengan fileId parameter. 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, yang diterima dari panggilan daftar sebelumnya. Berikan token ini untuk mengambil halaman berikutnya.

• startModifiedTime: Nilai minimum kolom modifiedTime untuk komentar hasil.

Permintaan

Dalam contoh ini, kami memberikan 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 menampilkan kolom yang tercantum di parameter kueri fields.

Permintaan

Dalam contoh ini, kami 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, kami memberikan parameter jalur fileId dan commentId.

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

Topik terkait

• Ringkasan file dan folder
• Mengelola revisi file