Mỗi tệp, thư mục và bộ nhớ dùng chung trên Google Drive đều có các tài nguyên permissions được liên kết. Mỗi tài nguyên xác định quyền cho một type cụ thể (user, group, domain, anyone) và role (owner, organizer, fileOrganizer, writer, commenter, reader). Ví dụ: một tệp có thể có quyền cấp cho một người dùng cụ thể (type=user) quyền truy cập chỉ đọc (role=reader), trong khi một quyền khác cấp cho các thành viên của một nhóm cụ thể (type=group) khả năng thêm nhận xét vào một tệp (role=commenter).
Để xem danh sách đầy đủ các vai trò và những thao tác được phép thực hiện đối với từng vai trò, hãy xem phần Vai trò và quyền.
Cách quyền được truyền
Các quyền được truyền từ thư mục mẹ xuống tất cả các mục con:
- Kế thừa theo mặc định: Tất cả tệp và thư mục con sẽ tự động kế thừa các quyền của thư mục mẹ.
- Không thể giảm quyền đối với các mục con: Bạn không thể xoá hoặc giảm quyền được thừa kế đối với một mục con. Bạn phải thực hiện thay đổi trên thư mục mẹ ban đầu hoặc thư mục đó phải sử dụng chế độ cài đặt quyền truy cập bị giới hạn.
- Có thể mở rộng trên các mục con: Một mục con có thể cấp một vai trò cho phép nhiều hơn, chẳng hạn như cấp quyền
role=writercho một tệp trong thư mục mà người dùng có quyềnrole=reader. - Được đánh giá lại khi di chuyển: Khi bạn di chuyển một mục đến một thư mục mẹ mới, hệ thống sẽ đánh giá lại và áp dụng các quyền của thư mục mẹ mới cho mục đó và các mục con của mục đó.
Đường liên kết đến tệp và chế độ kiểm soát quyền truy cập
Khi bạn chia sẻ một tệp hoặc thư mục với một người dùng hoặc nhóm cụ thể, URL để truy cập vào mục đó sẽ không thay đổi và hệ thống sẽ không tạo một đường liên kết duy nhất cho mỗi người dùng.
Thay vào đó, mặt hàng có một đường liên kết duy nhất và cố định dựa trên fileId.
Drive kiểm soát quyền truy cập bằng cách đánh giá ACL của mục. Khi người dùng cố gắng mở một đường liên kết, Drive sẽ xác minh danh tính đã xác thực của họ dựa trên ACL. Nếu một quyền bị thu hồi hoặc hết hạn, thì người dùng sẽ bị xoá khỏi danh sách kiểm soát truy cập. Nếu người dùng cố gắng truy cập lại vào đường liên kết, Drive sẽ từ chối quyền truy cập.
Tìm hiểu các chức năng của tệp
Tài nguyên permissions xác định những người có quyền truy cập (ACL), nhưng không cho biết trực tiếp liệu người dùng hiện tại có thể thực hiện một hành động cụ thể trong giao diện người dùng của ứng dụng hay không.
Thay vào đó, tài nguyên files chứa một tập hợp các trường boolean capabilities (chẳng hạn như canComment, canShare hoặc canDelete) mà API Google Drive tính toán linh động dựa trên vai trò của người dùng và chế độ cài đặt của mục.
Lấy các chức năng của tệp
Khi hiển thị giao diện người dùng của ứng dụng, hãy kiểm tra files.capabilities thay vì phân tích cú pháp trực tiếp các quyền:
- Gọi phương thức
files.getbằngfields=capabilities. Để biết thêm thông tin, hãy xem phần Trả về các trường cụ thể. - Sử dụng các cờ boolean được trả về để bật hoặc tắt các thao tác tương ứng trong giao diện của bạn. Ví dụ: tắt tính năng bình luận nếu
canCommentlàfalse.
Các trường hợp chia sẻ tài nguyên trên Drive
Bảng sau đây cho biết các vai trò và điều kiện bắt buộc để chia sẻ tài nguyên trên Drive ở nhiều vị trí và loại mục:
| Thông tin vị trí | Mục | Vai trò bắt buộc | Các hạn chế về khoá |
|---|---|---|---|
| Drive của tôi | Tệp hoặc thư mục | owner hoặc writer |
Cần có owner nếu writersCanShare=false.Để đặt ngày hết hạn quyền truy cập có thời hạn vào thư mục, bạn cần có reader (xem phần Đặt ngày hết hạn). |
| Bộ nhớ dùng chung | Tệp | organizer, fileOrganizer hoặc writer |
writersCanShare luôn được coi là true. |
| Bộ nhớ dùng chung | Thư mục | organizer |
fileOrganizer cũng có thể chia sẻ nếu sharingFoldersRequiresOrganizerPermission là false. |
| Bộ nhớ dùng chung | Gói thành viên | organizer |
Chỉ áp dụng cho user hoặc group (không áp dụng cho miền). |
Quản lý quyền
Bảng sau đây tóm tắt các phương thức có trên tài nguyên permissions:
| Phương thức | Điểm cuối của API | Các tham số chính | Tài liệu tham khảo |
|---|---|---|---|
| Tạo | POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
role, type, emailAddress hoặc domain |
permissions.create |
| Nhận | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
fields |
permissions.get |
| List (Danh sách) | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
pageSize, supportsAllDrives, pageToken |
permissions.list |
| Cập nhật | PATCH https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
role, allowFileDiscovery |
permissions.update |
| Xoá | DELETE https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
supportsAllDrives |
permissions.delete |
Tạo quyền
Để chia sẻ một tệp, thư mục hoặc bộ nhớ dùng chung, hãy gọi phương thức create trên tài nguyên permissions bằng fileId.
Việc tạo một quyền sẽ thêm một mục ACL mới vào mục và trả về một permissionId được chỉ định.
Trong phần nội dung yêu cầu, hãy cung cấp các trường sau:
role: Cấp độ truy cập cần cấp (ví dụ:reader,commenterhoặcwriter). Để xem danh sách đầy đủ, hãy xem phần Vai trò và quyền.type: Phạm vi của bên được cấp (user,group,domainhoặcanyone).- Giá trị nhận dạng bên được cấp phép (bắt buộc dựa trên
type):emailAddress: Bắt buộc khitypelàuserhoặcgroup.domain: Bắt buộc khitypelàdomain.
Đoạn mã mẫu sau đây cho biết cách tạo một quyền. Phản hồi trả về một thực thể của tài nguyên permissions, bao gồm cả permissionId được chỉ định.
Yêu cầu
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "role": "commenter", "type": "user", "emailAddress": "alex@altostrat.com" }
Đáp
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}Chia sẻ với đối tượng mục tiêu
Đối tượng mục tiêu là các nhóm người (chẳng hạn như bộ phận hoặc nhóm) mà bạn có thể đề xuất cho người dùng để chia sẻ các mục của họ. Bạn có thể khuyến khích người dùng chia sẻ các mục với một nhóm đối tượng cụ thể hoặc hạn chế hơn thay vì toàn bộ tổ chức. Đối tượng mục tiêu có thể giúp bạn cải thiện tính bảo mật và quyền riêng tư của dữ liệu, đồng thời giúp người dùng dễ dàng chia sẻ dữ liệu một cách phù hợp.
Để chia sẻ với đối tượng mục tiêu, hãy đặt type=domain và domain thành <TARGET_AUDIENCE_ID>.audience.googledomains.com. Để biết thông tin chi tiết về cách xác định hoặc tạo đối tượng mục tiêu trong Bảng điều khiển dành cho quản trị viên của Google, hãy xem bài viết Giới thiệu về đối tượng mục tiêu.
Để xem cách người dùng tương tác với đối tượng mục tiêu, hãy xem phần Trải nghiệm người dùng khi chia sẻ đường liên kết.
Xin cấp quyền
Để lấy một quyền, hãy gọi phương thức get trên tài nguyên permissions bằng các tham số đường dẫn fileId và permissionId. Nếu bạn không biết mã nhận dạng quyền, trước tiên hãy liệt kê tất cả các quyền.
Liệt kê các quyền
Để liệt kê các quyền đối với một tệp, thư mục hoặc bộ nhớ dùng chung, hãy gọi phương thức list trên tài nguyên permissions bằng tham số đường dẫn fileId bắt buộc.
Bạn có thể thêm bất kỳ tham số truy vấn không bắt buộc nào sau đây để phân trang hoặc lọc phản hồi:
pageSize(không bắt buộc): Số lượng quyền tối đa cần trả về trên mỗi trang. Nếu không được đặt cho các tệp trong bộ nhớ dùng chung, thì tối đa 100 kết quả sẽ được trả về. Nếu không được đặt cho các tệp không nằm trong bộ nhớ dùng chung, thì toàn bộ danh sách sẽ được trả về.pageToken(không bắt buộc): Mã thông báo trang từ một lệnh gọi danh sách trước đó để truy xuất trang tiếp theo.supportsAllDrives(không bắt buộc): Ứng dụng yêu cầu có hỗ trợ cả phần "Ổ của tôi" và bộ nhớ dùng chung hay không.useDomainAdminAccess(không bắt buộc): Đặt thànhtrueđể đưa ra yêu cầu với tư cách là quản trị viên miền. Người yêu cầu sẽ được cấp quyền truy cập nếu tham sốfileIdđề cập đến một bộ nhớ dùng chung và người yêu cầu là quản trị viên của miền mà bộ nhớ dùng chung đó thuộc về. Để biết thêm thông tin, hãy xem bài viết Quản lý bộ nhớ dùng chung với tư cách quản trị viên miền.includePermissionsForView(không bắt buộc): Các quyền xem bổ sung cần đưa vào phản hồi. Chỉ hỗ trợpublished.fields(không bắt buộc): Các trường cụ thể cần trả về trong phản hồi. Theo mặc định,listchỉ trả vềid,type,kindvàrole. Để trả về các trường bổ sung (chẳng hạn nhưpermissionDetails), hãy chỉ định các trường đó bằng tham số này. Để biết thêm thông tin, hãy xem phần Trả về các trường cụ thể.
Xác định nguồn vai trò
Để thay đổi vai trò đối với một tệp hoặc thư mục, bạn phải biết nguồn gốc của vai trò đó. Đối với bộ nhớ dùng chung, nguồn của vai trò có thể dựa trên tư cách thành viên của bộ nhớ dùng chung, vai trò trên thư mục hoặc vai trò trên tệp.
Để xác định nguồn vai trò cho một bộ nhớ dùng chung hoặc các mục trong bộ nhớ dùng chung đó, hãy gọi phương thức get trên tài nguyên permissions bằng các tham số đường dẫn fileId và permissionId, đồng thời đặt tham số fields thành trường permissionDetails.
Để tìm permissionId, hãy sử dụng phương thức list trên tài nguyên permissions bằng tham số đường dẫn fileId. Để tìm nạp trường permissionDetails trong yêu cầu list, hãy đặt tham số fields thành permissions/permissionDetails.
Trường này liệt kê tất cả các quyền trực tiếp và quyền được kế thừa đối với tệp của người dùng, nhóm hoặc miền.
Mã mẫu sau đây cho thấy cách xác định nguồn vai trò. Phản hồi này trả về permissionDetails của tài nguyên permissions. Trường inheritedFrom cung cấp mã nhận dạng của mục mà quyền được kế thừa.
Yêu cầu
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true
Đáp
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}Cập nhật quyền
Để cập nhật quyền đối với một tệp hoặc thư mục, bạn có thể thay đổi vai trò được chỉ định. Để biết thêm thông tin về cách tìm nguồn vai trò, hãy xem bài viết Xác định nguồn vai trò.
Gọi phương thức
updatetrên tài nguyênpermissionsvới tham số đường dẫnfileIdđược đặt thành tệp, thư mục hoặc bộ nhớ dùng chung được liên kết và tham số đường dẫnpermissionIdđược đặt thành quyền cần thay đổi. Để tìmpermissionId, hãy sử dụng phương thứclisttrên tài nguyênpermissionsbằng tham số đường dẫnfileId.Trong yêu cầu, hãy xác định
rolemới.
Bạn có thể cấp quyền cho từng tệp hoặc thư mục trong bộ nhớ dùng chung ngay cả khi người dùng hoặc nhóm đó đã là thành viên. Ví dụ: Alex có role=commenter trong tư cách thành viên của họ đối với một bộ nhớ dùng chung. Tuy nhiên, ứng dụng của bạn có thể cấp quyền cho Alex role=writer đối với một tệp trong bộ nhớ dùng chung. Trong trường hợp này, vì vai trò mới có nhiều quyền hơn vai trò được cấp thông qua tư cách thành viên, nên quyền mới sẽ trở thành vai trò có hiệu lực đối với tệp hoặc thư mục.
Bạn có thể áp dụng các nội dung cập nhật thông qua ngữ nghĩa vá, tức là bạn có thể sửa đổi một phần tài nguyên. Bạn phải đặt rõ ràng các trường mà bạn dự định sửa đổi trong yêu cầu của mình. Mọi trường không có trong yêu cầu sẽ giữ lại giá trị hiện có. Để biết thêm thông tin, hãy xem phần Xử lý tài nguyên một phần.
Ngoài việc thay đổi vai trò, bạn cũng có thể sửa đổi khả năng hiển thị của một mục khi quyền type là domain hoặc anyone. Để giúp người dùng tìm thấy hoặc không tìm thấy một tệp được chia sẻ, hãy thêm trường boolean allowFileDiscovery vào yêu cầu vá. Khi bạn đặt giá trị này thành true, mặt hàng sẽ xuất hiện trong kết quả tìm kiếm cho đối tượng được chỉ định, ngay cả khi họ chưa được cung cấp đường liên kết trực tiếp. Bạn không cần xoá rồi tạo lại quyền để thay đổi chế độ cài đặt này.
Mã mẫu sau đây cho biết cách thay đổi quyền trên một tệp hoặc thư mục từ commenter thành writer. Phản hồi này trả về một thực thể của tài nguyên permissions.
Yêu cầu
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"role": "writer"
}Đáp
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}Cập nhật nhiều quyền bằng các yêu cầu hàng loạt
Chúng tôi không hỗ trợ việc sửa đổi quyền đồng thời trên cùng một tệp, thư mục hoặc bộ nhớ dùng chung. Giới hạn này áp dụng cho tất cả các thao tác sửa đổi (chẳng hạn như cập nhật hoặc xoá), bất kể bạn đang sửa đổi quyền cho cùng một người nhận hay nhiều người nhận, cũng như bất kể các yêu cầu đến từ một ứng dụng duy nhất hay nhiều người dùng.
Drive đánh giá và cập nhật quyền của một mục dưới dạng một ACL duy nhất. Các thao tác đồng thời gây ra tình trạng tương tranh, trong đó "lần ghi cuối cùng sẽ thắng", điều này có thể âm thầm ghi đè các thay đổi về quyền hoặc kích hoạt lỗi sharingRateLimitExceeded.
Để tránh xung đột, hãy thực thi các thay đổi về quyền trên cùng một mục theo trình tự hoặc sử dụng yêu cầu hàng loạt để sửa đổi nhiều quyền trong một yêu cầu.
Sau đây là ví dụ về cách thực hiện một lần sửa đổi hàng loạt quyền bằng thư viện ứng dụng.
Java
Python
Node.js
PHP
.NET
Xoá quyền
Để thu hồi quyền truy cập vào một tệp hoặc thư mục, hãy gọi phương thức delete trên tài nguyên permissions bằng các tham số đường dẫn fileId và permissionId.
Bạn không thể thu hồi trực tiếp các quyền được thừa kế trên các mục con. Thay vào đó, hãy cập nhật hoặc xoá quyền đối với thư mục mẹ (hoặc sử dụng chế độ cài đặt quyền truy cập bị giới hạn).
Xin lưu ý rằng việc xoá quyền truy cập của người dùng khỏi một mục mẹ chỉ thu hồi các quyền được kế thừa từ mục mẹ đó. Nếu người dùng cũng được cấp quyền trực tiếp đối với một mục con, thì quyền truy cập trực tiếp đó vẫn tồn tại. Để xác nhận rằng một quyền đã bị xoá, hãy gọi list bằng fileId.
Đặt ngày hết hạn
Để cấp quyền truy cập tạm thời vào một tệp hoặc thư mục, hãy đặt trường expirationTime (ngày giờ theo RFC 3339) khi gọi phương thức create hoặc update.
Thời gian hết hạn có các quy tắc hạn chế sau:
- Chỉ có thể đặt cho các quyền
uservàgroup(không phảidomainhoặcanyone). - Thời gian phải là thời gian trong tương lai, tối đa là một năm.
- Đối với thư mục, quyền truy cập tạm thời chỉ được hỗ trợ với vai trò
reader.
Chủ đề có liên quan
- Quản lý đề xuất cấp quyền truy cập đang chờ xử lý
- Quản lý thư mục có quyền truy cập bị giới hạn và mở rộng
- Chuyển quyền sở hữu tệp
- Bảo vệ nội dung tệp
- Truy cập vào tệp trên Drive được chia sẻ qua đường liên kết bằng khoá tài nguyên
- Vai trò và quyền