Trang này mô tả các sự kiện trên Google Drive mà ứng dụng của bạn có thể đăng ký nhận thông báo bằng Google Workspace Events API. Sau khi quyết định loại sự kiện bạn cần, hãy tạo một gói thuê bao để bắt đầu nhận sự kiện từ Drive.
Để tìm hiểu thêm về cách phát triển ứng dụng cho Drive, hãy xem bài viết Tổng quan về Google Drive API.
Các sự kiện được hỗ trợ trên Drive
Gói thuê bao Google Workspace cho phép bạn nhận các sự kiện về những loại thay đổi sau đây trong Drive:
Đề xuất cấp quyền truy cập được tạo hoặc giải quyết trên một tệp.
Một nhận xét được tạo, chỉnh sửa, giải quyết, mở lại hoặc xoá trên một tệp hoặc một tệp trong bộ nhớ dùng chung.
Tệp là:
- Được thêm vào một thư mục hoặc bộ nhớ dùng chung.
- Đã di chuyển đến một thư mục hoặc bộ nhớ dùng chung.
- Bạn tải bản sửa đổi mới hoặc đã chỉnh sửa lên.
- Đã chuyển vào thùng rác hoặc xoá khỏi thùng rác.
- Đổi tên (tiêu đề của tệp hoặc thư mục bị thay đổi).
Một phản hồi được tạo, chỉnh sửa hoặc xoá trên một chuỗi bình luận trong một tệp hoặc một tệp trong bộ nhớ dùng chung.
Tài nguyên mà bạn có thể theo dõi sự kiện
Để nhận sự kiện, bạn chỉ định một tài nguyên trên Drive để theo dõi. Tài nguyên này được gọi là tài nguyên đích của gói thuê bao.
Google Workspace Events API hỗ trợ các tài nguyên mục tiêu sau đây cho Drive:
| Tài nguyên mục tiêu | Định dạng | Các điểm hạn chế (nếu có) |
|---|---|---|
| Tệp |
//drive.googleapis.com/files/FILE
trong đó FILE là mã nhận dạng trong
tên tài nguyên của tài nguyên |
Người dùng uỷ quyền cho gói thuê bao phải có quyền đối với tệp trong gói thuê bao so với sự kiện đăng ký. |
| Bộ nhớ dùng chung |
//drive.googleapis.com/drives/DRIVE
trong đó DRIVE là mã nhận dạng trong tên tài nguyên của tài nguyên |
Dịch vụ đăng ký chỉ nhận các sự kiện cho những mục trong ổ đĩa dùng chung mà người dùng là thành viên thông qua Tài khoản Google Workspace hoặc Tài khoản Google của họ. |
Các loại sự kiện để tạo gói thuê bao
Khi tạo một lượt đăng ký nhận thông báo về tài nguyên trên Drive, bạn sẽ sử dụng trường eventTypes[] để chỉ định những loại sự kiện mà bạn muốn nhận. Các loại sự kiện được định dạng theo quy cách CloudEvents, chẳng hạn như google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.
Ví dụ: để nhận sự kiện về việc tạo một tệp trong một thư mục hoặc ổ đĩa dùng chung, bạn chỉ định tệp đó làm tài nguyên đích và loại sự kiện là google.workspace.drive.file.v3.created. Để nhận các sự kiện về đề xuất cấp quyền truy cập được tạo trên một tệp, bạn chỉ định đề xuất cấp quyền truy cập làm tài nguyên đích và loại sự kiện là google.workspace.drive.accessproposal.v3.created. Để tìm hiểu thêm về cách hoạt động của sự kiện, hãy xem Cấu trúc của sự kiện Google Workspace.
Bảng sau đây cho biết những loại sự kiện được hỗ trợ cho việc đăng ký nhận thông báo về các tài nguyên trên Drive:
| Loại sự kiện | Định dạng | Dữ liệu tài nguyên | ||
|---|---|---|---|---|
| Đăng ký nhận thông báo về tệp và bộ nhớ dùng chung | ||||
| Đề xuất cấp quyền truy cập được tạo trên một tệp. |
|
|
||
| Đề xuất cấp quyền truy cập được giải quyết trên một tệp. |
|
|
||
| Một bình luận được tạo trên một tệp hoặc một tệp trong bộ nhớ dùng chung. |
|
|
||
| Một nhận xét được chỉnh sửa trên một tệp hoặc một tệp trong bộ nhớ dùng chung. |
|
|
||
| Một nhận xét được giải quyết trên một tệp hoặc một tệp trong bộ nhớ dùng chung. |
|
|
||
| Một nhận xét được mở lại trên một tệp hoặc một tệp trong bộ nhớ dùng chung. |
|
|
||
| Một bình luận bị xoá trên một tệp hoặc một tệp trong bộ nhớ dùng chung. |
|
|
||
| Một tệp được thêm vào thư mục hoặc bộ nhớ dùng chung. |
|
|
||
| Một tệp được di chuyển đến một thư mục hoặc bộ nhớ dùng chung. |
|
|
||
| Một tệp được chỉnh sửa hoặc một bản sửa đổi mới được tải lên. |
|
|
||
| Một tệp bị xoá. |
|
|
||
| Một tệp bị chuyển vào thùng rác. |
|
|
||
| Một tệp bị xoá khỏi thùng rác. |
|
|
||
| Một tệp được đổi tên. |
|
|
||
| Một câu trả lời được tạo trong chuỗi bình luận của một tệp hoặc một tệp trong bộ nhớ dùng chung. |
|
|
||
| Một câu trả lời được chỉnh sửa trong chuỗi bình luận của một tệp hoặc một tệp trong bộ nhớ dùng chung. |
|
|
||
| Một câu trả lời bị xoá trong chuỗi bình luận của một tệp hoặc một tệp trong bộ nhớ dùng chung. |
|
|
||
Dữ liệu sự kiện
Phần này mô tả dữ liệu sự kiện và các tải trọng mẫu cho các sự kiện trong Drive.
Khi gói thuê bao Google Workspace của bạn nhận được một sự kiện từ Drive, trường data sẽ chứa tải trọng của sự kiện. Tải trọng này có thông tin về tài nguyên Google Workspace đã thay đổi. Ví dụ: nếu bạn đã đăng ký nhận sự kiện về tệp, thì tải trọng cho các sự kiện này sẽ chứa thông tin về tài nguyên files đã thay đổi.
Dữ liệu tài nguyên trong tải trọng sự kiện
Khi tạo một gói thuê bao, bạn có thể chỉ định xem bạn muốn tải trọng bao gồm thông tin chi tiết về tài nguyên hay chỉ tên của tài nguyên. Ví dụ: nếu muốn nhận các sự kiện về tệp trên Drive, bạn có thể chỉ định những trường của tài nguyên files mà bạn muốn nhận trong tải trọng sự kiện.
Bảng sau đây cung cấp ví dụ về tải trọng JSON cho một gói thuê bao đối với tài nguyên Drive. Mã nhận dạng tệp chứa chữ cái, số và một số ký tự đặc biệt có cấu trúc là files/^[01][0-9a-zA-Z_-]+$/. Ví dụ: files/1aaabbbAAABBB111222-_. Đối với mỗi sự kiện mà gói thuê bao nhận được, tải trọng sẽ xuất hiện trong trường data của sự kiện:
| Ví dụ | Loại sự kiện | Tải trọng JSON |
|---|---|---|
Người dùng tạo đề xuất cấp quyền truy cập cho một tệp. |
|
Bao gồm dữ liệu tài nguyên
{
"accessProposal": [
{
"file_id": "FILE_ID",
"proposalId": "PROPOSAL_ID",
"recipientEmailAddress": "alex@altostrat.com",
"requesterEmailAddress": "kai@cymbalgroup.com",
"requestMessage": "grant me access to this file",
"rolesAndViews": [
{
"role": "writer",
"view": "published"
}
]
}
]
}
Không bao gồm dữ liệu tài nguyên
{
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
|
Người dùng giải quyết đề xuất cấp quyền truy cập đối với một tệp. |
|
Bao gồm dữ liệu tài nguyên
{
"accessProposal": [
{
"file_id": "FILE_ID",
"proposalId": "PROPOSAL_ID",
"recipientEmailAddress": "alex@altostrat.com",
"requesterEmailAddress": "kai@cymbalgroup.com",
"requestMessage": "resolve access to this file",
"rolesAndViews": [
{
"role": "writer",
"view": "published"
}
]
}
]
}
Không bao gồm dữ liệu tài nguyên
{
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
|
Một người dùng tạo nhận xét trên tệp. |
|
Bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
Không bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
Người dùng chỉnh sửa một bình luận trên tệp. |
|
Bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
Không bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
Người dùng giải quyết một bình luận trên tệp. |
|
Bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
Không bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
Người dùng mở lại một bình luận trên tệp. |
|
Bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
Không bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
Người dùng xoá một bình luận trên tệp. |
|
Bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
Không bao gồm dữ liệu tài nguyên
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
Người dùng thêm tệp vào một thư mục hoặc bộ nhớ dùng chung. |
|
Bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
Không bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID"
}
}
|
Người dùng di chuyển một tệp đến một thư mục hoặc bộ nhớ dùng chung. |
|
Bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
Không bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID"
}
}
|
Người dùng chỉnh sửa tệp hoặc một phiên bản mới được tải lên. |
|
Bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
Không bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID"
}
}
|
Người dùng xoá một tệp. |
|
Bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
Không bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID"
}
}
|
Người dùng chuyển một tệp vào thùng rác. |
|
Bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
Không bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID"
}
}
|
Người dùng khôi phục tệp trong thùng rác. |
|
Bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
Không bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID"
}
}
|
Người dùng đổi tên tệp hoặc thư mục. |
|
Bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
Không bao gồm dữ liệu tài nguyên
{
"file": {
"id": "FILE_ID"
}
}
|
Người dùng tạo một câu trả lời cho bình luận trong một chuỗi bình luận. |
|
Bao gồm dữ liệu tài nguyên
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
Không bao gồm dữ liệu tài nguyên
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
Một người dùng chỉnh sửa câu trả lời cho bình luận trong một chuỗi bình luận. |
|
Bao gồm dữ liệu tài nguyên
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
Không bao gồm dữ liệu tài nguyên
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
Một người dùng xoá câu trả lời cho bình luận trong một chuỗi bình luận. |
|
Bao gồm dữ liệu tài nguyên
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
Không bao gồm dữ liệu tài nguyên
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
Các điểm hạn chế
- Khi trường boolean
includeDescendantstrongDriveOptionslàtrue, các lượt đăng ký trên Drive đối với bộ nhớ dùng chung và thư mục luôn gửi một sự kiện, ngay cả khi tệp kích hoạt sự kiện được lồng nhiều lớp bên dưới thư mục dùng cho lượt đăng ký trên Drive. - Mặc dù đã tạo một chế độ đăng ký trên một thư mục, nhưng bạn có thể không nhận được tất cả các sự kiện trong hệ thống phân cấp tệp vì người dùng hoặc ứng dụng có thể không được cấp quyền truy cập vào các sự kiện đó. Trong trường hợp này, gói thuê bao vẫn hoạt động nhưng bạn sẽ không nhận được bất kỳ sự kiện nào cho những tài nguyên mà bạn không có quyền truy cập.
- Bạn có thể đăng ký nhận thông báo về các sự kiện trên mọi tệp và thư mục, nhưng không thể đăng ký nhận thông báo về các sự kiện trên thư mục gốc của bộ nhớ dùng chung. Tính năng đăng ký chỉ được hỗ trợ cho các tệp và thư mục bên trong bộ nhớ dùng chung. Những thay đổi được thực hiện trực tiếp đối với thư mục gốc của bộ nhớ dùng chung sẽ không kích hoạt sự kiện.
- Người dùng uỷ quyền đăng ký phải có quyền đối với tệp tương ứng với các sự kiện mà họ đăng ký.
- Dịch vụ đăng ký chỉ nhận các sự kiện cho những tài nguyên mà người dùng có quyền truy cập thông qua tài khoản Google Workspace hoặc Tài khoản Google của họ.