Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

管理“审批”功能

本文档介绍了如何在 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 对象表示。

当审批 Status 为 IN_PROGRESS 时，如果文件内容发生更改，审批的行为由 fileContentChangeBehavior 字段的 approvals 资源决定。您可以应用以下行为：

RESET_APPROVAL：审批流程会确保每位审批人都批准相同版本的内容。如果文件在审批人批准请求后且在请求完成之前经过修改，则审批人的批准会被重置（响应会重新设置为 NO_RESPONSE），并且审批人必须批准新版本。当审批的状态为 APPROVED 时，文件会被锁定，以防止进一步修改。在最终批准后对内容进行其他修改会导致文档上显示横幅，指明当前版本与已批准的版本不同。这是默认行为。
NO_APPROVAL_ACTION：在审批待处理期间，对文件内容的修改不会重置审批人的决定。此外，文件在最终批准后不会被锁定。审批人还可以在审批完成之前的任何时间将其自己的 APPROVED 决定重置为待处理状态（响应会重新设置为 NO_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 参数

如需检索审批详细信息，您必须显式指定所需的字段，并使用 fields system parameter ，以及 approvals 资源的任何方法。与其他资源不同，如果省略 fields 参数，approvals 资源的方法不会返回一组默认字段。如需了解详情，请参阅返回特定字段。

开始和管理审批

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

开始审批

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

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

dueTime：审批的截止时间，采用 RFC 3339 格式。
lockFile：一个布尔值，指示是否在开始审批时锁定文件。这会阻止用户在审批流程期间修改文件。任何具有 role=writer 权限的用户都可以移除此锁定。
message：发送给审批人的自定义消息。
fileContentChangeBehavior：文件内容发生更改时审批的行为。支持的值包括：
- RESET_APPROVAL：（默认）当审批进行期间内容发生更改时，将任何审批人响应 APPROVED 重置为 NO_RESPONSE。审批完成后，文件会被锁定，状态为 APPROVED。
- NO_APPROVAL_ACTION：当内容发生更改时，不会重置审批人响应，并且在审批完成后不会锁定文件。

响应正文包含一个 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.",
    "fileContentChangeBehavior": "RESET_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 获取和列出审批的状态。

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

获取审批

如需获取文件的审批，请对 approvals 资源使用 get方法，并添加 fileId 和 approvalId 路径参数。如果您不知道审批 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&fields=nextPageToken,items(approvalId,status)' \
  -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

相关主题

管理“审批”功能