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

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ý các 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ề việc xem xét hợp đồng hoặc một tài liệu chính thức trước khi công bố. Quy trình phê duyệt theo dõi trạng thái của cả quy trình 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 xem xét có liên quan. Phê duyệt là một cách hiệu quả để xác thực nội dung và lưu giữ hồ sơ của 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 của 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 chứa khả năng canStartApproval . Để kiểm tra các chức 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 chức 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.

Khả 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 này 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 không có quyền role=writer đối với tệp.
Hãy nhớ 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 làm 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 quy trình 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ì các lượt 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 lần cuối, 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 đã được phê duyệt.

Tài nguyên approvals bao gồm một đối tượng Status nêu chi tiết trạng thái phê duyệt khi tài nguyên được yêu cầu. Nó cũng bao gồm đối tượng ReviewerResponse nêu chi tiết các phản hồi đối với một yêu cầu phê duyệt do người đánh giá cụ thể thực hiện. Mỗi câu trả lời của 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 sẽ tạo ra thông báo qua email được gửi cho 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á. Yêu cầu 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á đều 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 phê duyệt đều đặt trạng thái hoàn tất thành DECLINED.

Sau khi hoàn tất quy trình phê duyệt (trạng thái là APPROVED, CANCELLED hoặc DECLINED), quy trình này sẽ vẫn ở trạng thái hoàn tất và người khởi tạo hoặc người đánh giá không thể tương tác với quy trình đó. Bạn có thể thêm bình luận vào một 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 ở trạng thái IN_PROGRESS trên tệp.

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

Yêu cầu phê duyệt sẽ 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 của vòng đời phê duyệt:

Bắt đầu quy trình phê duyệt. Gọi start để bắt đầu yêu cầu phê duyệt. Sau đó, status được đặt thành IN_PROGRESS.
Đang chờ phê duyệt. 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 tạo và người xem xét đều có thể tương tác với yêu cầu đó. Họ có thể thêm comment, người khởi tạo 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 đã hoàn tất. Yêu cầu phê duyệt sẽ 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 tạo 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 tham số hệ thống fields 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 các 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 phần Trả về các trường cụ thể.

Bắt đầu và quản lý quy trình phê duyệt

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

Bắt đầu phê duyệt

Để bắt đầu một quy trình 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 gồm các chuỗi chứa địa chỉ email của những người được giao 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, bạn có thể chọn điền vào 3 trường sau:

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 quy trình phê duyệt. Thao tác này sẽ 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 gửi cho người đánh giá.

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

Nếu có yêu cầu phê duyệt hiện tại với 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 quy trình phê duyệt nếu không có quy trình phê duyệt nào đang diễn ra trên tệp hoặc nếu quy trình phê duyệt hiện có đã 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ã nhận dạng của tệp mà yêu cầu phê duyệt liên quan đến.
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

Để bình luận về một 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 các 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 bình luận 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 phiên bản của tài nguyên approvals. Thông báo này sẽ được gửi đến người khởi tạo và người đánh giá yêu cầu phê duyệt, đồ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ã nhận dạng của tệp mà yêu cầu phê duyệt liên quan đến.
APPROVAL_ID: Mã nhận dạng của lượt 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á khi phê duyệt

Để chỉ định lại người đánh giá cho một 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 các tham số đường dẫn fileId và approvalId.

Phương thức reassign cho phép người khởi tạo quy trình 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 một yêu cầu phê duyệt được chỉ định cho chính họ. Việc này cho phép người dùng chỉ định lại yêu cầu cho người khác có khả năng xem xét tốt 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á trong quy trình phê duyệt. Nếu cần xoá một 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 đều có một đối tượng lặp lại cho AddReviewer và ReplaceReviewer. Mỗi đối tượng này 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 bình luận mà bạn muốn gửi cho người đánh giá mới.

Nội dung phản hồi chứa một phiên bản của tài nguyên approvals. Thông báo sẽ được gửi đến người đánh giá mớ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.

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ã nhận dạng của tệp mà yêu cầu phê duyệt liên quan đến.
APPROVAL_ID: Mã nhận dạng của lượt 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 phương thức cancel trên tài nguyên approvals và thêm các tham số đường dẫn fileId và approvalId.

Chỉ người khởi tạo quy trình phê duyệt (hoặc người dùng có quyền role=writer) mới có thể gọi phương thức cancel trong khi quy trình phê duyệt Status đang ở trạng thái IN_PROGRESS.

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

Nội dung phản hồi chứa một phiên bản của tài nguyên approvals. Thông báo sẽ đượ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. Yêu cầu phê duyệt Status đượ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ã nhận dạng của tệp mà yêu cầu phê duyệt liên quan đến.
APPROVAL_ID: Mã nhận dạng của lượt 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 các tham số đường dẫn fileId và approvalId.

Bạn chỉ có thể gọi phương thức decline khi trạng thái phê duyệt 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. Đây là một chuỗi chứa thông báo đi kèm với việc từ chối phê duyệt.

Nội dung phản hồi chứa một phiên bản của tài nguyên approvals. Thông báo sẽ đượ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, trạng thái phê duyệt Status đượ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ã nhận dạng của tệp mà yêu cầu phê duyệt liên quan đến.
APPROVAL_ID: Mã nhận dạng của lượt 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 mộ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 các tham số đường dẫn fileId và approvalId.

Bạn chỉ có thể gọi phương thức approve khi trạng thái phê duyệt 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. Đây 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 phiên bản của tài nguyên approvals. Thông báo sẽ đượ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 mà người đánh giá bắt buộc phải đưa ra, thì trạng thái phê duyệt Status 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ã nhận dạng của tệp mà yêu cầu phê duyệt liên quan đến.
APPROVAL_ID: Mã nhận dạng của lượt phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Tìm 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 để nhận và liệt kê trạng thái phê duyệt bằng API Drive.

Để xem thông tin 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 phần Vai trò và quyền.

Yêu cầu phê duyệt

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

Nội dung phản hồi chứa một phiên bản 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ã nhận dạng của tệp mà yêu cầu phê duyệt liên quan đến.
APPROVAL_ID: Mã nhận dạng của lượt phê duyệt.
ACCESS_TOKEN: Mã thông báo OAuth 2.0 của ứng dụng.

Liệt kê các lượt phê duyệt

Để liệt kê các lượt 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 lượt phê duyệt trên tệp. Trường items chứa thông tin về từng lượt phê duyệt dưới dạng tài nguyên approvals.

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

pageSize: Số lượng 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 lượt phê duyệt.
pageToken: Mã thông báo trang, nhận được từ mộ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 giá trị này thành giá trị của nextPageToken trong mộ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ã nhận dạng của tệp mà yêu cầu phê duyệt liên quan đến.
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 một yêu cầu phê duyệt

Sử dụng tham số fields

Bắt đầu và quản lý quy trình phê duyệt

Bắt đầ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á khi 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

Tìm các yêu cầu phê duyệt hiện có

Yêu cầu phê duyệt

curl

Liệt kê các lượt phê duyệt

curl

Chủ đề có liên quan

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