댓글 관리

Google Sheets를 사용하면 사용자가 특정 셀에 댓글을 추가하여 공동작업할 수 있습니다.

이 문서에서는 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 배열

범위 또는 시트로 댓글 필터링

스프레드시트를 가져올 때 범위를 지정하여 반환된 데이터를 필터링할 수 있습니다 (ranges 메서드의 spreadsheets.get 쿼리 매개변수 사용) 또는 시트 (dataFilters 메서드의 요청 본문에 있는 spreadsheets.getByDataFilter 필드 사용).

  • 범위 또는 시트로 필터링하는 경우: 지정된 범위 또는 시트 내에 고정된 댓글 대화목록만 반환됩니다. 고정되지 않은 댓글(예: 원래 셀 좌표가 삭제된 댓글)은 포함되지 않습니다.
  • 범위 또는 시트로 필터링하지 않는 경우: 고정되지 않은 댓글을 포함한 모든 댓글 대화목록이 반환됩니다.

샘플 응답

다음 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 객체를 사용합니다. 댓글 텍스트 콘텐츠와 댓글이 고정된 coordinate 를 GridCoordinate 객체를 사용하여 제공해야 합니다.

다음 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 작성자인 경우에만 댓글 대화목록을 삭제할 수 있습니다.

  • 답글 삭제: 특정 답글 Post을(를) CommentThread에서 삭제하려면 DeleteCommentReplyRequest 객체를 사용합니다. 작성한 답글만 삭제할 수 있습니다. commentAction 또는 assigneeEmail이 포함된 답글 게시물은 삭제할 수 없습니다.

다음 JSON 샘플은 댓글 대화목록을 삭제하는 방법을 보여줍니다.

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

댓글 업데이트 상태

댓글 삽입 또는 답글 추가와 같이 댓글 대화목록을 저장해야 하는 요청은 부분적으로 실패할 수 있습니다. 이러한 경우 스프레드시트 모델 변경사항 (예: 셀 값 업데이트 또는 시트 추가)은 성공적으로 커밋될 수 있지만 연결된 댓글은 저장되지 않을 수 있습니다.

commentUpdateState 필드를 확인하여 댓글 업데이트가 성공적으로 적용되었는지 확인할 수 있습니다.spreadsheets.batchUpdate 필드는 CommentUpdateState 객체로 표시됩니다.

다음 상태가 CommentUpdateState에 반환됩니다.

  • NO_UPDATES_REQUESTED: 일괄 작업에서 댓글 업데이트가 요청되지 않았습니다.
  • ALL_SAVED: 요청된 모든 댓글 업데이트가 성공적으로 적용되었습니다.
  • ALL_FAILED_UNKNOWN_REASON: 다른 스프레드시트 변경사항이 커밋되었을 수 있지만 요청된 모든 댓글 업데이트를 저장하지 못했습니다.