Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

管理“审批”功能

本文档介绍了如何在 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 时发生更改时，审批的行为由 approvals 资源的 fileContentChangeBehavior 字段决定。可以应用以下行为：

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 参数

如果您想指定要在响应中返回的字段，可以使用 approvals 资源的任何方法设置 fields 系统参数。如果您省略 fields 参数，服务器会返回一组特定于相应方法的默认字段。如需返回其他字段，请参阅返回特定字段。

发起和管理审批

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 权限的用户）可以在 approvals 资源的 ReviewerResponse 对象中添加或替换审核者。拥有 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 路径形参。

只有审批发起者（或具有 role=writer 权限的用户）才能在审批 Status 为 IN_PROGRESS 时调用 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 资源实例。

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

相关主题

管理“审批”功能