管理核准

本文說明如何透過 Google Drive API 管理核准。

使用者可以將 Google 雲端硬碟中的文件透過正式程序送交核准。無論是待核准的合約審查或正式文件，你都可以採用這個程序。核准會追蹤審查狀態 (例如「進行中」、「已核准」或「已拒絕」)，以及參與審查的人員。核准是驗證內容的絕佳方式，也能記錄審查人員。

您可以在雲端硬碟中建立及管理內容核准流程。Google Drive API 提供 approvals 資源，可處理檔案核准作業。approvals 資源的方法適用於 Google 雲端硬碟、Google 文件和其他 Google Workspace 編輯器中的項目。審查者可以直接核准或拒絕文件，也可以在文件中加入意見回饋。

事前準備

檔案應包含 canStartApproval 功能。如要檢查檔案功能，請使用 fileId 路徑參數，在 files 資源上呼叫 get 方法，並在 fields 參數中使用 canStartApproval 功能欄位。詳情請參閱「瞭解檔案功能」。

布林值 canStartApproval 功能會在下列情況下為 false：
- 管理員設定限制了這項功能的存取權。
- 您的 Google Workspace 版本不符合資格。
- 檔案擁有者是網域外部使用者。
- 使用者沒有檔案的 role=writer 權限。
請務必手動與審查人員共用目標檔案。 Google 雲端硬碟不會自動執行這項作業。如果審查者沒有檔案存取權，核准要求會成功送出，但對方不會收到通知，也無法查看檔案。

概念

以下是核准功能的重要概念。

核准狀態

要求核准文件時，核准程序會確保每位審查者核准的內容版本相同。如果審查者核准要求後，且要求完成前編輯了檔案，審查者的核准狀態就會重設，審查者必須核准新版本。如果內容在最終核准後經過編輯，文件上會顯示橫幅，指出目前版本與核准版本不同。

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 參數。如果省略 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 路徑參數。

核准發起人 (或具備 role=writer 權限的使用者) 可透過 reassign 方法，在 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

相關主題

管理核准