管理留言

使用者可以在 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只有討論串的作者才能刪除討論串的 headPost CommentThread 物件。

  • 刪除回覆：如要從 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：所有要求更新的註解都無法儲存， 即使其他試算表變更可能已提交。