Google Docs를 사용하면 공동작업자가 댓글을 작성하고 승인을 기다리는 지연된 수정사항 역할을 하는 수정 제안을 통해 공동작업할 수 있습니다.
API를 사용하여 문서 텍스트 내에서 제안된 변경사항을 인라인으로 볼 수 있습니다. 개발자 미리보기에서는 댓글 및 제안 스레드를 프로그래매틱 방식으로 읽거나, 만들거나, 답글을 달거나, 업데이트하거나, 삭제할 수도 있습니다.
documents.get 메서드를 사용하여 문서 콘텐츠를 가져오면 콘텐츠에 해결되지 않은 제안이 포함될 수 있습니다. documents.get가 추천을 나타내는 방식을 제어하려면 선택적 SuggestionsViewMode 매개변수를 사용하세요. 이 매개변수와 함께 사용할 수 있는 필터 조건은 다음과 같습니다.
SUGGESTIONS_INLINE로 콘텐츠를 가져와 삭제 또는 삽입 대기 중인 텍스트가 문서에 표시되도록 합니다.- 모든 제안이 수락된 콘텐츠를 미리보기로 가져옵니다.
- 모든 제안이 거부된 상태로 제안 없이 콘텐츠를 미리보기로 가져옵니다.
SuggestionsViewMode를 제공하지 않으면 Google Docs API는 현재 사용자의 권한에 적합한 기본 설정을 사용합니다.
추천 및 색인
SuggestionsViewMode가 중요한 한 가지 이유는 아래와 같이 제안이 있는지에 따라 대답의 색인이 달라질 수 있기 때문입니다.
| 추천이 포함된 콘텐츠 | 추천이 없는 콘텐츠 |
|---|---|
{
"tabs": [
{
"documentTab": {
"body": {
"content": [
{
"startIndex": 1,
"endIndex": 31,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 31,
"textRun": {
"content": "Text preceding the suggestion\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
},
{
"startIndex": 31,
"endIndex": 51,
"paragraph": {
"elements": [
{
"startIndex": 31,
"endIndex": 50,
"textRun": {
"content": "Suggested insertion",
"suggestedInsertionIds": [
"suggest.vcti8ewm4mww"
],
"textStyle": {}
}
},
{
"startIndex": 50,
"endIndex": 51,
"textRun": {
"content": "\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
},
{
"startIndex": 51,
"endIndex": 81,
"paragraph": {
"elements": [
{
"startIndex": 51,
"endIndex": 81,
"textRun": {
"content": "Text following the suggestion\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
},
|
{
"tabs": [
{
"documentTab": {
"body": {
"content": [
{
"startIndex": 1,
"endIndex": 31,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 31,
"textRun": {
"content": "Text preceding the suggestion\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
},
{
"startIndex": 31,
"endIndex": 32,
"paragraph": {
"elements": [
{
"startIndex": 31,
"endIndex": 32,
"textRun": {
"content": "\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
},
{
"startIndex": 32,
"endIndex": 62,
"paragraph": {
"elements": [
{
"startIndex": 32,
"endIndex": 62,
"textRun": {
"content": "Text following the suggestion\n",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
},
|
위의 대답에서 '추천 다음의 텍스트'라는 줄이 포함된 단락은 SuggestionsViewMode를 사용할 때의 차이점을 보여줍니다. 값이 SUGGESTIONS_INLINE로 설정되면 ParagraphElement의 startIndex이 51에서 시작하고 endIndex이 81에서 중지됩니다. 추천이 없으면 startIndex 및 endIndex 범위는 32~62입니다.
추천 없이 콘텐츠 가져오기
다음 부분 코드 샘플은 SuggestionsViewMode 매개변수를 PREVIEW_WITHOUT_SUGGESTIONS로 설정하여 모든 제안이 거부된 문서 (있는 경우)를 미리보기로 가져오는 방법을 보여줍니다.
자바
final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"; Document doc = service .documents() .get(DOCUMENT_ID) .setIncludeTabsContent(true) .setSuggestionsViewMode(SUGGEST_MODE) .execute();
Python
SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS" result = ( service.documents() .get( documentId=DOCUMENT_ID, includeTabsContent=True, suggestionsViewMode=SUGGEST_MODE, ) .execute() )
SuggestionsViewMode 매개변수를 생략하는 것은 DEFAULT_FOR_CURRENT_ACCESS을 매개변수 값으로 제공하는 것과 같습니다.
스타일 제안
문서에 스타일 제안이 있을 수도 있습니다. 콘텐츠 변경사항이 아닌 서식 및 프레젠테이션에 대한 제안된 변경사항입니다.
텍스트 삽입 또는 삭제와 달리 이러한 변경사항은 색인을 오프셋하지는 않지만 TextRun을 더 작은 청크로 나눌 수는 있습니다. 제안된 스타일 변경에 관한 주석만 추가합니다.
이러한 주석 중 하나는 SuggestedTextStyle이며, 이는 다음 두 부분으로 구성됩니다.
textStyle: 제안된 변경사항이 적용된 후 텍스트의 스타일을 설명하지만 변경된 내용은 설명하지 않습니다.textStyleSuggestionState: 추천이textStyle의 필드를 어떻게 변경하는지 나타냅니다.
다음 문서 탭 추출에서 이를 확인할 수 있습니다. 여기에는 추천 스타일 변경사항이 포함되어 있습니다.
[01] "paragraph": {
[02] "elements": [
[03] {
[04] "endIndex": 106,
[05] "startIndex": 82,
[06] "textRun": {
[07] "content": "Some text that does not ",
[08] "textStyle": {}
[09] }
[10] },
[11] {
[12] "endIndex": 115,
[13] "startIndex": 106,
[14] "textRun": {
[15] "content": "initially",
[16] "suggestedTextStyleChanges": {
[17] "suggest.xymysbs9zldp": {
[18] "textStyle": {
[19] "backgroundColor": {},
[20] "baselineOffset": "NONE",
[21] "bold": true,
[22] "fontSize": {
[23] "magnitude": 11,
[24] "unit": "PT"
[25] },
[26] "foregroundColor": {
[27] "color": {
[28] "rgbColor": {}
[29] }
[30] },
[31] "italic": false,
[32] "smallCaps": false,
[33] "strikethrough": false,
[34] "underline": false
[35] },
[36] "textStyleSuggestionState": {
[37] "boldSuggested": true,
[38] "weightedFontFamilySuggested": true
[39] }
[40] }
[41] },
[42] "textStyle": {
[43] "italic": true
[44] }
[45] }
[46] },
[47] {
[48] "endIndex": 143,
[49] "startIndex": 115,
[50] "textRun": {
[51] "content": " contain any boldface text.\n",
[52] "textStyle": {}
[53] }
[54] }
[55] ],
[56] "paragraphStyle": {
[57] "direction": "LEFT_TO_RIGHT",
[58] "namedStyleType": "NORMAL_TEXT"
[59] }
[60] }
위 샘플에서 단락은 6번째 줄, 14번째 줄, 50번째 줄에서 시작하는 3개의 텍스트 실행으로 구성됩니다. 중간 텍스트 실행을 검사합니다.
- 16번째 줄:
suggestedTextStyleChanges객체가 있습니다. - 18번째 줄:
textStyle는 다양한 서식을 지정합니다. - 36번째 줄:
textStyleSuggestionState는 이 사양에서 굵게 표시된 부분만 제안되었음을 나타냅니다. - 42번째 줄: 이 텍스트 실행의 기울임꼴 스타일은 현재 문서의 일부이며 제안의 영향을 받지 않습니다.
textStyleSuggestionState에서 true로 설정된 스타일 기능만 추천에 포함됩니다.
댓글 만들기 및 관리
documents.batchUpdate 메서드를 사용하여 댓글과 답글을 프로그래매틱 방식으로 추가하고, 댓글을 수정하고, 댓글이나 답글을 삭제할 수 있습니다.
댓글 또는 제안이 포함된 일괄 업데이트를 실행할 때는 부분적인 실패가 발생할 수 있는지 모니터링해야 합니다. 자세한 내용은 의견 및 제안 업데이트 상태를 참고하세요.
댓글 삽입
댓글 대화목록을 삽입하려면 InsertCommentRequest 객체를 사용합니다. 댓글 텍스트 콘텐츠와 댓글이 첨부된 앵커 위치 (예: 범위)를 제공해야 합니다.
다음 JSON 예에서는 지정된 범위에 할당되지 않은 댓글 대화목록을 추가합니다.
{
"requests": [
{
"insertComment": {
"content": "This is a comment added via the API.",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
assigneeEmailAddress 필드에 이메일을 제공하여 특정 사용자에게 댓글을 할당할 수 있습니다.
{
"requests": [
{
"insertComment": {
"content": "Please review this paragraph.",
"assigneeEmailAddress": "user@example.com",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
답글 추가 또는 조치 취하기
댓글 또는 제안 대화목록에 답글을 달거나 대화목록을 해결 또는 다시 열려면 AddCommentReplyRequest을 사용합니다.
답글은 Post 객체로 표현됩니다.
Post 객체에는 답장 content이 포함되며 선택적으로 commentAction(스레드를 RESOLVE 또는 REOPEN)를 지정할 수 있습니다.
다음은 기존 댓글 대화목록에 대한 샘플 답글입니다.
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
다음 샘플은 콘텐츠가 필요하지 않은 댓글 대화목록을 해결합니다.
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
게시물 수정하기
내가 작성한 게시물의 텍스트 콘텐츠를 수정하려면 UpdateCommentPostRequest를 사용합니다.
수정하려는 게시물의 스레드 ID (commentId 또는 suggestionId), postId, 새 일반 텍스트 content를 지정해야 합니다.
추천 스레드의 헤드 게시물은 수정할 수 없습니다 (추천 모드 수정으로 생성됨).
{
"requests": [
{
"updateCommentPost": {
"commentId": "comment_thread_id",
"postId": "post_id",
"content": "This is the updated comment text."
}
}
]
}
댓글 및 답글 삭제
- 댓글 대화목록 삭제: 전체 댓글 대화목록을 삭제하려면
DeleteCommentRequest를 사용합니다. 댓글 대화목록은 대화목록의 헤드 게시물 작성자만 삭제할 수 있습니다. - 답글 삭제: 특정 답글 게시물을 삭제하려면
DeleteCommentReplyRequest를 사용합니다. 내가 작성한 답글만 삭제할 수 있습니다. 작업 또는 담당자가 포함된 답글은 삭제할 수 없습니다.
다음 샘플은 댓글 대화목록을 삭제합니다.
{
"requests": [
{
"deleteComment": {
"commentId": "comment_thread_id"
}
}
]
}
추천 작성 및 추천 스레드 관리
직접 수정하는 대신 수정사항을 제안으로 작성하고 제안 스레드를 프로그래매틱 방식으로 수락, 거부 또는 삭제할 수 있습니다.
추천이 포함된 일괄 업데이트를 실행할 때는 부분적인 실패가 발생할 수 있는지 모니터링해야 합니다. 자세한 내용은 의견 및 제안 업데이트 상태를 참고하세요.
추천 모드를 사용하여 제안 만들기
수정사항을 제안으로 적용하려면 일괄 업데이트 요청에서 WriteControl 객체의 writeMode 필드를 SUGGEST로 설정합니다. 요청의 모든 업데이트가 제안으로 처리됩니다.
{
"requests": [
{
"insertText": {
"text": "suggested insertion text",
"location": {
"index": 1
}
}
}
],
"writeControl": {
"writeMode": "SUGGEST"
}
}
추천 모드에서 지원되지 않는 요청
WriteMode.SUGGEST를 사용하는 경우 다음 요청 유형은 지원되지 않으며 오류를 반환합니다.
AddDocumentTabCreateNamedRangeDeleteFooterDeleteHeaderDeleteNamedRangeDeleteTabUpdateDocumentTabPropertiesUpdateTableColumnProperties
또한 문서 형식이나 머리글/바닥글 설정에 대한 변경사항을 제안할 수 없습니다. UpdateDocumentStyle에서는 다음 스타일 유형에 대한 제안이 지원되지 않습니다.
documentFormatuseEvenPageHeaderFooteruseFirstPageHeaderFooter
추천 스레드 수락, 거부 또는 삭제
다음 요청을 사용하여 추천 스레드를 관리할 수 있습니다.
- 추천 수락:
AcceptSuggestionRequest을 사용하여 추천을 수락합니다. 문서에 대한 수정 액세스 권한이 필요합니다. - 추천 거부:
RejectSuggestionRequest를 사용하여 추천을 거부합니다. 이 작업을 수행하려면 문서에 대한 수정 액세스 권한이 있거나 제안의 작성자여야 합니다. - 추천 삭제:
DeleteSuggestionRequest를 사용하여 추천을 삭제합니다. 이를 위해서는 제안의 작성자여야 합니다.
다음 샘플은 추천 스레드를 허용합니다.
{
"requests": [
{
"acceptSuggestion": {
"suggestionId": "suggestion_thread_id"
}
}
]
}
댓글 및 제안 업데이트 상태
댓글 또는 제안 대화목록을 저장해야 하는 요청 (예: 댓글 삽입, 답글 추가, 제안하기)은 부분적으로 실패할 수 있습니다. 이러한 경우 문서 모델 변경사항 (예: 텍스트 삽입 또는 삭제)은 Docs 모델에 커밋될 수 있지만 연결된 댓글이나 제안사항은 저장되지 않을 수 있습니다.
BatchUpdateDocumentResponse에서 commentUpdateState 필드를 확인하여 댓글 또는 제안 업데이트가 성공적으로 적용되었는지 확인할 수 있습니다.
CommentUpdateState에는 다음 상태가 반환됩니다.
NO_UPDATES_REQUESTED: 일괄 작업에서 댓글 또는 제안 업데이트가 요청되지 않았습니다.ALL_SAVED: 요청된 모든 댓글 또는 제안 업데이트가 성공적으로 적용되었습니다.ALL_FAILED_UNKNOWN_REASON: Docs 모델 변경사항이 커밋되었을 수 있지만 요청된 모든 댓글 또는 제안 업데이트를 저장하지 못했습니다.