Quản lý yêu cầu phê duyệt

Tài liệu này giải thích cách quản lý yêu cầu phê duyệt trong API Google Drive.

Người dùng có thể gửi tài liệu trong Google Drive thông qua một quy trình phê duyệt chính thức. Bạn có thể sử dụng quy trình này để yêu cầu phê duyệt về một bản xem xét hợp đồng hoặc một tài liệu chính thức trước khi công bố. Yêu cầu phê duyệt theo dõi trạng thái của cả bản xem xét (chẳng hạn như Đang tiến hành, Đã phê duyệt hoặc Bị từ chối) và những người đánh giá liên quan. Yêu cầu phê duyệt là một cách tuyệt vời để xác thực nội dung và lưu giữ hồ sơ về người đánh giá.

Bạn có thể tạo và quản lý yêu cầu phê duyệt nội dung trong Drive. API Google Drive cung cấp tài nguyên approvals để xử lý yêu cầu phê duyệt tệp. Các phương thức của tài nguyên approvals hoạt động trên các mục trong Drive, Google Tài liệu và các trình chỉnh sửa khác trên Google Workspace. Người đánh giá có thể phê duyệt, từ chối hoặc để lại ý kiến phản hồi về tài liệu ngay lập tức.

Trước khi bắt đầu

Tệp của bạn phải có tính năng canStartApproval . Để kiểm tra các tính năng của tệp, hãy gọi phương thức get trên tài nguyên files bằng tham số đường dẫn fileId và sử dụng trường tính năng canStartApproval trong tham số fields. Để biết thêm thông tin, hãy xem bài viết Tìm hiểu các tính năng của tệp.

Tính năng boolean canStartApproval là false khi:
- Chế độ cài đặt của quản trị viên hạn chế quyền truy cập vào tính năng này.
- Phiên bản Google Workspace của bạn không đủ điều kiện.
- Tệp thuộc quyền sở hữu của một người dùng bên ngoài miền của bạn.
- Người dùng thiếu quyền role=writer trên tệp.
Đảm bảo bạn chia sẻ tệp mục tiêu với người đánh giá theo cách thủ công. Drive không tự động thực hiện việc này. Nếu người đánh giá không có quyền truy cập vào tệp, thì yêu cầu phê duyệt sẽ thành công, nhưng họ sẽ không nhận được thông báo hoặc không thể xem tệp.

Khái niệm

Các khái niệm chính sau đây tạo thành nền tảng của yêu cầu phê duyệt.

Trạng thái phê duyệt

Khi bạn yêu cầu phê duyệt tài liệu, quy trình phê duyệt sẽ đảm bảo mọi người đánh giá đều phê duyệt cùng một phiên bản nội dung. Nếu tệp được chỉnh sửa sau khi người đánh giá phê duyệt yêu cầu và trước khi yêu cầu hoàn tất, thì yêu cầu phê duyệt của người đánh giá sẽ được đặt lại và người đánh giá phải phê duyệt phiên bản mới. Nếu nội dung được chỉnh sửa sau khi phê duyệt cuối cùng, thì một biểu ngữ sẽ xuất hiện trên tài liệu cho biết phiên bản hiện tại khác với phiên bản đã phê duyệt.

Tài nguyên approvals bao gồm đối tượng Status cung cấp thông tin chi tiết về trạng thái của yêu cầu phê duyệt khi tài nguyên được yêu cầu. Tài nguyên này cũng bao gồm đối tượng ReviewerResponse cung cấp thông tin chi tiết về các phản hồi đối với yêu cầu phê duyệt do những người đánh giá cụ thể thực hiện. Phản hồi của mỗi người đánh giá được biểu thị bằng đối tượng Response.

Mọi hành động trong quy trình phê duyệt đều tạo ra thông báo qua email được gửi đến người khởi xướng (người dùng yêu cầu phê duyệt) và tất cả người đánh giá. Thông báo này cũng được thêm vào nhật ký hoạt động phê duyệt.

Tất cả người đánh giá phải phê duyệt một yêu cầu phê duyệt. Bất kỳ người đánh giá nào từ chối yêu cầu phê duyệt đều đặt trạng thái hoàn tất thành DECLINED.

Sau khi hoàn tất yêu cầu phê duyệt (trạng thái là APPROVED, CANCELLED hoặc DECLINED), yêu cầu phê duyệt sẽ vẫn ở trạng thái hoàn tất và người khởi xướng hoặc người đánh giá không thể tương tác với yêu cầu đó. Bạn có thể thêm nhận xét vào yêu cầu phê duyệt đã hoàn tất miễn là không có yêu cầu phê duyệt nào đang tồn tại trên một tệp có trạng thái IN_PROGRESS.

Vòng đời của yêu cầu phê duyệt

Vòng đời của một yêu cầu phê duyệt. — **Hình 1.** Vòng đời của yêu cầu phê duyệt.

Yêu cầu phê duyệt trải qua một số trạng thái trong vòng đời của mình. Hình 1 cho thấy các bước cấp cao trong vòng đời của yêu cầu phê duyệt:

Bắt đầu yêu cầu phê duyệt. Gọi start để bắt đầu yêu cầu phê duyệt. Sau đó, status được đặt thành IN_PROGRESS.
Yêu cầu phê duyệt đang chờ xử lý. Trong khi yêu cầu phê duyệt đang chờ xử lý (status được đặt thành IN_PROGRESS), cả người khởi xướng và người đánh giá đều có thể tương tác với yêu cầu đó. Họ có thể thêm comment, người khởi xướng có thể reassign người đánh giá và một hoặc nhiều người đánh giá có thể approve yêu cầu.
Yêu cầu phê duyệt ở trạng thái hoàn tất. Yêu cầu phê duyệt chuyển sang trạng thái hoàn tất (status được đặt thành APPROVED, CANCELLED hoặc DECLINED) khi tất cả người đánh giá phê duyệt yêu cầu, người khởi xướng chọn cancel yêu cầu hoặc nếu bất kỳ người đánh giá nào chọn để decline yêu cầu.

Sử dụng tham số fields

Nếu muốn chỉ định các trường cần trả về trong phản hồi, bạn có thể đặt fields tham số hệ thống bằng bất kỳ phương thức nào của tài nguyên approvals. Nếu bạn bỏ qua tham số fields, máy chủ sẽ trả về một tập hợp trường mặc định dành riêng cho phương thức đó. Để trả về các trường khác, hãy xem bài viết Trả về các trường cụ thể.

Bắt đầu và quản lý yêu cầu phê duyệt

Bạn có thể sử dụng tài nguyên approvals để bắt đầu và quản lý yêu cầu phê duyệt bằng API Drive. Các phương thức này hoạt động với bất kỳ phạm vi API Drive OAuth 2.0 hiện có nào cho phép ghi siêu dữ liệu tệp. Để biết thêm thông tin, hãy xem bài viết Chọn phạm vi API Google Drive.

Bắt đầu yêu cầu phê duyệt

Để bắt đầu một yêu cầu phê duyệt mới trên một tệp, hãy sử dụng phương thức start trên tài nguyên approvals và thêm tham số đường dẫn fileId.

Nội dung yêu cầu bao gồm một trường reviewerEmails bắt buộc là một mảng chuỗi chứa địa chỉ email của những người đánh giá được chỉ định để xem xét tệp. Mỗi địa chỉ email của người đánh giá phải được liên kết với một Tài khoản Google, nếu không yêu cầu sẽ không thành công. Ngoài ra, có 3 trường không bắt buộc:

dueTime: Thời hạn phê duyệt ở định dạng RFC 3339.
lockFile: Giá trị boolean cho biết có khoá tệp hay không khi bắt đầu yêu cầu phê duyệt. Điều này ngăn người dùng sửa đổi tệp trong quá trình phê duyệt. Bất kỳ người dùng nào có quyền role=writer đều có thể xoá khoá này.
message: Thông báo tuỳ chỉnh được gửi đến người đánh giá.

Nội dung phản hồi chứa một thực thể của tài nguyên approvals và nó bao gồm trường initiator là người dùng đã yêu cầu phê duyệt. `Status` phê duyệt Status được đặt thành IN_PROGRESS.

Nếu có một yêu cầu phê duyệt hiện tại có Status là IN_PROGRESS, thì phương thức start sẽ không thành công. Bạn chỉ có thể bắt đầu yêu cầu phê duyệt nếu không có yêu cầu phê duyệt nào đang tồn tại trên tệp hoặc nếu yêu cầu phê duyệt hiện tại ở trạng thái hoàn tất (trạng thái là APPROVED, CANCELLED hoặc 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."
 }'

Thay thế nội dung sau:

FILE_ID: Mã của tệp có yêu cầu phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Nhận xét về yêu cầu phê duyệt

Để nhận xét về yêu cầu phê duyệt, hãy sử dụng phương thức comment trên tài nguyên approvals và thêm tham số đường dẫn fileId và approvalId.

Nội dung yêu cầu bao gồm một trường message bắt buộc là một chuỗi chứa nhận xét mà bạn muốn thêm vào yêu cầu phê duyệt.

Nội dung phản hồi chứa một thực thể của tài nguyên approvals. Thông báo được gửi đến người khởi xướng và người đánh giá yêu cầu phê duyệt dưới dạng thông báo, đồng thời cũng được đưa vào nhật ký hoạt động phê duyệt.

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."
 }'

Thay thế nội dung sau:

FILE_ID: Mã của tệp có yêu cầu phê duyệt.
APPROVAL_ID: Mã của yêu cầu phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Chỉ định lại người đánh giá trên yêu cầu phê duyệt

Để chỉ định lại người đánh giá trên yêu cầu phê duyệt, hãy sử dụng phương thức reassign trên tài nguyên approvals và thêm tham số đường dẫn fileId và approvalId.

Phương thức reassign cho phép người khởi xướng yêu cầu phê duyệt (hoặc người dùng có quyền role=writer ) thêm hoặc thay thế người đánh giá trong đối tượng ReviewerResponse của tài nguyên approvals. Người dùng có quyền role=reader chỉ có thể chỉ định lại yêu cầu phê duyệt được chỉ định cho chính họ. Điều này cho phép người dùng chỉ định lại yêu cầu cho người khác là người đánh giá có năng lực hơn.

Bạn chỉ có thể chỉ định lại người đánh giá khi Status là IN_PROGRESS và trường response cho người đánh giá được chỉ định lại được đặt thành NO_RESPONSE.

Xin lưu ý rằng bạn không thể xoá người đánh giá trên yêu cầu phê duyệt. Nếu cần xoá người đánh giá, bạn phải huỷ yêu cầu phê duyệt và bắt đầu một yêu cầu mới.

Nội dung yêu cầu bao gồm các trường addReviewers và replaceReviewers không bắt buộc. Mỗi trường có một đối tượng lặp lại cho AddReviewer và ReplaceReviewer, mỗi đối tượng chứa một người đánh giá duy nhất để thêm hoặc một cặp người đánh giá để thay thế. Bạn cũng có thể thêm trường message không bắt buộc chứa nhận xét mà bạn muốn gửi đến người đánh giá mới.

Nội dung phản hồi chứa một thực thể của tài nguyên approvals. Thông báo được gửi đến người đánh giá mới dưới dạng thông báo, đồng thời cũng được đưa vào nhật ký hoạt động phê duyệt.

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."
 }'

Thay thế nội dung sau:

FILE_ID: Mã của tệp có yêu cầu phê duyệt.
APPROVAL_ID: Mã của yêu cầu phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Huỷ phê duyệt

Để huỷ yêu cầu phê duyệt, hãy sử dụng cancel phương thức trên approvals tài nguyên và thêm tham số đường dẫn fileId và approvalId.

Phương thức cancel chỉ có thể được gọi bởi người khởi xướng yêu cầu phê duyệt (hoặc người dùng có quyền role=writer) khi Status là IN_PROGRESS.

Nội dung yêu cầu bao gồm một trường message không bắt buộc là một chuỗi chứa thông báo đi kèm với việc huỷ yêu cầu phê duyệt.

Nội dung phản hồi chứa một thực thể của tài nguyên approvals. Thông báo được gửi dưới dạng thông báo và cũng được đưa vào nhật ký hoạt động phê duyệt. Status phê duyệt được đặt thành CANCELLED và ở trạng thái hoàn tất.

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."
 }'

Thay thế nội dung sau:

FILE_ID: Mã của tệp có yêu cầu phê duyệt.
APPROVAL_ID: Mã của yêu cầu phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Từ chối phê duyệt

Để từ chối yêu cầu phê duyệt, hãy sử dụng phương thức decline trên tài nguyên approvals và thêm tham số đường dẫn fileId và approvalId.

Phương thức decline chỉ có thể được gọi khi Status phê duyệt là IN_PROGRESS.

Nội dung yêu cầu bao gồm một trường message không bắt buộc là một chuỗi chứa thông báo đi kèm với việc từ chối yêu cầu phê duyệt.

Nội dung phản hồi chứa một thực thể của tài nguyên approvals. Thông báo được gửi dưới dạng thông báo và cũng được đưa vào nhật ký hoạt động phê duyệt. Trường response của đối tượng ReviewerResponse của người dùng yêu cầu được đặt thành DECLINED. Ngoài ra, Status phê duyệt được đặt thành DECLINED và ở trạng thái hoàn tất.

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."
 }'

Thay thế nội dung sau:

FILE_ID: Mã của tệp có yêu cầu phê duyệt.
APPROVAL_ID: Mã của yêu cầu phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Phê duyệt yêu cầu phê duyệt

Để phê duyệt yêu cầu phê duyệt, hãy sử dụng phương thức approve trên tài nguyên approvals và thêm tham số đường dẫn fileId và approvalId.

Phương thức approve chỉ có thể được gọi khi Status phê duyệt là IN_PROGRESS.

Nội dung yêu cầu bao gồm một trường không bắt buộc message là một chuỗi chứa thông báo đi kèm với yêu cầu phê duyệt.

Nội dung phản hồi chứa một thực thể của tài nguyên approvals. Thông báo được gửi dưới dạng thông báo và cũng được đưa vào nhật ký hoạt động phê duyệt. Trường response của đối tượng ReviewerResponse của người dùng yêu cầu được đặt thành APPROVED. Ngoài ra, nếu đây là phản hồi cuối cùng bắt buộc của người đánh giá, thì Status phê duyệt sẽ được đặt thành APPROVED và ở trạng thái hoàn tất.

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."
 }'

Thay thế nội dung sau:

FILE_ID: Mã của tệp có yêu cầu phê duyệt.
APPROVAL_ID: Mã của yêu cầu phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Xác định vị trí của các yêu cầu phê duyệt hiện có

Bạn cũng có thể sử dụng tài nguyên approvals để lấy và liệt kê trạng thái của các yêu cầu phê duyệt bằng API Drive.

Để xem các yêu cầu phê duyệt trên một tệp, bạn phải có quyền đọc siêu dữ liệu của tệp đó. Để biết thêm thông tin, hãy xem bài viết Vai trò và quyền.

Lấy yêu cầu phê duyệt

Để lấy yêu cầu phê duyệt trên một tệp, hãy sử dụng get phương thức trên tài nguyên approvals bằng tham số đường dẫn fileId và approvalId path parameters. Nếu không biết mã yêu cầu phê duyệt, bạn có thể liệt kê các yêu cầu phê duyệt bằng phương thức list.

Nội dung phản hồi chứa một thực thể của tài nguyên 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'

Thay thế nội dung sau:

FILE_ID: Mã của tệp có yêu cầu phê duyệt.
APPROVAL_ID: Mã của yêu cầu phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Liệt kê các yêu cầu phê duyệt

Để liệt kê các yêu cầu phê duyệt trên một tệp, hãy gọi phương thức list trên tài nguyên approvals và thêm tham số đường dẫn fileId.

Nội dung phản hồi bao gồm danh sách các yêu cầu phê duyệt trên tệp. Trường items bao gồm thông tin về từng yêu cầu phê duyệt ở dạng tài nguyên approvals.

Bạn cũng có thể truyền các tham số truy vấn sau để tuỳ chỉnh phân trang hoặc lọc các yêu cầu phê duyệt:

pageSize: Số lượng yêu cầu phê duyệt tối đa cần trả về trên mỗi trang. Nếu bạn không đặt pageSize, máy chủ sẽ trả về tối đa 100 yêu cầu phê duyệt.
pageToken: Mã thông báo trang nhận được từ lệnh gọi danh sách trước đó. Mã thông báo này được dùng để truy xuất trang tiếp theo. Bạn nên đặt mã thông báo này thành giá trị của nextPageToken từ phản hồi trước đó.

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'

Thay thế nội dung sau:

FILE_ID: Mã của tệp có yêu cầu phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Quản lý yêu cầu phê duyệt Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Trước khi bắt đầu

Khái niệm

Trạng thái phê duyệt

Vòng đời của yêu cầu phê duyệt

Sử dụng tham số fields

Bắt đầu và quản lý yêu cầu phê duyệt

Bắt đầu yêu cầu phê duyệt

curl

Nhận xét về yêu cầu phê duyệt

curl

Chỉ định lại người đánh giá trên yêu cầu phê duyệt

curl

Huỷ phê duyệt

curl

Từ chối phê duyệt

curl

Phê duyệt yêu cầu phê duyệt

curl

Xác định vị trí của các yêu cầu phê duyệt hiện có

Lấy yêu cầu phê duyệt

curl

Liệt kê các yêu cầu phê duyệt

curl

Chủ đề có liên quan

Quản lý yêu cầu phê duyệt