管理评论和回复

注释是指用户针对文件提供的反馈，例如文字处理文档的读者建议如何改写某个句子。评论分为两种类型：锚定评论和非锚定评论。锚定注释与文档特定版本中的特定位置（例如字处理文档中的某个句子）相关联。相反，未锚定的评论仅与文档相关联。

回复会附加到评论中，表示用户对评论的回答。借助 Drive API，您的用户可以向您应用创建的文档添加评论和回复。评论和回复统称为讨论。

使用 fields 参数

对于 comments 资源上的所有方法（不包括 delete），您必须设置 fields system 参数，以指定要在响应中返回的字段。在大多数 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()

Drive API 会返回 comments 资源对象的实例，其中包含 anchor 字符串。

注意： 我们建议您检查用户是否拥有添加注释的正确权限。此外，只有评论或回复的创作者才能删除或修改评论或回复。当非创作者角色的用户尝试删除或修改评论时，系统会出错。为避免这些错误，请检查评论资源的 author.me 字段。

添加未锚定的评论

如需添加未锚定的注释，请使用 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()

重要提示： 建议您检查用户是否拥有添加评论的相应权限。此外，只有评论或回复的创作者才能删除或修改评论或回复。当非创建者角色的用户尝试删除或修改评论时，系统会出错。为避免这些错误，请检查 comments 资源的 author.me 字段，确保发出请求的用户是相应评论的作者，然后验证其与相应评论相关的权限。

回复评论

如需向评论添加回复，请对 replies 资源使用 create 方法，并提供 fileId 和 commentId 参数。请求正文使用 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 字段。

当应用解决评论后，界面应指明相应评论已得到处理。例如，您的应用可能：

• 禁止进一步回复，并使所有之前的回复以及原始评论变暗。
• 隐藏已解决的评论。

请求

在此示例中，我们提供了 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 资源使用 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

列出评论

如需列出文件中的评论，请对 comments 资源使用 list 方法，并提供 fileId 参数。该方法会返回一个评论列表。

传递以下查询参数可自定义评论的分页或过滤评论：

• 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)

更新评论

如需更新文件上的评论，请对 comments 资源使用 update 方法，并提供 fileId 和 commentId 参数。请求正文使用 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."
}

删除评论

如需删除文件中的评论，请对 comments 资源使用 delete 方法，并提供 fileId 和 commentId 参数。

删除评论后，云端硬盘会将相应评论资源标记为 deleted: true。已删除的评论不包含 htmlContent 或 content 字段。

请求

在此示例中，我们提供了 fileId 和 commentId 路径参数。

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

相关主题

• 文件和文件夹概览
• 管理文件修订版本