Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

コメントと提案を使用する

Google ドキュメントでは、共同編集者がコメントを書き込んだり、承認待ちの遅延編集として機能する候補を作成したりして、共同作業を行うことができます。

API を使用すると、ドキュメントテキスト内に候補の変更をインラインで表示できます。デベロッパープレビューでは、コメントと候補のスレッドをプログラムで読み取り、作成、返信、更新、削除することもできます。

documents.get メソッドを使用してドキュメントコンテンツを取得すると、未解決の候補が含まれる場合があります。でdocuments.get候補を表す方法を制御するには、オプションの SuggestionsViewMode パラメータを使用します。このパラメータでは、次のフィルタ条件を使用できます。

SUGGESTIONS_INLINE を使用してコンテンツを取得します。削除または挿入保留中のテキストがドキュメントに表示されます。
すべての候補が承認された状態で、コンテンツをプレビューとして取得します。
すべての候補が拒否された状態で、候補なしのプレビューとしてコンテンツを取得します。

SuggestionsViewMode が指定されていない場合、Google ドキュメント API は現在のユーザーの権限に適したデフォルト設定を使用します。

ドキュメントの取得時にコメントを含めるかどうかを制御するには、オプションの commentsViewMode パラメータを使用します。commentsViewMode を COMMENTS_VIEW_MODE_INCLUDED に設定する場合は、includeTabsContent を true に設定する必要があります。また、tabs フィールド（またはサブフィールド）を参照するフィールドマスクを使用すると、API はリクエストを includeTabsContent を true に設定した場合と同様に暗黙的に処理します。

候補とインデックス

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" } } } ] } } } ] },

候補を含むコンテンツ

候補を含まないコンテンツ

{
 "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 に設定されている場合、startIndex の ParagraphElement は 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 する）を指定できます。

Post オブジェクトに新しい assigneeEmail を指定して、コメントスレッドを再割り当てすることもできます。

次のサンプルは、既存のコメントスレッドに返信します。

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

次のサンプルは、コンテンツを必要としないコメントスレッドを解決します。

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

次の JSON サンプルは、コメントスレッドを再割り当てする方法を示しています。

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "user@example.com"
        }
      }
    }
  ]
}

投稿を編集する

作成した投稿のテキストコンテンツを編集するには、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 を使用する場合、次のリクエストタイプはサポートされておらず、エラーが返されます。

AddDocumentTab
CreateNamedRange
DeleteFooter
DeleteHeader
DeleteNamedRange
DeleteTab
UpdateDocumentTabProperties
UpdateTableColumnProperties

また、ドキュメントの形式やヘッダーとフッターの設定の変更を提案することはできません。UpdateDocumentStyle では、次のスタイルタイプで候補はサポートされていません。

documentFormat
useEvenPageHeaderFooter
useFirstPageHeaderFooter

候補スレッドを承認、拒否、削除する

次のリクエストを使用して、候補スレッドを管理できます。

候補を承認する: 候補を承認するには、AcceptSuggestionRequest を使用します。これには、ドキュメントの編集権限が必要です。
候補を拒否する: 候補を拒否するには、RejectSuggestionRequest を使用します。これには、ドキュメントの編集権限または候補の作成者である必要があります。
候補を削除する: 候補を削除するには、DeleteSuggestionRequest を使用します。これには、候補の作成者である必要があります。

次のサンプルは、候補スレッドを承認します。

{
  "requests": [
    {
      "acceptSuggestion": {
        "suggestionId": "suggestion_thread_id"
      }
    }
  ]
}

コメントと候補の更新ステータス

コメントまたは候補のスレッドの保存が必要なリクエスト（コメントの挿入、返信の追加、候補の作成など）で、部分的な失敗が発生する可能性があります。このような場合、ドキュメントモデルの変更（テキストの挿入や削除など）はドキュメントモデルに正常にコミットされる可能性がありますが、関連するコメントや候補は保存に失敗する可能性があります。

コメントまたは候補の更新が正常に適用されたかどうかを確認するには、commentUpdateState の BatchUpdateDocumentResponse フィールドを確認します。

CommentUpdateState では、次の状態が返されます。

NO_UPDATES_REQUESTED: バッチ処理でコメントまたは候補の更新がリクエストされていません。
ALL_SAVED: リクエストされたコメントまたは候補の更新がすべて正常に適用されました。
ALL_FAILED_UNKNOWN_REASON: ドキュメントモデルの変更がコミットされた場合でも、リクエストされたコメントまたは候補の更新がすべて保存に失敗しました。