使用者可以在 Google 試算表的特定儲存格中新增註解，與他人協作。
本文說明如何使用 Google Sheets API，以程式輔助方式讀取、建立、回覆、更新或刪除註解。
閱讀評論
在 spreadsheets 資源上使用 get 方法擷取試算表時，系統預設會省略留言串和錨點。
如要在回應中加入留言，請將 commentsViewMode 查詢參數設為 COMMENTS_VIEW_MODE_INCLUDED。此外，如果呼叫使用者擁有檔案的註解存取權，將查詢參數設為 COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS 也會傳回註解。
回應中會傳回 comments 和 sheets.commentAnchors 欄位。
下列程式碼範例說明如何使用 get 要求，從試算表擷取留言串及其錨點 (格線範圍)：
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)
在回應中，系統會在兩個位置傳回留言：
- 包含
CommentThread物件的全域comments陣列。 sheets.commentAnchors陣列，內含將留言錨點 ID 對應至儲存格位置 (格線範圍) 的CommentAnchor物件。
依範圍或工作表篩選註解
擷取試算表時，您可以指定範圍 (使用 spreadsheets.get 方法中的 ranges 查詢參數) 或工作表 (使用 spreadsheets.getByDataFilter 方法要求主體中的 dataFilters 欄位)，篩選傳回的資料。
- 如果依範圍或工作表篩選：系統只會傳回錨定在指定範圍或工作表中的留言串。系統不會匯出未錨定的註解 (例如原始儲存格座標已刪除的註解)。
- 如未依範圍或工作表篩選：系統會傳回所有留言串，包括未錨定的留言。
回應範例
下列 JSON 回應範例顯示錨定至工作表上儲存格 A1 (第 0 列第 0 欄) 的留言串，該工作表的 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"
}
建立及管理留言
您可以使用 spreadsheets 資源的 batchUpdate 方法，以程式輔助方式新增、編輯及刪除留言或回覆。
執行涉及留言的批次更新時，請監控可能發生的部分失敗情況。詳情請參閱「留言更新狀態」。
插入註解
如要在試算表中插入註解串，請使用
InsertCommentRequest
物件。您必須提供註解文字內容，以及使用 GridCoordinate 物件錨定註解的 coordinate。
下列 JSON 範例說明如何將未指派的註解討論串新增至 ID 為 0 的工作表，並放在儲存格 B2 (第 1 列第 1 欄)：
{
"requests": [
{
"insertComment": {
"content": "This is a comment added using the API.",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
您可以在「assigneeEmailAddress」欄位中提供特定使用者的電子郵件地址，將註解指派給對方：
{
"requests": [
{
"insertComment": {
"content": "Please review the data in this cell.",
"assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
新增回覆或採取行動
如要回覆、解決或重新開啟留言討論串，請使用 AddCommentReplyRequest 物件。
您必須提供 commentId 和 post，其中回覆是以 Post 物件表示。
Post 物件包含回覆 content，並可選擇指定 commentAction (包括 RESOLVE 或 REOPEN 留言討論串的動作)。這項資料會以 CommentActionType 物件表示。
您也可以在 Post 物件中指定新的 assigneeEmail，重新指派留言討論串。
下列 JSON 範例顯示如何回覆現有留言串：
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
下列 JSON 範例說明如何解決留言串問題 (不需要 content 欄位)：
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
下列 JSON 範例說明如何重新指派留言串：
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "ASSIGNEE_EMAIL"
}
}
}
]
}
編輯貼文
如要編輯自己發布的貼文內容，請使用 UpdateCommentPostRequest 物件。您必須指定執行緒的 commentId、要編輯的貼文 postId，以及新的純文字 content。
下列 JSON 範例說明如何編輯貼文：
{
"requests": [
{
"updateCommentPost": {
"commentId": "COMMENT_ID",
"postId": "POST_ID",
"content": "This is the updated comment text."
}
}
]
}
刪除留言和回覆
如要刪除留言和回覆，有兩種做法：
刪除留言討論串：如要移除整個討論串
CommentThread，請使用DeleteCommentRequest物件。只有討論串的作者才能刪除討論串。討論串的作者是CommentThread物件中的headPost。刪除回覆：如要從
CommentThread中刪除特定回覆Post，請使用DeleteCommentReplyRequest物件。你只能刪除自己撰寫的回覆。如果回覆貼文含有commentAction或assigneeEmail，就無法刪除。
下列 JSON 範例說明如何刪除留言串：
{
"requests": [
{
"deleteComment": {
"commentId": "COMMENT_ID"
}
}
]
}
註解更新狀態
如果要求需要儲存留言串 (例如插入留言或新增回覆)，可能會部分失敗。在這些情況下，試算表模型變更 (例如更新儲存格值或新增工作表) 可能會成功提交，但相關聯的註解可能無法儲存。
如要確認註解更新是否已成功套用，請檢查 spreadsheets.batchUpdate 方法回應主體中的 commentUpdateState 欄位。欄位會以 CommentUpdateState 物件表示。
CommentUpdateState 會傳回下列狀態：
NO_UPDATES_REQUESTED：批次作業中未要求更新任何留言。ALL_SAVED：所有要求的留言更新都已成功套用。ALL_FAILED_UNKNOWN_REASON：所有要求更新的註解都無法儲存，即使其他試算表變更可能已提交。