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 yang disematkan dan komentar yang tidak disematkan. Komentar yang ditambatkan dikaitkan dengan lokasi tertentu, seperti kalimat dalam dokumen pemrosesan kata, dalam versi tertentu dari dokumen. Sebaliknya, komentar yang tidak ditambatkan hanya dikaitkan dengan dokumen.

Balasan dilampirkan ke komentar dan mewakili respons pengguna terhadap komentar. Drive API memungkinkan pengguna Anda 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 menghilangkan parameter fields, metode akan menampilkan error. Untuk mengetahui informasi selengkapnya, lihat Mengembalikan kolom tertentu.

Batasan komentar

Batasan berikut diterapkan saat menggunakan komentar yang di-anchor dan tidak di-anchor dengan Drive API:

Menambahkan komentar yang ditambatkan ke revisi terbaru dokumen

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

Untuk menambahkan komentar yang disematkan:

1. (Opsional). Panggil metode list di resource revisions untuk mencantumkan setiap revisionID untuk dokumen. Ikuti langkah ini hanya jika Anda ingin menyematkan komentar ke revisi selain revisi terbaru. Jika Anda ingin menggunakan revisi terbaru, gunakan head untuk revisionID.

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

Contoh kode berikut menunjukkan cara membuat komentar yang ditambatkan:

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

Menambahkan komentar yang tidak terkait

Untuk menambahkan komentar yang tidak ditambatkan, 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.

Contoh kode berikut menunjukkan cara membuat komentar yang tidak ditambatkan:

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()

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.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

{
  "content": "This is a reply to a comment."
}

Menyelesaikan komentar

Komentar hanya dapat diselesaikan dengan memposting balasan ke komentar.

Untuk menyelesaikan komentar, gunakan metode create pada resource replies dengan parameter fileId dan commentId.

Isi permintaan menggunakan kolom action untuk menyelesaikan komentar. Anda juga dapat menyetel 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 dapat:

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

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

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.

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, yang diterima dari panggilan daftar sebelumnya. Berikan token ini untuk mengambil halaman berikutnya.

• startModifiedTime: Nilai minimum kolom modifiedTime untuk komentar hasil.

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 dalam parameter kueri fields.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

{
  "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.

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

Topik terkait

• Ringkasan file dan folder
• Mengelola revisi file