Google Docs API 댓글·수정 제안 자동화, 원문을 바로 바꾸지 않고 검수받는 법
자동 검수 프로그램이 Google Docs 문장을 바로 고치지 않고 ‘검토해 달라’는 형태로 남겨야 한다면, 2026년 9월 30일부터 Docs API의 댓글과 수정 제안 기능을 정식 API 흐름에 넣을 수 있습니다. 핵심은 검토 질문은 댓글로, 바꿀 문장은 제안 모드로 분리하는 것입니다. 둘을 섞어 쓸 때는 문서 위치와 저장 결과까지 확인해야 사람이 보는 Docs 화면과 자동화 상태가 어긋나지 않습니다.
같은 날 Google Sheets와 Slides도 댓글 API가 일반 제공 상태가 됐지만 범위는 같지 않습니다. Docs는 댓글과 수정 제안을 모두 다루고, Sheets는 셀 좌표에 댓글을 붙이며, Slides는 슬라이드·도형·텍스트·표 위치에 댓글을 붙입니다. 반면 2026년 10월 1일 공개된 Docs MCP 서버의 댓글 기능은 별도로 Developer Preview 상태입니다. REST API가 정식 제공됐다는 사실과 MCP 서버의 배포 상태를 한 기능처럼 보지 않아야 합니다.
댓글과 수정 제안은 목적부터 나눠야 합니다
자동화가 발견한 문제를 모두 본문 수정으로 처리하면 검토자가 무엇을 승인했는지 남기기 어렵습니다. 숫자 근거를 다시 확인해야 하거나 표현을 결정해야 하는 항목은 댓글이 맞습니다. 반대로 오탈자나 문장 교체처럼 ‘이 문장을 이렇게 바꾸자’가 명확한 경우에는 제안 모드가 더 자연스럽습니다. 제안은 사람이 수락하거나 거절하기 전까지 검토 대상으로 남기 때문에 원문을 즉시 확정하는 자동 편집과 성격이 다릅니다.
Docs API에서 댓글은 `InsertCommentRequest`로 만들고 문서의 `range`에 연결합니다. 특정 사람에게 확인을 맡겨야 하면 담당자 이메일을 함께 지정할 수 있습니다. 댓글 이후에는 `AddCommentReplyRequest`로 답글을 달거나 스레드를 해결·재열기할 수 있고, 자신이 작성한 댓글·답글은 수정 또는 삭제할 수 있습니다. 다만 제안 스레드의 첫 게시물은 제안 편집 결과에서 생성되므로 일반 댓글처럼 직접 고치는 대상이 아닙니다.
문서를 읽을 때 댓글과 제안 위치를 같은 기준으로 맞춥니다
자동 검수에서 가장 흔한 실수는 읽을 때 계산한 위치와 쓸 때 적용하는 위치가 달라지는 것입니다. 기존 제안이 포함된 문서는 제안 표시 방식에 따라 텍스트 인덱스가 달라질 수 있습니다. Google은 이후 `documents.batchUpdate`에 사용할 인덱스를 얻으려면 `SuggestionsViewMode`를 `SUGGESTIONS_INLINE`로 읽으라고 안내합니다. 제안을 제외한 미리보기 상태에서 얻은 인덱스를 그대로 쓰면 의도한 문장과 다른 위치를 가리킬 수 있습니다.
기존 댓글까지 함께 읽으려면 `commentsViewMode`에 댓글 포함 값을 사용합니다. 이때 Docs에서 댓글을 포함해 읽는 요청은 `includeTabsContent=true` 조건도 함께 맞춰야 합니다. 자동화는 ‘본문 텍스트 → 검수 위치 → 댓글/제안 작성’ 순서로 한 번에 계산하기보다, 먼저 같은 보기 모드로 문서와 기존 검토 상태를 읽은 뒤 그 응답의 범위를 기준으로 다음 요청을 만드는 편이 안전합니다.
문장 수정은 SUGGEST 모드로 보내고 수락 권한을 따로 봅니다
본문을 제안으로 남길 때는 `documents.batchUpdate`의 `writeControl.writeMode`를 `SUGGEST`로 설정합니다. 이 모드의 요청은 바로 확정 편집이 아니라 제안으로 처리됩니다. 이후 `AcceptSuggestionRequest`, `RejectSuggestionRequest`, `DeleteSuggestionRequest`로 제안 스레드를 처리할 수 있으며, 수락에는 문서 편집 권한이 필요합니다. 거절은 편집 권한이 있거나 해당 제안의 작성자여야 하고, 삭제는 제안 작성자 권한이 필요합니다.
제안 모드가 모든 종류의 Docs 변경을 대신하는 것은 아닙니다. 탭 추가·삭제, 머리글·바닥글 삭제, 이름이 지정된 범위 생성·삭제, 일부 문서 형식·헤더/푸터 스타일 변경 등은 제안 모드에서 지원되지 않습니다. 자동화 규칙을 만들 때는 텍스트 삽입·삭제 같은 ‘검토 가능한 문장 수정’과 문서 구조 변경을 같은 배치에 섞지 말고, 제안으로 보낼 수 없는 작업은 별도 승인 단계나 직접 편집 경로로 분리해야 합니다.
성공 응답만 보지 말고 commentUpdateState까지 확인합니다
댓글과 제안을 포함한 배치 업데이트에는 부분 실패 가능성이 있습니다. 공식 문서는 본문 삽입·삭제 같은 Docs 모델 변경이 저장됐는데 연결된 댓글이나 제안 저장은 실패할 수 있다고 명시합니다. 따라서 HTTP 요청이 끝났다는 사실만으로 검수 기록까지 남았다고 처리하면 안 됩니다.
`BatchUpdateDocumentResponse`의 `commentUpdateState`를 검사해 `ALL_SAVED`인지 확인합니다. `ALL_FAILED_UNKNOWN_REASON`이면 본문 쪽 변경이 반영됐을 가능성을 별도로 확인한 뒤 댓글·제안 생성만 재시도해야 합니다. 이 구분이 없으면 자동화가 같은 문장을 다시 수정하거나, 반대로 검토자에게 보낼 질문만 빠진 채 작업을 완료 처리할 수 있습니다. 재시도 키는 문서 ID와 대상 범위, 자동화 작업 ID를 함께 저장해 중복 실행을 막는 구조가 적합합니다.
Sheets와 Slides는 댓글의 앵커가 다릅니다
Sheets API의 댓글은 문서 텍스트 인덱스가 아니라 `GridCoordinate`로 셀 위치를 지정합니다. 예를 들어 B2라면 해당 시트 ID와 행·열 인덱스를 넣어 댓글을 붙입니다. 범위나 시트로 댓글을 조회할 수도 있으며, 원래 댓글이 붙은 셀 좌표가 삭제되면 해당 댓글이 앵커 없는 상태가 될 수 있으므로 행·열을 크게 재배치하는 자동화와 댓글 생성 순서를 같이 설계해야 합니다.
Slides API는 위치 표현이 더 다양합니다. 슬라이드 페이지나 페이지 요소의 `objectId`, 도형 안의 텍스트 범위, 표 셀의 텍스트 범위, 표의 셀 범위를 댓글 앵커로 사용할 수 있습니다. Docs·Sheets·Slides를 한 검수 서비스에서 묶더라도 ‘파일 ID + 문자열 위치’ 하나로 통일하지 말고 편집기별 앵커 타입을 별도 필드로 저장해야 나중에 원래 위치를 다시 찾을 수 있습니다.
Drive API 댓글로 우회하면 위치 댓글이 풀릴 수 있습니다
예전 방식처럼 Drive API의 comments 리소스를 모든 파일 형식에 공통으로 쓰는 설계는 주의가 필요합니다. Drive API는 자체 정의한 앵커 문자열을 저장할 수 있지만, Google Workspace 편집기는 그 앵커를 문서 내부 위치로 해석하지 않고 앵커 없는 댓글처럼 취급합니다. 반대로 Docs·Sheets·Slides에서 만든 댓글의 내부 앵커 데이터를 Drive API로 읽어도 Drive API는 문서 영역·셀 좌표·슬라이드 요소 의미를 해석하지 못합니다.
문서에서 특정 문장, 셀, 슬라이드 요소를 정확히 가리켜야 한다면 해당 편집기의 전용 API를 사용합니다. Drive API 댓글은 파일 전체에 붙는 일반 피드백이나 자체 뷰어용 앵커가 목적일 때 남겨 두는 편이 맞습니다. 이 경계를 정하지 않으면 자동화 로그에는 앵커 값이 있는데 사용자가 Docs 화면에서 보면 위치가 없는 댓글로 보이는 문제가 생깁니다.
안 보임·엉뚱한 위치·삭제 실패는 같은 오류가 아닙니다
자동화 결과가 Docs 화면에서 보이지 않는다면 먼저 댓글을 읽는 요청에 `commentsViewMode`가 포함됐는지, 탭 콘텐츠 조건이 맞는지 확인합니다. 댓글은 보이는데 엉뚱한 문장에 붙었다면 읽을 때 사용한 제안 보기 모드와 이후 batchUpdate에 사용한 인덱스를 비교합니다. 기존 제안이 있는 문서에서 `SUGGESTIONS_INLINE` 기준이 아니었다면 위치 계산부터 다시 해야 합니다.
삭제 요청만 실패하는 경우에는 작성자 조건을 확인합니다. Docs 댓글 스레드는 첫 게시물 작성자만 삭제할 수 있고, 답글 역시 자신이 쓴 것만 삭제할 수 있습니다. 동작이나 담당자 지정이 들어간 답글은 삭제 대상에서 제외됩니다. 이런 권한 오류를 재시도로 덮으면 같은 요청만 반복되므로, 작성자·스레드 상태·작업 종류를 실패 기록에 남기고 사람이 처리해야 할 건 별도 큐로 보내는 편이 낫습니다.
처음 연결할 때는 Cloud 프로젝트·OAuth와 API 상태를 따로 확인합니다
Google Docs API를 호출하려면 Google Cloud 프로젝트에서 Docs API를 사용 설정하고, 사용자 데이터에 접근하는 앱이라면 OAuth 동의 화면과 OAuth 2.0 클라이언트를 구성해야 합니다. Google의 Node.js 빠른 시작 문서는 테스트용 데스크톱 앱 예시에서 Google Auth platform의 Branding·Audience·Data Access를 설정하고, Clients에서 Desktop app 유형의 OAuth 클라이언트를 만드는 순서를 안내합니다. 실제 서버 서비스는 배포 형태에 맞는 자격 증명과 최소 권한 범위를 다시 정해야 합니다.
기능이 계정에서 예상대로 동작하지 않을 때는 ‘Docs 화면에 새 메뉴가 있는가’를 먼저 찾을 필요가 없습니다. 이번 변경은 사용자용 메뉴 추가가 아니라 API 기능 확장입니다. API 호출 권한, 파일에 대한 댓글·편집 권한, 사용 중인 클라이언트 라이브러리·요청 필드를 먼저 확인합니다. 또한 MCP로 같은 작업을 붙이는 경우에는 2026년 10월 1일 기준 Developer Preview라는 별도 상태를 적용해야 하므로, REST API의 일반 제공 상태를 MCP 설정에 그대로 대입하면 안 됩니다.
