コメントと返信を管理する

コメントは、ファイルに関するユーザー提供のフィードバックです。たとえば、ワード プロセッシング ドキュメントの読者が文の言い換え方を提案するなどです。コメントには、アンカー付きコメントとアンカーなしコメントの 2 種類があります。アンカー付きコメントは、特定のバージョンのドキュメント内の特定の場所（ワープロ ドキュメント内の文など）に関連付けられます。アンカーのないコメントは、ドキュメントに関連付けられているだけです。

注: Blob ファイルの場合、Google Drive API はアンカーなしのコメントのみをサポートします。Blob ファイルまたは Google ドキュメント エディタ ファイルのアンカリング コメントはサポートされていません。

返信はコメントに添付され、コメントに対するユーザーの返信を表します。Drive API を使用すると、ユーザーはアプリによって作成されたドキュメントにコメントと返信を追加できます。コメントと返信をまとめてディスカッションと呼びます。

comments リソースのすべてのメソッド（delete を除く）で、fields システム パラメータを設定して、レスポンスで返すフィールドを指定する必要があります。ほとんどの Drive メソッドでは、このアクションはデフォルト以外のフィールドを返す場合にのみ必要ですが、comments リソースでは必須です。パラメータを省略すると、メソッドはエラーを返します。詳細については、特定のフィールドを返すをご覧ください。

アンカーなしのコメントを追加する

アンカーのないコメントをドキュメントに追加するには、fileId パラメータとコメントを含む comments リソースを指定して create メソッドを呼び出します。

コメントはプレーンテキストとして挿入されますが、レスポンスの本文には、表示用にフォーマットされたコンテンツを含む htmlContent フィールドが用意されています。

重要: コメントを追加する適切な権限がユーザーに付与されていることを確認することをおすすめします。また、コメントや返信を削除または編集できるのは、コメントや返信の作成者のみです。クリエイター以外のロールのユーザーがコメントを削除または編集しようとすると、エラーが発生します。これらのエラーを回避するには、comments リソースの author.me フィールドをチェックして、リクエストを行ったユーザーがコメントの作成者であることを確認してから、コメントに関する権限を確認します。

コメントに返信を追加する

コメントに返信を追加するには、replies リソースで fileId パラメータと commentId パラメータを使用して 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 フィールドを設定して、コメントを閉じる返信を追加することもできます。

コメントが解決されると、ドライブはコメント リソースを 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 文字列として定義します。

注: Blob ファイルの場合、Drive API はアンカーなしのコメントのみをサポートします。Blob ファイルまたは Google ドキュメント エディタ ファイルのアンカリングされたコメントはサポートされていません。

重要: アンカーは不変であり、ドキュメントのコンテンツに対するアンカーの位置は、リビジョン間で保証されません。アンカーは、位置が変更されないドキュメント（画像ファイルや読み取り専用ドキュメントなど）で使用することをおすすめします。

アンカー付きコメントを追加するには:

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 の地域分類子のリストについては、地域分類子をご覧ください。

次の例は、ドキュメントの 2 つの異なる領域の行にコメントをアンカーする JSON アンカー文字列を示しています。

• 最初の領域は 12 行目（'n':12）から始まり、3 行（'l':3）にわたっています。
• 2 番目の領域は、行 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: 前の list 呼び出しから受け取ったページトークン。後続のページを取得するには、このトークンを指定します。

• 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 メソッドを使用します。

コメントが削除されると、ドライブはコメント リソースを deleted: true としてマークします。削除されたコメントには、htmlContent フィールドと content フィールドが含まれません。

リクエスト

この例では、fileId パス パラメータと commentId パス パラメータを指定します。

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