댓글 및 답글 관리

댓글은 사용자가 파일에 제공하는 의견입니다. 예를 들어 워드 프로세서 문서의 독자가 문장을 다시 작성하는 방법을 제안하는 의견이 있습니다. 댓글에는 고정 댓글과 고정되지 않은 댓글의 두 가지 유형이 있습니다. 고정된 댓글은 문서의 특정 버전 내에서 워드 프로세싱 문서의 문장과 같은 특정 위치와 연결됩니다. 반대로 앵커가 지정되지 않은 댓글은 문서와만 연결됩니다.

참고: blob 파일의 경우 Google Drive API는 앵커가 지정되지 않은 댓글만 지원합니다. blob 파일 또는 Google Docs 편집기 파일의 고정 댓글은 지원되지 않습니다.

답글은 댓글에 첨부되며 댓글에 대한 사용자의 응답을 나타냅니다. Drive API를 사용하면 사용자가 앱에서 만든 문서에 댓글과 답글을 추가할 수 있습니다. 답글이 있는 댓글을 통칭하여 토론이라고 합니다.

comments 리소스의 모든 메서드 (delete 제외)의 경우 fields 시스템 매개변수를 설정하여 응답에 반환할 필드를 지정해야 합니다. 대부분의 Drive 메서드에서 이 작업은 기본이 아닌 필드를 반환하는 데만 필요하지만 comments 리소스에는 필수입니다. 매개변수를 생략하면 메서드에서 오류를 반환합니다. 자세한 내용은 특정 필드 반환을 참고하세요.

고정되지 않은 댓글 추가

문서에 고정되지 않은 댓글을 추가하려면 fileId 매개변수와 댓글이 포함된 comments 리소스를 사용하여 create 메서드를 호출합니다.

댓글은 일반 텍스트로 삽입되지만 응답 본문은 표시를 위해 형식이 지정된 콘텐츠가 포함된 htmlContent 필드를 제공합니다.

중요: 사용자에게 댓글을 추가할 수 있는 올바른 권한이 있는지 확인하는 것이 좋습니다. 또한 댓글 또는 답글의 작성자만 댓글 또는 답글을 삭제하거나 수정할 수 있습니다. 크리에이터가 아닌 역할을 가진 사용자가 댓글을 삭제하거나 수정하려고 하면 오류가 발생합니다. 이러한 오류를 방지하려면 comments 리소스의 author.me 필드를 확인하여 요청을 하는 사용자가 댓글 작성자인지 확인한 다음 댓글에 대한 권한을 확인하세요.

댓글에 답글 추가하기

댓글에 답글을 추가하려면 fileId 및 commentId 매개변수와 함께 replies 리소스에서 replies.create 메서드를 사용합니다. 요청 본문은 content 필드를 사용하여 답글을 추가합니다.

답글은 일반 텍스트로 삽입되지만 응답 본문은 표시용으로 형식이 지정된 콘텐츠가 포함된 htmlContent 필드를 제공합니다.

이 메서드는 fields 필드에 나열된 필드를 반환합니다.

요청

이 예에서는 fileId 및 commentId 경로 매개변수와 여러 필드를 제공합니다.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

요청 본문

{
  "content": "This is a reply to a comment."
}

댓글 해결

댓글에 대한 답글을 게시해야만 댓글이 해결된 것으로 표시됩니다.

댓글을 해결하려면 fileId 및 commentId 매개변수와 함께 replies 리소스에서 replies.create 메서드를 사용합니다.

요청 본문은 action 필드를 사용하여 댓글을 해결합니다. content 필드를 설정하여 댓글을 종료하는 답글을 추가할 수도 있습니다.

댓글이 해결되면 Drive에서 댓글 리소스를 resolved: true로 표시합니다. 삭제된 댓글과 달리 해결된 댓글에는 htmlContent 또는 content 필드가 포함될 수 있습니다.

앱에서 댓글을 해결하면 UI에 댓글이 처리되었음을 표시해야 합니다. 예를 들어 앱에서 다음 작업을 할 수 있습니다.

• 추가 답글을 허용하지 않고 이전 답글과 원본 댓글을 모두 어둡게 표시합니다.
• 해결된 댓글 숨기기

요청

이 예에서는 fileId 및 commentId 경로 매개변수와 여러 필드를 제공합니다.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

요청 본문

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

문서의 최신 버전에 고정 댓글 추가하기

댓글을 추가할 때 파일의 특정 영역에 댓글을 고정할 수 있습니다. 앵커는 댓글이 참조하는 파일의 파일 수정사항과 영역을 정의합니다. comments 리소스는 anchor 필드를 JSON 문자열로 정의합니다.

참고: Drive API는 blob 파일에서 앵커가 지정되지 않은 댓글만 지원합니다. blob 파일 또는 Google Docs 편집기 파일의 고정 댓글은 지원되지 않습니다.

중요: 앵커는 변경할 수 없으며, 버전 간에 문서 콘텐츠에 대한 앵커의 위치가 보장되지 않습니다. 이미지 파일이나 읽기 전용 문서와 같이 위치가 변경되지 않는 문서에서는 앵커를 사용하는 것이 좋습니다.

고정 댓글을 추가하려면 다음 단계를 따르세요.

1. (선택사항) revisions.list 메서드를 호출하여 문서의 모든 revisionID를 나열합니다. 최신 버전이 아닌 버전에 댓글을 고정하려면 이 단계를 따르세요. 최신 버전을 사용하려면 revisionID에 head를 사용하세요.

2. fileID 매개변수, 댓글이 포함된 comments 리소스, revisionID(r) 및 지역 (a)이 포함된 JSON 앵커 문자열을 사용하여 create 메서드를 호출합니다.

영역을 정의하는 방법은 작업 중인 문서 콘텐츠의 유형에 따라 다릅니다. 자세한 내용은 리전 정의를 참고하세요.

참고: 사용자에게 댓글을 추가할 수 있는 올바른 권한이 있는지 확인하는 것이 좋습니다. 또한 댓글 또는 답글의 작성자만 댓글 또는 답글을 삭제하거나 수정할 수 있습니다. 크리에이터가 아닌 역할을 가진 사용자가 댓글을 삭제하거나 수정하려고 하면 오류가 발생합니다. 이러한 오류를 방지하려면 comments 리소스의 author.me 필드를 확인하세요.

지역 정의

앞서 언급한 것처럼 JSON 앵커 문자열에는 revisionID (r) 및 리전 (a)이 포함됩니다. 리전 (a)은 댓글이 고정되는 형식과 위치를 지정하는 리전 분류자가 포함된 JSON 배열입니다. 분류자는 이미지의 경우 2차원 직사각형, 문서의 경우 텍스트 줄, 동영상의 경우 시간일 수 있습니다. 리전을 정의하려면 고정하려는 콘텐츠 유형과 일치하는 리전 분류자를 선택합니다. 예를 들어 콘텐츠가 텍스트인 경우 txt 또는 line 지역 분류기를 사용할 가능성이 높습니다.

Drive API의 지역 분류자 목록은 지역 분류자를 참고하세요.

다음 예시에서는 문서의 두 개 별도 영역에 있는 줄에 댓글을 고정하는 JSON 앵커 문자열을 보여줍니다.

• 첫 번째 영역은 12번째 줄 ('n':12)에서 시작하여 3줄('l':3)에 걸쳐 있습니다.
• 두 번째 영역은 18번 줄 ('n':18, 'l':1`)만 포함합니다.

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

REVISION_ID를 head 또는 특정 버전의 ID로 바꿉니다.

중요: 사용자가 문서의 여러 수정 버전을 업데이트하고 공유할 수 있는 앱의 경우 이전 수정 버전에 대한 댓글이 고정된 위치에 더 이상 적용되지 않을 수 있습니다. 따라서 UI에서 각 댓글이 속한 수정 버전을 명확하게 표시해야 합니다.

댓글 가져오기

파일에 대한 댓글을 가져오려면 fileId 및 commentId 매개변수와 함께 comments 리소스에서 get 메서드를 사용합니다. 댓글 ID를 모르는 경우 list 메서드를 사용하여 모든 댓글을 나열할 수 있습니다.

이 메서드는 comments 리소스의 인스턴스를 반환합니다.

결과에 삭제된 댓글을 포함하려면 includedDeleted 쿼리 매개변수를 true로 설정합니다.

요청

이 예에서는 fileId 및 commentId 경로 매개변수와 여러 필드를 제공합니다.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

댓글 나열

파일의 댓글을 나열하려면 fileId 매개변수와 함께 comments 리소스에서 list 메서드를 사용합니다. 이 메서드는 댓글 목록을 반환합니다.

다음 쿼리 매개변수를 전달하여 댓글의 페이지로 나누기를 맞춤설정하거나 댓글을 필터링합니다.

• includeDeleted: 삭제된 댓글을 포함하려면 true로 설정합니다. 삭제된 댓글에는 htmlContent 또는 content 필드가 포함되지 않습니다.

• pageSize: 페이지당 반환할 최대 댓글 수입니다.

• pageToken: 이전 목록 호출에서 수신된 페이지 토큰입니다. 후속 페이지를 가져오려면 이 토큰을 제공하세요.

• startModifiedTime: 결과 의견의 modifiedTime 필드의 최소값입니다.

요청

이 예에서는 fileId 경로 매개변수, includeDeleted 쿼리 매개변수, 여러 필드를 제공합니다.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

댓글 업데이트

파일에 대한 댓글을 업데이트하려면 fileId 및 commentId 매개변수와 함께 comments 리소스에서 update 메서드를 사용합니다. 요청 본문은 content 필드를 사용하여 댓글을 업데이트합니다.

comments 리소스의 불리언 resolved 필드는 읽기 전용입니다. 댓글은 댓글에 답글을 게시해야만 해결할 수 있습니다. 자세한 내용은 댓글 해결을 참고하세요.

이 메서드는 fields 쿼리 매개변수에 나열된 필드를 반환합니다.

요청

이 예에서는 fileId 및 commentId 경로 매개변수와 여러 필드를 제공합니다.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

요청 본문

{
  "content": "This comment is now updated."
}

댓글 삭제

파일의 댓글을 삭제하려면 fileId 및 commentId 매개변수와 함께 comments 리소스에서 delete 메서드를 사용합니다.

댓글이 삭제되면 Drive에서 댓글 리소스를 deleted: true로 표시합니다. 삭제된 댓글에는 htmlContent 또는 content 필드가 포함되지 않습니다.

요청

이 예에서는 fileId 및 commentId 경로 매개변수를 제공합니다.

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID