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배열- 댓글 앵커 ID를 셀 위치 (그리드 범위)에 매핑하는
CommentAnchor객체를 포함하는sheets.commentAnchors배열입니다.
범위 또는 시트로 댓글 필터링
스프레드시트를 가져올 때 spreadsheets.get 메서드의 ranges 쿼리 매개변수를 사용하여 범위를 지정하거나 spreadsheets.getByDataFilter 메서드의 요청 본문에서 dataFilters 필드를 사용하여 시트를 지정하여 반환된 데이터를 필터링할 수 있습니다.
- 범위 또는 시트로 필터링하는 경우: 지정된 범위 또는 시트 내에 고정된 댓글 스레드만 반환됩니다. 고정되지 않은 댓글(예: 원래 셀 좌표가 삭제된 댓글)은 포함되지 않습니다.
- 범위 또는 시트로 필터링하지 않는 경우: 고정되지 않은 댓글을 포함한 모든 댓글 스레드가 반환됩니다.
샘플 응답
다음 JSON 샘플 응답은 ID가 0인 시트의 A1 셀(행 0, 열 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 객체를 사용합니다.
답변이 Post 객체로 표시되는 경우 commentId 및 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: 다른 스프레드시트 변경사항이 커밋되었을 수 있지만 요청된 모든 댓글 업데이트가 저장되지 않았습니다.