管理审批

本文档介绍了如何在 Google Drive API 中管理审批。

用户可以在 Google 云端硬盘中通过正式审批流程发送文档。您可以通过此流程完成合同审核或正式文档发布前的审批。审批会跟踪审核状态（例如“进行中”“已批准”或“已拒绝”）以及所涉及的审核者。审批是验证内容和记录审核者的绝佳方式。

您可以在云端硬盘中创建和管理内容审批。 Google Drive API 提供了 approvals 资源，用于处理文件审批。approvals 资源的方法适用于云端硬盘、Google 文档和其他 Google Workspace 编辑器中的项。审核者可以直接批准、拒绝文档或提供反馈。

准备工作

您的文件应包含 canStartApproval 功能。如需检查文件功能，请使用 fileId 路径参数对 files 资源调用 get 方法，并在 fields 参数中使用 canStartApproval 功能字段。如需了解详情，请参阅了解文件功能。

在以下情况下，布尔值 canStartApproval 功能为 false：
- 管理员设置限制了对该功能的访问权限。
- 您的 Google Workspace 版本不符合条件。
- 文件归您网域外的用户所有。
- 用户缺少对文件的 role=writer 权限。
请务必手动与审核者共享目标文件。云端硬盘不会自动执行此操作。如果审核者没有文件访问权限，审批请求会成功，但他们不会收到通知，也无法查看文件。

概念

以下主要概念构成了审批的基础。

审批状态

当您请求文档审批时，审批流程会确保每位审核者都批准相同版本的内容。如果文件在审核者批准请求后且在请求完成之前被修改，则审核者的批准会被重置，审核者必须批准新版本。如果内容在最终批准后被修改，文档上会显示一个横幅，指明当前版本与已批准的版本不同。

approvals 资源包含一个 Status 对象，其中详细说明了请求资源时审批的状态。它还包含 ReviewerResponse对象，其中详细说明了特定审核者对审批做出的响应。每位审核者的响应都由 Response对象表示。

审批流程中的每个操作都会生成电子邮件通知，这些通知会发送给发起者（请求审批的用户）和所有审核者。它还会添加到审批活动日志中。

所有审核者都必须批准审批。任何拒绝审批的审核者都会将完成状态设置为 DECLINED。

审批完成后（状态为 APPROVED、CANCELLED 或 DECLINED），它会保持完成状态，发起者或审核者无法与之互动。只要没有状态为 IN_PROGRESS 的文件审批，您就可以向已完成的审批添加评论。

审批的生命周期

审批在其生命周期内会经历多种状态。图 1 显示了审批生命周期的高级步骤：

开始审批 。调用 start 以开始审批请求。然后，status 会设置为 IN_PROGRESS。
审批待处理 。在审批待处理期间（status 设置为 IN_PROGRESS），发起者和审核者都可以与之互动。他们可以添加 comment，发起者可以 reassign 审核者，一位或多位审核者可以 approve 该请求。
审批处于完成状态 。当所有审核者都批准请求、发起者选择 cancel 请求，或者任何审核者选择 decline 请求时，审批会进入完成状态（status 设置为 APPROVED、CANCELLED 或 DECLINED）。

使用 fields 参数

如果您想指定要在响应中返回的字段，可以使用 approvals 资源的任何方法设置 fields system parameter 。如果您省略 fields 参数，服务器会返回特定于该方法的默认字段集。如需返回不同的字段，请参阅返回特定字段。

开始和管理审批

您可以使用 approvals 资源通过 Drive API 开始和管理审批。这些方法适用于任何允许写入文件元数据的现有 OAuth 2.0 Drive API 范围。如需了解详情，请参阅选择 Google Drive API 范围。

开始审批

如需对文件开始新的审批，请对 approvals 资源使用 start 方法，并添加 fileId 路径参数。

请求正文包含一个必需的 reviewerEmails 字段，该字段是一个字符串数组，其中包含分配给审核文件的审核者的电子邮件地址。每个审核者的电子邮件地址都必须与 Google 账号相关联，否则请求会失败。此外，还提供了三个可选字段：

dueTime：审批的截止时间，采用 RFC 3339 格式。
lockFile：一个布尔值，指示是否在开始审批时锁定文件。这会阻止用户在审批过程中修改文件。任何拥有 role=writer 权限的用户都可以移除此锁定。
message：发送给审核者的自定义消息。

响应正文包含一个 approvals 资源实例，其中包含 initiator 字段，该字段是请求审批的用户。审批 Status 设置为 IN_PROGRESS。

如果存在 Status 为 IN_PROGRESS 的现有审批，start 方法会失败。只有在文件上没有现有审批，或者现有审批处于完成状态（状态为 APPROVED、CANCELLED 或 DECLINED）时，您才能开始审批。

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals:start' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "reviewerEmails": [
     "reviewer1@example.com",
     "reviewer2@example.com"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval."
 }'

替换以下内容：

FILE_ID：审批所针对的文件的 ID。
ACCESS_TOKEN：应用的 OAuth 2.0 令牌。

对审批发表评论

如需对审批发表评论，请对 approvals 资源使用 comment 方法，并添加 fileId 和 approvalId 路径参数。

请求正文包含一个必需的 message 字段，该字段是一个字符串，其中包含您想添加到审批中的评论。

响应正文包含一个 approvals 资源实例。该消息会作为通知发送给审批发起者和审核者，并且还会包含在审批活动日志中。

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:comment' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The required comment on the approval."
 }'

替换以下内容：

FILE_ID：审批所针对的文件的 ID。
APPROVAL_ID：审批的 ID。
ACCESS_TOKEN：应用的 OAuth 2.0 令牌。

重新分配审批的审核者

如需重新分配审批的审核者，请对 approvals 资源使用 reassign 方法，并添加 fileId 和 approvalId 路径参数。

借助 reassign 方法，审批发起者（或拥有 role=writer 权限的用户）可以在 ReviewerResponse 对象的 approvals 资源中添加或替换审核者。拥有 role=reader 权限的用户只能重新分配分配给自己的审批。这样，用户就可以将请求重新分配给更有能力的审核者。

只有在 Status为IN_PROGRESS且要重新分配的审核者的 response 字段设置为NO_RESPONSE时，才能重新分配审核者。

请注意，您无法移除审批的审核者。如果您需要移除审核者，必须取消审批并开始新的审批。

请求正文包含可选的 addReviewers 和 replaceReviewers 字段。每个字段都有一个 AddReviewer 和 ReplaceReviewer 的重复对象，每个对象都包含一个要添加的审核者或一对要替换的审核者。您还可以添加可选的 message 字段，其中包含您想发送给新审核者的评论。

响应正文包含一个 approvals 资源实例。该消息会作为通知发送给新审核者，并且还会包含在审批活动日志中。

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:reassign' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "addReviewers": [
    {
        "addedReviewerEmail": "new_reviewer@example.com"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "replacement_reviewer@example.com",
        "removedReviewerEmail": "old_reviewer@example.com"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

替换以下内容：

FILE_ID：审批所针对的文件的 ID。
APPROVAL_ID：审批的 ID。
ACCESS_TOKEN：应用的 OAuth 2.0 令牌。

取消审批

如需取消审批，请对 approvals 资源使用 cancel 方法，并添加 fileId 和 approvalId 路径参数。

只有在审批 Status为IN_PROGRESS时，审批发起者（或拥有 the role=writer权限的用户）才能调用cancel方法。

请求正文包含一个可选的 message 字段，该字段是一个字符串，其中包含随审批取消一起发送的消息。

响应正文包含一个 approvals 资源实例。该消息会作为通知发送，并且还会包含在审批活动日志中。审批 Status 设置为 CANCELLED，并且处于完成状态。

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:cancel' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for cancelling this approval request."
 }'

替换以下内容：

FILE_ID：审批所针对的文件的 ID。
APPROVAL_ID：审批的 ID。
ACCESS_TOKEN：应用的 OAuth 2.0 令牌。

拒绝审批

如需拒绝审批，请对 approvals 资源使用 decline 方法，并添加 fileId 和 approvalId 路径参数。

只有在审批 Status 为 IN_PROGRESS 时，才能调用 decline 方法。

请求正文包含一个可选的 message 字段，该字段是一个字符串，其中包含随审批拒绝一起发送的消息。

响应正文包含一个 approvals 资源实例。该消息会作为通知发送，并且还会包含在审批活动日志中。请求用户的 ReviewerResponse 对象的 response 字段设置为 DECLINED。此外，审批 Status 设置为 DECLINED，并且处于完成状态。

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:decline' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for declining this approval request."
 }'

替换以下内容：

FILE_ID：审批所针对的文件的 ID。
APPROVAL_ID：审批的 ID。
ACCESS_TOKEN：应用的 OAuth 2.0 令牌。

批准审批

如需批准审批，请对 approvals 资源使用 approve 方法，并添加 fileId 和 approvalId 路径参数。

只有在审批 Status 为 IN_PROGRESS 时，才能调用 approve 方法。

请求正文包含一个可选的 message 字段，该字段是一个字符串，其中包含随审批一起发送的消息。

响应正文包含一个 approvals 资源实例。该消息会作为通知发送，并且还会包含在审批活动日志中。请求用户的 ReviewerResponse 对象的 response 字段设置为 APPROVED。此外，如果这是最后一个必需的审核者响应，审批 Status 会设置为 APPROVED，并且处于完成状态。

cURL

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:approve' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for approving this approval request."
 }'

替换以下内容：

FILE_ID：审批所针对的文件的 ID。
APPROVAL_ID：审批的 ID。
ACCESS_TOKEN：应用的 OAuth 2.0 令牌。

查找现有审批

您还可以使用 approvals 资源通过 Drive API 获取和列出审批的状态。

如需查看文件的审批，您必须拥有读取文件元数据的权限。如需了解详情，请参阅角色和权限。

获取审批

如需获取文件的审批，请使用 fileId 和 approvalId 路径参数对 approvals 资源使用 get 方法。如果您不知道审批 ID，可以使用 list approvals 方法列出审批。list

响应正文包含一个 approvals 资源实例。

cURL

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

替换以下内容：

FILE_ID：审批所针对的文件的 ID。
APPROVAL_ID：审批的 ID。
ACCESS_TOKEN：应用的 OAuth 2.0 令牌。

列出审批

如需列出文件的审批，请对approvals资源调用 list方法并添加fileId路径参数。

响应正文包含文件上的审批列表。items 字段包含有关每个审批的信息，以 approvals 资源的形式呈现。

您还可以传递以下查询参数，以自定义审批的分页或过滤审批：

pageSize：每页返回的审批数量上限。如果您未设置 pageSize，服务器最多会返回 100 个审批。
pageToken：从之前的列表调用收到的页面令牌。此令牌用于检索后续页面。它应设置为上一个响应中的 nextPageToken 值。

cURL

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

替换以下内容：

FILE_ID：审批所针对的文件的 ID。
ACCESS_TOKEN：应用的 OAuth 2.0 令牌。

管理审批 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

概念

审批状态

审批的生命周期

使用 fields 参数

开始和管理审批

开始审批

cURL

对审批发表评论

cURL

重新分配审批的审核者

cURL

取消审批

cURL

拒绝审批

cURL

批准审批

cURL

查找现有审批

获取审批

cURL

列出审批

cURL

相关主题

管理审批