Google Spreadsheet memungkinkan pengguna berkolaborasi dengan menambahkan komentar pada sel tertentu.
Dokumen ini menunjukkan cara menggunakan Google Sheets API untuk membaca, membuat, membalas, memperbarui, atau menghapus komentar secara terprogram.
Membaca komentar
Saat Anda menggunakan metode
get pada resource
spreadsheets
untuk mengambil spreadsheet, thread komentar dan anchor akan dihilangkan secara default.
Untuk menyertakan komentar dalam respons, tetapkan parameter kueri ke.commentsViewModeCOMMENTS_VIEW_MODE_INCLUDED
Selain itu, jika pengguna yang memanggil memiliki akses komentar pada file, menetapkan parameter kueri ke COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS juga akan menampilkan komentar.
Kolom
comments
dan
sheets.commentAnchors
ditampilkan dalam respons.
Contoh kode berikut menunjukkan cara menggunakan permintaan get yang mengambil thread komentar dan anchornya (rentang petak) dari spreadsheet:
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)
Dalam respons, komentar ditampilkan di dua lokasi:
- Array global
commentsyang berisi objekCommentThread. - Array
sheets.commentAnchorsyang berisiCommentAnchorobjek yang memetakan ID anchor komentar ke lokasi sel (rentang petak).
Memfilter komentar menurut rentang atau sheet
Saat mengambil spreadsheet, Anda dapat memfilter data yang ditampilkan dengan menentukan
rentang (menggunakan
ranges
parameter kueri dalam metode spreadsheets.get) atau sheet (menggunakan
dataFilters
kolom di isi permintaan metode spreadsheets.getByDataFilter).
- Jika Anda memfilter menurut rentang atau sheet: Hanya thread komentar yang di-anchor dalam rentang atau sheet yang ditentukan yang akan ditampilkan. Komentar yang tidak di-anchor (seperti komentar yang koordinat sel aslinya dihapus) tidak disertakan.
- Jika Anda tidak memfilter menurut rentang atau sheet: Semua thread komentar, termasuk komentar yang tidak di-anchor, akan ditampilkan.
Contoh respons
Contoh respons JSON berikut menunjukkan thread komentar yang di-anchor ke sel A1 (baris 0, kolom 0) di sheet dengan ID 0:
{
"spreadsheetId": "SPREADSHEET_ID",
"sheets": [
{
"properties": {
"sheetId": 0,
"title": "Sheet1"
},
"commentAnchors": [
{
"anchorId": "ANCHOR_ID",
"range": {
"sheetId": 0,
"startRowIndex": 0,
"endRowIndex": 1,
"startColumnIndex": 0,
"endColumnIndex": 1
}
}
]
}
],
"comments": [
{
"commentId": "COMMENT_ID",
"anchorId": "ANCHOR_ID",
"headPost": {
"postId": "POST_ID",
"content": "This is a comment thread head post.",
"contentHtml": "The content of the post as HTML.",
"author": {
"displayName": "DISPLAY_NAME",
"me": true,
"user": "users/USER"
},
"createTime": "2026-07-01T10:13:12Z",
"updateTime": "2026-07-01T10:13:12Z"
},
"replies": [
{
"postId": "REPLY_POST_ID",
"content": "This is a reply to the comment.",
"author": {
"displayName": "DISPLAY_NAME",
"me": false
},
"createTime": "2026-07-01T10:15:00Z",
"updateTime": "2026-07-01T10:15:00Z"
}
],
"status": "OPEN"
}
],
"commentsViewMode": "COMMENTS_VIEW_MODE_INCLUDED"
}
Membuat dan mengelola komentar
Anda dapat menambahkan, mengedit, dan menghapus komentar atau balasan secara terprogram menggunakan metode
batchUpdate
pada resource
spreadsheets.
Saat melakukan pembaruan batch yang melibatkan komentar, Anda harus memantau potensi kegagalan sebagian. Untuk mengetahui informasi selengkapnya, lihat Status pembaruan komentar.
Menyisipkan komentar
Untuk menyisipkan thread komentar ke dalam spreadsheet, gunakan objek
InsertCommentRequest. Anda harus memberikan konten teks komentar dan the
coordinate
where the comment is anchored using a
GridCoordinate
object.
Contoh JSON berikut menunjukkan cara menambahkan thread komentar yang tidak ditetapkan ke sel B2 (baris 1, kolom 1) di sheet dengan ID 0:
{
"requests": [
{
"insertComment": {
"content": "This is a comment added using the API.",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Anda dapat menetapkan komentar kepada pengguna tertentu dengan memberikan emailnya di
assigneeEmailAddress
kolom:
{
"requests": [
{
"insertComment": {
"content": "Please review the data in this cell.",
"assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Menambahkan balasan atau mengambil tindakan
Untuk membalas thread komentar, menyelesaikan, atau membuka kembali thread, gunakan objek
AddCommentReplyRequest.
Anda harus memberikan commentId dan the
post
tempat balasan direpresentasikan oleh a
Post objek.
Objek Post berisi content balasan dan secara opsional dapat menentukan
commentAction
(termasuk tindakan untuk RESOLVE atau REOPEN thread komentar). Objek ini
direpresentasikan oleh objek
CommentActionType
object.
Anda juga dapat menetapkan ulang thread komentar dengan menentukan assigneeEmail baru dalam objek Post.
Contoh JSON berikut menunjukkan cara membalas thread komentar yang ada:
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
Contoh JSON berikut menunjukkan cara menyelesaikan thread komentar (yang tidak memerlukan kolom content):
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Contoh JSON berikut menunjukkan cara menetapkan ulang thread komentar:
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "ASSIGNEE_EMAIL"
}
}
}
]
}
Mengedit postingan
Untuk mengedit konten teks postingan yang Anda buat, gunakan objek
UpdateCommentPostRequest. Anda harus menentukan commentId thread, postId postingan yang ingin Anda edit, dan content teks biasa yang baru.
Contoh JSON berikut menunjukkan cara mengedit postingan:
{
"requests": [
{
"updateCommentPost": {
"commentId": "COMMENT_ID",
"postId": "POST_ID",
"content": "This is the updated comment text."
}
}
]
}
Menghapus komentar dan balasan
Untuk menghapus komentar dan balasan, Anda memiliki dua opsi:
Menghapus thread komentar: Untuk menghapus seluruh
CommentThread, gunakan objekDeleteCommentRequest. Anda hanya dapat menghapus thread komentar jika Anda adalah penulis thread'sheadPostdalam objekCommentThread.Menghapus balasan: Untuk menghapus balasan tertentu
PostdariCommentThread, gunakanDeleteCommentReplyRequestobjek. Anda hanya dapat menghapus balasan yang Anda buat. Anda tidak dapat menghapus postingan balasan yang berisicommentActionatauassigneeEmail.
Contoh JSON berikut menunjukkan cara menghapus thread komentar:
{
"requests": [
{
"deleteComment": {
"commentId": "COMMENT_ID"
}
}
]
}
Status pembaruan komentar
Permintaan yang memerlukan penyimpanan thread komentar (seperti menyisipkan komentar atau menambahkan balasan) mungkin mengalami kegagalan sebagian. Dalam kasus ini, perubahan model spreadsheet (seperti memperbarui nilai sel atau menambahkan sheet) mungkin berhasil diterapkan, tetapi komentar terkait mungkin gagal disimpan.
Anda dapat memverifikasi apakah pembaruan komentar berhasil diterapkan dengan memeriksa
commentUpdateState
kolom di isi respons metode spreadsheets.batchUpdate. Kolom
direpresentasikan oleh
CommentUpdateState
objek.
Status berikut ditampilkan di CommentUpdateState:
NO_UPDATES_REQUESTED: Tidak ada pembaruan komentar yang diminta dalam operasi batch.ALL_SAVED: Semua pembaruan komentar yang diminta berhasil diterapkan.ALL_FAILED_UNKNOWN_REASON: Semua pembaruan komentar yang diminta gagal disimpan, meskipun perubahan spreadsheet lainnya mungkin telah diterapkan.