管理评论和回复

评论是用户对文件提供的反馈，例如，文字处理文档的读者建议如何重述某个句子。注释分为两种类型：锚定注释和未锚定注释。锚定注释与特定位置文档的特定位置相关联，例如文字处理文档中某个句子。反之，未锚定的评论只与文档相关联。

注意 ：在 blob 文件中，Google Drive API 仅支持非锚定注释。不支持在 Blob 文件或 Google 文档编辑器文件中添加锚定评论。

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

添加非锚定评论

如需向文档添加非锚定注释，请使用 fileId 参数和包含注释的 comments 资源调用 comments.create 方法。

评论会以纯文本形式插入，但响应正文会提供一个 htmlContent 字段，其中包含经过格式设置以供显示的内容。

重要提示： 我们建议您检查用户是否拥有添加评论的正确权限。此外，只有评论或回复的创作者才能删除或修改评论或回复。如果具有非创作者角色的用户尝试删除或修改评论，则会发生错误。为避免出现这些错误，请检查评论资源的 author.me 字段，确保发出请求的用户是评论的作者，然后验证他们对评论的权限。

添加对评论的回复

如需对评论添加回复，请使用评论、fileId 参数和包含回复的 replies 资源调用 replies.create 方法。

回复会以纯文本形式插入，但响应正文会提供一个 htmlContent 字段，其中包含采用适合显示的格式的内容。

向文档的最新修订版本添加锚定评论

添加评论时，您可能需要将其锚定到文件中的某个区域。锚点用于定义注释引用的文件中的文件修订版本和区域。comments 资源将 anchor 字段定义为 JSON 字符串。

注意 ：对于 blob 文件，Drive API 仅支持未锚定的注释。不支持在 blob 文件或 Google 文档编辑器文件中使用锚定评论。

重要提示： 锚点不可变，在不同修订版本之间，其相对于文档内容的位置无法保证。我们建议您在位置不会发生变化的文档（例如图片文件或只读文档）中使用锚点。

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

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

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

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

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

指定区域

如前所述，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。

重要提示： 如果您的应用允许用户更新和分享文档的多个修订版本，则对旧修订版本的评论可能不再适用于锚定位置。因此，您必须在界面中明确指明每个注释属于哪个修订版本。

解决评论

在解决了评论后，使用 comment.update 方法将 comments 资源中的 resolved 属性设置为 true。

当应用将 resolved 属性设置为 true 时，界面应指示注释已得到解决。例如，您的应用可能会：

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

删除评论

使用 comments.delete 方法删除评论。删除评论后，云端硬盘会将评论资源标记为 "deleted": "true"。

列出评论

使用 comments.list 方法列出评论。如果您希望在结果中包含已删除的评论，请将 includedDeleted 字段设置为 true。