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

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

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

fields パラメータを使用する

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

コメントの制約

Drive API でアンカー付きコメントとアンカーなしコメントを操作する場合、次の制約が適用されます。

コメントの種類 ファイル形式
アンカー
  • デベロッパーは、アンカー仕様の独自の形式を定義できます。
  • アンカーは保存され、コメントの取得時に返されますが、Google Workspace エディタ アプリでは、これらのコメントはアンカーなしのコメントとして扱われます。
アンカーなし
  • Google Workspace ドキュメントでサポートされており、[すべてのコメント] ビューに表示されます。
  • アンカーのないコメントは、ドライブ ファイル プレビューアでレンダリングされた PDF には表示されませんが、保存されており、ドライブ API を介して取得できます。

ドキュメントの最新のリビジョンにアンカー付きコメントを追加する

コメントを追加する際に、ファイルの領域にアンカーを設定できます。アンカーは、コメントが参照するファイルの領域を定義します。comments リソースは、anchor フィールドを JSON 文字列として定義します。

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

  1. （省略可）revisions リソースで list メソッドを呼び出して、ドキュメントのすべての revisionID を一覧表示します。コメントを最新のリビジョン以外のリビジョンにアンカーする場合は、この手順に沿って操作します。最新のリビジョンを使用する場合は、revisionID に head を使用します。

  2. fileID パラメータ、コメントを含む comments リソース、revisionID（r）とリージョン（a）を含む JSON アンカー文字列を使用して、comments リソースで create メソッドを呼び出します。

次のコードサンプルは、アンカー付きコメントを作成する方法を示しています。

Python


from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

ドライブ API は、anchor 文字列を含む comments リソース オブジェクトのインスタンスを返します。

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

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

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

次のコードサンプルは、アンカーなしのコメントを作成する方法を示しています。

Python


from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

コメントに返信する

コメントに返信を追加するには、replies リソースで fileId パラメータと commentId パラメータを指定して 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."
}

コメントを解決する

コメントを解決するには、コメントに返信する必要があります。

コメントを解決するには、replies リソースで create メソッドを使用し、fileId パラメータと commentId パラメータを指定します。

リクエスト本文では、action フィールドを使用してコメントを解決します。content フィールドを設定して、コメントを閉じる返信を追加することもできます。

コメントが解決されると、ドライブは comments リソースを 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 リソースで fileId パラメータと commentId パラメータを指定して 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: 前回のリスト呼び出しから受け取ったページトークン。後続のページを取得するには、このトークンを指定します。

  • 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