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

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

注: Google Drive API は、BLOB ファイルではアンカーなしのコメントのみをサポートしています。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 メソッドを呼び出します。

領域の定義方法は、処理するドキュメント コンテンツのタイプによって異なります。詳細については、リージョンを定義するをご覧ください。

注: ユーザーがコメントを追加する権限を持っていることを確認することをおすすめします。また、コメントや返信を削除または編集できるのは、コメントや返信の作成者のみです。クリエイター以外のロールのユーザーがコメントを削除または編集しようとすると、エラーが発生します。これらのエラーを回避するには、コメント リソースの 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 で各コメントがどのリビジョンに属するかを明確に示す必要があります。

コメントを取得する

ファイルに関するコメントを取得するには、comments リソースで get メソッドを使用し、fileId パラメータと commentId パラメータを指定します。コメント 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: 前回のリスト呼び出しから受け取ったページトークン。後続のページを取得するには、このトークンを指定します。

• 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