Google Trang tính cho phép người dùng cộng tác bằng cách thêm nhận xét vào các ô cụ thể.
Tài liệu này trình bày cách bạn có thể sử dụng Google Sheets API để đọc, tạo, trả lời, cập nhật hoặc xoá nhận xét theo phương thức lập trình.
Đọc nhận xét
Khi bạn sử dụng phương thức get trên tài nguyên spreadsheets để truy xuất một bảng tính, theo mặc định, các chuỗi bình luận và điểm neo sẽ bị bỏ qua.
Để đưa bình luận vào phản hồi, hãy đặt tham số truy vấn commentsViewMode thành COMMENTS_VIEW_MODE_INCLUDED.
Ngoài ra, nếu người dùng gọi có quyền truy cập vào bình luận trên tệp, thì việc đặt tham số truy vấn thành COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS cũng sẽ trả về bình luận.
Cả trường comments và sheets.commentAnchors đều được trả về trong phản hồi.
Mã mẫu sau đây cho biết cách sử dụng yêu cầu get để truy xuất các chuỗi bình luận và điểm neo (dải ô) của chúng từ một bảng tính:
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)
Trong phản hồi, các bình luận sẽ được trả về ở hai vị trí:
- Mảng
commentstoàn cục chứa các đối tượngCommentThread. - Mảng
sheets.commentAnchorschứa các đối tượngCommentAnchoránh xạ mã nhận dạng điểm neo của nhận xét với vị trí ô (dải ô).
Lọc bình luận theo dải ô hoặc trang tính
Khi truy xuất một bảng tính, bạn có thể lọc dữ liệu được trả về bằng cách chỉ định các dải ô (bằng cách sử dụng tham số truy vấn ranges trong phương thức spreadsheets.get) hoặc các trang tính (bằng cách sử dụng trường dataFilters trong nội dung yêu cầu của phương thức spreadsheets.getByDataFilter).
- Nếu bạn lọc theo dải ô hoặc trang tính: Chỉ những chuỗi bình luận được liên kết trong dải ô hoặc trang tính đã chỉ định mới được trả về. Những nhận xét không được liên kết (chẳng hạn như nhận xét có toạ độ ô ban đầu đã bị xoá) sẽ không được đưa vào.
- Nếu bạn không lọc theo dải ô hoặc trang tính: Tất cả chuỗi bình luận, kể cả bình luận không được liên kết, đều sẽ được trả về.
Phản hồi mẫu
Phản hồi JSON mẫu sau đây cho thấy một chuỗi bình luận được liên kết với ô A1 (hàng 0, cột 0) trên trang tính có mã nhận dạng là 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"
}
Tạo và quản lý bình luận
Bạn có thể thêm, chỉnh sửa và xoá bình luận hoặc câu trả lời theo cách lập trình bằng phương thức batchUpdate trên tài nguyên spreadsheets.
Khi thực hiện các bản cập nhật hàng loạt liên quan đến bình luận, bạn nên theo dõi để tránh trường hợp thất bại một phần. Để biết thêm thông tin, hãy xem phần Trạng thái cập nhật bình luận.
Chèn nhận xét
Để chèn một chuỗi bình luận vào bảng tính, hãy sử dụng đối tượng InsertCommentRequest. Bạn phải cung cấp nội dung văn bản của bình luận và coordinate nơi bình luận được liên kết bằng đối tượng GridCoordinate.
Mẫu JSON sau đây cho biết cách thêm một chuỗi bình luận chưa được chỉ định vào ô B2 (hàng 1, cột 1) trên trang tính có mã nhận dạng là 0:
{
"requests": [
{
"insertComment": {
"content": "This is a comment added using the API.",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Bạn có thể chỉ định một bình luận cho một người dùng cụ thể bằng cách cung cấp email của họ trong trường assigneeEmailAddress:
{
"requests": [
{
"insertComment": {
"content": "Please review the data in this cell.",
"assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Thêm câu trả lời hoặc thực hiện hành động
Để trả lời một chuỗi bình luận, giải quyết hoặc mở lại một chuỗi bình luận, hãy sử dụng đối tượng AddCommentReplyRequest.
Bạn phải cung cấp commentId và post, trong đó câu trả lời được biểu thị bằng một đối tượng Post.
Đối tượng Post chứa câu trả lời content và có thể tuỳ ý chỉ định commentAction (bao gồm cả hành động RESOLVE hoặc REOPEN chuỗi bình luận). Đối tượng này được biểu thị bằng một đối tượng CommentActionType.
Bạn cũng có thể chỉ định một assigneeEmail mới trong đối tượng Post để chỉ định lại một chuỗi bình luận.
Mẫu JSON sau đây cho thấy cách trả lời một chuỗi bình luận hiện có:
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
Mẫu JSON sau đây cho thấy cách giải quyết một chuỗi bình luận (không yêu cầu trường content):
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Mẫu JSON sau đây cho thấy cách chỉ định lại một chuỗi bình luận:
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "ASSIGNEE_EMAIL"
}
}
}
]
}
Chỉnh sửa bài đăng
Để chỉnh sửa nội dung văn bản của một bài đăng mà bạn đã viết, hãy sử dụng đối tượng UpdateCommentPostRequest. Bạn phải chỉ định commentId của luồng, postId của bài đăng mà bạn muốn chỉnh sửa và content văn bản thuần tuý mới.
Mẫu JSON sau đây cho thấy cách chỉnh sửa một bài đăng:
{
"requests": [
{
"updateCommentPost": {
"commentId": "COMMENT_ID",
"postId": "POST_ID",
"content": "This is the updated comment text."
}
}
]
}
Xoá bình luận và câu trả lời
Bạn có thể xoá bình luận và phản hồi theo 2 cách:
Xoá một chuỗi bình luận: Để xoá toàn bộ
CommentThread, hãy dùng đối tượngDeleteCommentRequest. Bạn chỉ có thể xoá một chuỗi bình luận nếu bạn là tác giả củaheadPostcủa chuỗi đó trong đối tượngCommentThread.Xoá câu trả lời: Để xoá một câu trả lời cụ thể
PostkhỏiCommentThread, hãy dùng đối tượngDeleteCommentReplyRequest. Bạn chỉ có thể xoá những câu trả lời do chính mình viết. Bạn không thể xoá bài đăng phản hồi có chứacommentActionhoặcassigneeEmail.
Mẫu JSON sau đây cho thấy cách xoá một chuỗi bình luận:
{
"requests": [
{
"deleteComment": {
"commentId": "COMMENT_ID"
}
}
]
}
Trạng thái cập nhật bình luận
Các yêu cầu cần lưu chuỗi bình luận (chẳng hạn như chèn bình luận hoặc thêm câu trả lời) có thể gặp phải lỗi một phần. Trong những trường hợp này, các thay đổi về mô hình bảng tính (chẳng hạn như cập nhật giá trị ô hoặc thêm trang tính) có thể được xác nhận thành công, nhưng các bình luận liên quan có thể không lưu được.
Bạn có thể xác minh xem các nội dung cập nhật bình luận có được áp dụng thành công hay không bằng cách kiểm tra trường commentUpdateState trong phần nội dung phản hồi của phương thức spreadsheets.batchUpdate. Trường này được biểu thị bằng một đối tượng CommentUpdateState.
Các trạng thái sau đây được trả về trong CommentUpdateState:
NO_UPDATES_REQUESTED: Không có yêu cầu cập nhật bình luận nào trong thao tác hàng loạt.ALL_SAVED: Tất cả nội dung cập nhật bình luận được yêu cầu đều đã được áp dụng thành công.ALL_FAILED_UNKNOWN_REASON: Không lưu được tất cả nội dung cập nhật nhận xét theo yêu cầu, mặc dù các thay đổi khác đối với bảng tính có thể đã được thực hiện.