管理评论和回复

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

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

对于 comments 资源上的所有方法（delete 除外），您必须设置 fields system 参数，以指定要在响应中返回的字段。在大多数 Drive 方法中，此操作仅在需要返回非默认字段时才需要，但对于 comments 资源，此操作是必需的。如果您省略该参数，该方法会返回错误。如需了解详情，请参阅返回特定字段。

添加未锚定的评论

如需向文档添加未锚定的评论，请调用 create 方法，并使用 fileId 参数和包含评论的 comments 资源。

评论以纯文本形式插入，但响应正文提供了一个 htmlContent 字段，其中包含格式化为可供显示的内容。

回复评论

如需向评论添加回复，请对 replies 资源使用 replies.create 方法，并提供 fileId 和 commentId 参数。请求正文使用 content 字段添加回复。

回复以纯文本形式插入，但响应正文提供了一个 htmlContent 字段，其中包含格式化为可显示的内容。

该方法会返回 fields 字段中列出的字段。

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 资源使用 replies.create 方法，并提供 fileId 和 commentId 参数。

请求正文使用 action 字段来解决评论。您还可以设置 content 字段以添加关闭评论的回复。

当评论被标记为已解决时，云端硬盘会将相应评论资源标记为 resolved: true。与已删除的评论不同，已解决的评论可以包含 htmlContent 或 content 字段。

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

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

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 字符串。

如需添加锚定评论，请执行以下操作：

1. （可选）调用 revisions.list 方法可列出文档的所有 revisionID。如果您想将评论锚定到最新修订版本以外的任何修订版本，请执行此步骤。 如果您想使用最新修订版本，请为 revisionID 使用 head。

2. 使用 fileID 参数（包含注释的 comments 资源）和包含 revisionID (r) 和区域 (a) 的 JSON 锚点字符串调用 create 方法。

如何定义区域取决于您处理的文档内容类型。如需了解详情，请参阅定义地区。

定义区域

如前所述，JSON 锚点字符串包含 revisionID (r) 和区域 (a)。区域 (a) 是一个 JSON 数组，其中包含用于指定注释锚定到的格式和位置的区域分类器。分类器可以是图片中的二维矩形、文档中的一行文字，也可以是视频中的一段时间。如需定义区域，请选择与您要锚定的内容类型相符的区域分类器。例如，如果您的内容是文本，您可能会使用 txt 或 line 区域分类器。

如需查看 Drive API 中的地区分类器列表，请参阅地区分类器。

以下示例展示了一个 JSON 锚点字符串，该字符串将注释锚定到文档中两个不同区域的行：

• 第一个区域从第 12 行 ('n':12) 开始，延伸三行 ('l':3)。
• 第二个区域仅涵盖第 18 行 ('n':18, 'l':1`)。

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

将 REVISION_ID 替换为 head 或特定修订版本的 ID。

获取评论

如需获取文件上的评论，请对 comments 资源使用 get 方法，并提供 fileId 和 commentId 参数。如果您不知道评论 ID，可以使用 list 方法列出所有评论。

该方法会返回 comments 资源的实例。

如需在结果中包含已删除的评论，请将 includedDeleted 查询参数设置为 true。

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 字段的最小值。

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 查询参数中列出的字段。

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 字段。

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