Google ドキュメントでは、共同編集者がコメントを書き込んだり、提案を行ったりすることで共同編集できます。提案は、承認待ちの遅延編集として機能します。
API を使用すると、ドキュメントのテキスト内で提案された変更をインラインで確認できます。デベロッパー プレビューでは、コメントと提案のスレッドをプログラムで読み取り、作成、返信、更新、削除することもできます。
documents.get メソッドを使用してドキュメントのコンテンツを取得すると、未解決の候補がコンテンツに含まれることがあります。documents.get が候補を表す方法を制御するには、オプションの SuggestionsViewMode パラメータを使用します。このパラメータでは、次のフィルタ条件を使用できます。
SUGGESTIONS_INLINEを使用してコンテンツを取得し、削除または挿入が保留中のテキストをドキュメントに表示します。- すべての提案が承認された状態で、コンテンツをプレビューとして取得します。
- 提案なしで、すべての提案が拒否された状態で、コンテンツをプレビューとして取得します。
SuggestionsViewMode を指定しない場合、Google ドキュメント API は現在のユーザーの権限に適したデフォルト設定を使用します。
候補とインデックス
SuggestionsViewMode が重要な理由の 1 つは、以下に示すように、レスポンスのインデックスが候補があるかどうかによって異なる可能性があるためです。
| 提案を含むコンテンツ | 候補のないコンテンツ |
|---|---|
{
"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"
}
}
}
]
}
}
}
]
},
|
上記のレスポンスでは、「Text following the suggestion」という行を含む段落に、SuggestionsViewMode を使用した場合の違いが示されています。値を SUGGESTIONS_INLINE に設定すると、ParagraphElement の startIndex は 51 から始まり、endIndex は 81 で停止します。候補がない場合、startIndex と endIndex の範囲は 32 ～ 62 です。
候補なしでコンテンツを取得する
次のコードサンプルの一部は、SuggestionsViewMode パラメータを PREVIEW_WITHOUT_SUGGESTIONS に設定して、すべての候補を拒否（候補がある場合）したドキュメントをプレビューとして取得する方法を示しています。
Java
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 が小さなチャンクに分割されることはあります。スタイル変更の提案に関するアノテーションが追加されるだけです。
このようなアノテーションの 1 つに SuggestedTextStyle があります。これは次の 2 つの部分で構成されます。
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] }
上記の例では、段落は 3 つのテキスト実行で構成され、6 行目、14 行目、50 行目から始まります。中央のテキスト実行を調べます。
- 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"
}
}
]
}
コメントと提案のステータスを更新する
コメントや提案のスレッドの保存が必要なリクエスト（コメントの挿入、返信の追加、提案など）は、部分的に失敗する可能性があります。このような場合、ドキュメント モデルの変更（テキストの挿入や削除など）はドキュメント モデルに正常にコミットされる可能性がありますが、関連するコメントや提案は保存されない可能性があります。
コメントまたは提案の更新が正常に適用されたかどうかを確認するには、BatchUpdateDocumentResponse の commentUpdateState フィールドを確認します。
CommentUpdateState で返される状態は次のとおりです。
NO_UPDATES_REQUESTED: バッチ オペレーションでコメントや提案の更新がリクエストされませんでした。ALL_SAVED: リクエストされたコメントまたは提案の更新がすべて正常に適用されました。ALL_FAILED_UNKNOWN_REASON: ドキュメント モデルの変更が commit された場合でも、リクエストされたコメントや提案の更新がすべて保存されませんでした。