本頁說明應用程式可使用 Google Workspace Events API 訂閱的 Google 雲端硬碟事件。決定需要哪些類型的事件後，請建立訂閱項目，開始接收雲端硬碟事件。
如要進一步瞭解如何開發雲端硬碟應用程式，請參閱「 Google Drive API 總覽」。
支援的雲端硬碟事件
訂閱 Google Workspace 後，您就能接收雲端硬碟中下列類型異動的事件：
可監控事件的資源
如要接收事件，請指定要監控的雲端硬碟資源，這類資源稱為訂閱的目標資源。
Google Workspace Events API 支援下列 Google 雲端硬碟目標資源：
| 目標資源 | 格式 | 限制 (如適用) |
|---|---|---|
| 檔案 |
//drive.googleapis.com/files/FILE
其中 FILE 是 Drive API |
授權訂閱的使用者必須具備訂閱項目中檔案的權限，才能訂閱事件。 |
| 共用雲端硬碟 |
//drive.googleapis.com/drives/DRIVE
其中 DRIVE 是 Drive API |
訂閱項目只會接收使用者透過 Google Workspace 帳戶或 Google 帳戶成為成員的共用雲端硬碟項目事件。 |
建立訂閱項目的事件類型
建立雲端硬碟資源的訂閱項目時，請使用 eventTypes[] 欄位指定要接收的事件類型。事件類型會根據 CloudEvents 規格格式化，例如 google.workspace.APPLICATION.RESOURCE.VERSION.ACTION。
舉例來說，如要接收資料夾或共用雲端硬碟中建立檔案的事件，請將檔案指定為目標資源，並將事件類型指定為 google.workspace.drive.file.v3.created。如要接收有關檔案存取提案建立的事件，請將存取提案指定為目標資源，並將事件類型指定為 google.workspace.drive.accessproposal.v3.created。如要進一步瞭解事件的運作方式，請參閱「Google Workspace 事件的結構」。
下表列出訂閱雲端硬碟資源時支援的事件類型：
| 事件類型 | 格式 | 資源資料 | ||
|---|---|---|---|---|
| 訂閱檔案 | ||||
| 檔案新增至資料夾或共用雲端硬碟。 |
|
|
||
| 檔案移至資料夾或共用雲端硬碟。 |
|
|
||
| 編輯檔案或上傳新修訂版本。 |
|
|
||
| 刪除檔案。 |
|
|
||
| 檔案已移至垃圾桶。 |
|
|
||
| 檔案從垃圾桶中移除。 |
|
|
||
| 在檔案上建立存取提案。 |
|
|
||
| 檔案的存取提案已解決。 |
|
|
||
| 共用雲端硬碟的訂閱項目 | ||||
| 檔案新增至資料夾或共用雲端硬碟。 |
|
|
||
| 檔案移至資料夾或共用雲端硬碟。 |
|
|
||
| 編輯檔案或上傳新修訂版本。 |
|
|
||
| 刪除檔案。 |
|
|
||
| 檔案已移至垃圾桶。 |
|
|
||
| 檔案從垃圾桶中移除。 |
|
|
||
| 在檔案上建立存取提案。 |
|
|
||
| 檔案的存取提案已解決。 |
|
|
||
事件資料
本節說明 Google 雲端硬碟中的事件資料和事件酬載範例。
當 Google Workspace 訂閱方案收到來自 Google 雲端硬碟的事件時，data 欄位會包含該事件的酬載。這個酬載包含變更的 Google Workspace 資源相關資訊。舉例來說，如果您已訂閱檔案事件，這些事件的酬載會包含變更的 file 資源相關資訊。
事件酬載中的資源資料
建立訂閱項目時，您可以指定要在酬載中加入資源詳細資料，還是只加入資源名稱。舉例來說，如果您想接收雲端硬碟檔案的相關事件，可以指定要在事件酬載中接收哪些 files 資源的欄位。
下表提供訂閱 Drive 資源的 JSON 酬載範例。檔案 ID 包含字母、數字和一些特殊字元，結構為 files/^[01][0-9a-zA-Z_-]+$/。例如：files/1aaabbbAAABBB111222-_。訂閱項目收到的每個事件，其酬載都會顯示在事件的 data 欄位中：
| 範例 | 事件類型 | JSON 酬載 |
|---|---|---|
使用者在資料夾或共用雲端硬碟中新增檔案。 |
|
包含資源資料
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
不包含資源資料
{
"file": {
"id": "FILE_ID"
}
}
|
使用者將檔案移至資料夾或共用雲端硬碟。 |
|
包含資源資料
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
不包含資源資料
{
"file": {
"id": "FILE_ID"
}
}
|
使用者編輯檔案或上傳新版本。 |
|
包含資源資料
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
不包含資源資料
{
"file": {
"id": "FILE_ID"
}
}
|
使用者刪除檔案。 |
|
包含資源資料
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
不包含資源資料
{
"file": {
"id": "FILE_ID"
}
}
|
使用者將檔案丟進垃圾桶。 |
|
包含資源資料
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
不包含資源資料
{
"file": {
"id": "FILE_ID"
}
}
|
使用者從垃圾桶還原檔案。 |
|
包含資源資料
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
不包含資源資料
{
"file": {
"id": "FILE_ID"
}
}
|
使用者對檔案建立存取權提案。 |
|
包含資源資料
{
"accessProposal": [
{
"file_id": "FILE_ID",
"proposalId": "PROPOSAL_ID",
"recipientEmailAddress": "63",
"requesterEmailAddress": "application/vnd.google-apps.document",
"requestMessage": "grant me access to this file",
"rolesAndViews": [
{
"role": "writer",
"view": "published"
}
]
}
]
}
不包含資源資料
{
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
|
使用者解決檔案的存取提案。 |
|
包含資源資料
{
"accessProposal": [
{
"file_id": "FILE_ID",
"proposalId": "PROPOSAL_ID",
"recipientEmailAddress": "63",
"requesterEmailAddress": "application/vnd.google-apps.document",
"requestMessage": "resolve access to this file",
"rolesAndViews": [
{
"role": "writer",
"view": "published"
}
]
}
]
}
不包含資源資料
{
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
|
限制
- 當
DriveOptions中的includeDescendants布林欄位為true時，即使觸發事件的檔案位於雲端硬碟訂閱項目所用資料夾的許多層級下方，共用雲端硬碟和資料夾上的雲端硬碟訂閱項目仍會一律傳送事件。 - 即使您已為資料夾建立訂閱項目，您可能仍無法接收檔案階層中的所有事件，因為使用者或應用程式可能未獲授權存取這些事件。在這種情況下，訂閱項目仍有效，但您無法存取資源，因此不會收到任何事件。
- 系統支援訂閱所有檔案和資料夾的事件，但不支援訂閱共用雲端硬碟的根資料夾。訂閱功能僅支援共用雲端硬碟內的檔案和資料夾。直接對共用雲端硬碟的根資料夾所做的變更不會觸發事件。
- 授權訂閱的使用者必須擁有與訂閱事件相應的檔案權限。
- 訂閱項目只會接收使用者透過 Google Workspace 帳戶或 Google 帳戶存取資源的事件。