Mengelola komentar

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, rangkaian komentar dan penanda akan dihilangkan secara default.

Untuk menyertakan komentar dalam respons, tetapkan parameter kueri commentsViewMode ke COMMENTS_VIEW_MODE_INCLUDED. Selain itu, jika pengguna yang memanggil memiliki akses komentar pada file, maka menyetel 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 rangkaian komentar dan penanda (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 comments global yang berisi objek CommentThread.
  • Array sheets.commentAnchors yang berisi objek CommentAnchor yang memetakan ID penanda 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 parameter kueri ranges dalam metode spreadsheets.get) atau sheet (menggunakan kolom dataFilters dalam isi permintaan metode spreadsheets.getByDataFilter).

  • Jika Anda memfilter menurut rentang atau sheet: Hanya rangkaian komentar yang ditambatkan dalam rentang atau sheet yang ditentukan yang ditampilkan. Komentar yang tidak ditambatkan (seperti komentar yang koordinat sel aslinya dihapus) tidak disertakan.
  • Jika Anda tidak memfilter menurut rentang atau sheet: Semua rangkaian komentar, termasuk komentar yang tidak ditambatkan, akan ditampilkan.

Contoh respons

Contoh respons JSON berikut menunjukkan rangkaian komentar yang ditambatkan 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 update batch yang melibatkan komentar, Anda harus memantau kemungkinan kegagalan sebagian. Untuk mengetahui informasi selengkapnya, lihat Status update komentar.

Menyisipkan komentar

Untuk menyisipkan rangkaian komentar ke dalam spreadsheet, gunakan objek InsertCommentRequest. Anda harus memberikan isi teks komentar dan coordinate tempat komentar ditambatkan menggunakan objek GridCoordinate.

Contoh JSON berikut menunjukkan cara menambahkan rangkaian 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 kolom assigneeEmailAddress:

{
  "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 rangkaian pesan komentar, menyelesaikan, atau membuka kembali rangkaian pesan, gunakan objek AddCommentReplyRequest.

Anda harus memberikan commentId dan post tempat balasan diwakili oleh objek Post.

Objek Post berisi balasan content dan secara opsional dapat menentukan commentAction (termasuk tindakan untuk RESOLVE atau REOPEN rangkaian pesan komentar). Objek ini direpresentasikan oleh objek CommentActionType.

Anda juga dapat menetapkan ulang rangkaian komentar dengan menentukan assigneeEmail baru dalam objek Post.

Contoh JSON berikut menunjukkan cara membalas rangkaian komentar yang ada:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

Contoh JSON berikut menunjukkan cara menyelesaikan rangkaian komentar (yang tidak memerlukan kolom content):

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

Contoh JSON berikut menunjukkan cara menetapkan ulang rangkaian 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 rangkaian pesan, postId postingan yang ingin Anda edit, dan content teks biasa 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 rangkaian komentar: Untuk menghapus seluruh CommentThread, gunakan objek DeleteCommentRequest. Anda hanya dapat menghapus rangkaian komentar jika Anda adalah penulis rangkaian headPost dalam objek CommentThread.

  • Menghapus balasan: Untuk menghapus balasan spesifik Post dari CommentThread, gunakan objek DeleteCommentReplyRequest. Anda hanya dapat menghapus balasan yang Anda tulis. Anda tidak dapat menghapus postingan balasan yang berisi commentAction atau assigneeEmail.

Contoh JSON berikut menunjukkan cara menghapus rangkaian komentar:

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "COMMENT_ID"
      }
    }
  ]
}

Status pembaruan komentar

Permintaan yang memerlukan penyimpanan rangkaian 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 dilakukan, tetapi komentar terkait mungkin gagal disimpan.

Anda dapat memverifikasi apakah pembaruan komentar berhasil diterapkan dengan memeriksa kolom commentUpdateState di isi respons metode spreadsheets.batchUpdate. Kolom diwakili oleh objek CommentUpdateState.

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 dilakukan.