訂閱 Google 雲端硬碟事件

本頁說明應用程式可使用 Google Workspace Events API 訂閱的 Google 雲端硬碟事件。決定需要哪些類型的事件後，請建立訂閱項目，開始接收雲端硬碟事件。

如要進一步瞭解如何開發雲端硬碟應用程式，請參閱「 Google Drive API 總覽」。

支援的雲端硬碟事件

訂閱 Google Workspace 後，您就能接收雲端硬碟中下列類型異動的事件：

  • 檔案建立或解決存取提案。

  • 在檔案或共用雲端硬碟中的檔案上建立、編輯、解決、重新開啟或刪除留言。

  • 檔案可以是：

    • 新增至資料夾或共用雲端硬碟。
    • 已移至資料夾或共用雲端硬碟。
    • 編輯或上傳新修訂版本。
    • 已移至垃圾桶或從垃圾桶中移除。
    • 已重新命名 (檔案或資料夾的名稱已變更)。

  • 在檔案或共用雲端硬碟中的檔案內，建立、編輯或刪除註解串的回覆。

可監控事件的資源

如要接收事件，請指定要監控的雲端硬碟資源，這稱為訂閱的目標資源。

Google Workspace Events API 支援下列 Google 雲端硬碟目標資源：

目標資源 格式 限制 (如適用)
檔案 //drive.googleapis.com/files/FILE

其中 FILE 是 Drive API files 資源的 資源名稱中的 ID。您可以從檔案的網址取得 ID，也可以使用 files.list 方法取得 ID。

 授權訂閱的使用者必須具備訂閱項目中檔案的權限，才能訂閱事件。
共用雲端硬碟 //drive.googleapis.com/drives/DRIVE

其中 DRIVE 是 Drive API drives 資源的 資源名稱中的 ID。您可以從雲端硬碟的網址取得 ID，也可以使用 drives.list 方法取得 ID。

 訂閱項目只會接收使用者透過 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.workspace.drive.accessproposal.v3.created

accessproposal
檔案的存取提案已解決。

google.workspace.drive.accessproposal.v3.resolved

accessproposal
在檔案或共用雲端硬碟中的檔案上建立留言。

google.workspace.drive.comment.v3.created

comment
編輯檔案或共用雲端硬碟中檔案的註解。

google.workspace.drive.comment.v3.edited

comment
檔案或共用雲端硬碟中的檔案註解已解決。

google.workspace.drive.comment.v3.resolved

comment
重新開啟檔案或共用雲端硬碟中檔案的留言。

google.workspace.drive.comment.v3.reopened

comment
刪除檔案或共用雲端硬碟中檔案的留言。

google.workspace.drive.comment.v3.deleted

comment
檔案新增至資料夾或共用雲端硬碟。

google.workspace.drive.file.v3.created

file
檔案移至資料夾或共用雲端硬碟。

google.workspace.drive.file.v3.moved

file
編輯檔案或上傳新修訂版本。

google.workspace.drive.file.v3.contentChanged

file
刪除檔案。

google.workspace.drive.file.v3.deleted

file
檔案已移至垃圾桶。

google.workspace.drive.file.v3.trashed

file
檔案從垃圾桶中移除。

google.workspace.drive.file.v3.untrashed

file
檔案已重新命名。

google.workspace.drive.file.v3.renamed

file
在檔案或共用雲端硬碟中的檔案的留言串中建立回覆。

google.workspace.drive.reply.v3.created

reply
在檔案或共用雲端硬碟中的檔案內，編輯留言串中的回覆。

google.workspace.drive.reply.v3.edited

reply
刪除檔案或共用雲端硬碟中檔案的留言串回覆。

google.workspace.drive.reply.v3.deleted

reply

事件資料

本節說明 Google 雲端硬碟中的事件資料和事件酬載範例。

當 Google Workspace 訂閱方案收到來自 Google 雲端硬碟的事件時，data 欄位會包含該事件的酬載。這個酬載包含變更的 Google Workspace 資源相關資訊。舉例來說，如果您已訂閱檔案事件，這些事件的酬載會包含變更的 files 資源相關資訊。

事件酬載中的資源資料

建立訂閱項目時，您可以指定要在酬載中加入資源詳細資料，還是只加入資源名稱。舉例來說，如果您想接收雲端硬碟檔案的相關事件，可以指定要在事件酬載中接收哪些 files 資源的欄位。

下表提供訂閱 Drive 資源的 JSON 酬載範例。檔案 ID 包含字母、數字和一些特殊字元，結構為 files/^[01][0-9a-zA-Z_-]+$/。例如：files/1aaabbbAAABBB111222-_。訂閱項目收到的每個事件，其酬載都會顯示在事件的 data 欄位中：

範例 事件類型 JSON 酬載

使用者在檔案上建立存取提案。

google.workspace.drive.accessproposal.v3.created
包含資源資料
{
    "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"
          }
        ]
      }
    ]
}
不包含資源資料
{
    "accessProposal": [
      {
        "proposalId": "PROPOSAL_ID"
      }
    ]
}

使用者解決檔案的存取提案。

google.workspace.drive.accessProposal.v3.resolved
包含資源資料
{
    "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"
          }
        ]
      }
    ]
}
不包含資源資料
{
    "accessProposal": [
      {
        "proposalId": "PROPOSAL_ID"
      }
    ]
}

使用者在檔案中建立留言。

google.workspace.drive.comment.v3.created
包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID",
      "mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
      "assignee_email_address": "yuri@altostrat.com"
    }
}
不包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID"
    }
}

使用者編輯檔案中的註解。

google.workspace.drive.comment.v3.edited
包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID",
      "mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
      "assignee_email_address": "yuri@altostrat.com"
    }
}
不包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID"
    }
}

使用者解決檔案中的留言。

google.workspace.drive.comment.v3.resolved
包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID",
      "mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
      "assignee_email_address": "yuri@altostrat.com"
    }
}
不包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID"
    }
}

使用者重新開啟檔案的留言。

google.workspace.drive.comment.v3.reopened
包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID",
      "mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
      "assignee_email_address": "yuri@altostrat.com"
    }
}
不包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID"
    }
}

使用者刪除檔案中的留言。

google.workspace.drive.comment.v3.deleted
包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID",
      "mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
      "assignee_email_address": "yuri@altostrat.com"
    }
}
不包含資源資料
{
    "comment": {
      "id": "COMMENT_ID",
      "file_id": "FILE_ID"
    }
}

使用者在資料夾或共用雲端硬碟中新增檔案。

google.workspace.drive.file.v3.created
包含資源資料
{
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
}
不包含資源資料
{
    "file": {
      "id": "FILE_ID"
    }
}

使用者將檔案移至資料夾或共用雲端硬碟。

google.workspace.drive.file.v3.moved
包含資源資料
{
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
}
不包含資源資料
{
    "file": {
      "id": "FILE_ID"
    }
}

使用者編輯檔案或上傳新版本。

google.workspace.drive.file.v3.contentChanged
包含資源資料
{
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
}
不包含資源資料
{
    "file": {
      "id": "FILE_ID"
    }
}

使用者刪除檔案。

google.workspace.drive.file.v3.deleted
包含資源資料
{
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
}
不包含資源資料
{
    "file": {
      "id": "FILE_ID"
    }
}

使用者將檔案丟進垃圾桶。

google.workspace.drive.file.v3.trashed
包含資源資料
{
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
}
不包含資源資料
{
    "file": {
      "id": "FILE_ID"
    }
}

使用者從垃圾桶還原檔案。

google.workspace.drive.file.v3.untrashed
包含資源資料
{
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
}
不包含資源資料
{
    "file": {
      "id": "FILE_ID"
    }
}

使用者重新命名檔案或資料夾。

google.workspace.drive.file.v3.renamed
包含資源資料
{
    "file": {
      "id": "FILE_ID",
      "parent": "PARENT_ID",
      "version": "63",
      "mimeType": "application/vnd.google-apps.document"
    }
}
不包含資源資料
{
    "file": {
      "id": "FILE_ID"
    }
}

使用者在留言串中建立留言回覆。

google.workspace.drive.reply.v3.created
包含資源資料
{
    "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"
    }
}
不包含資源資料
{
    "reply": {
      "id": "REPLY_ID",
      "comment_id": "COMMENT_ID",
      "file_id": "FILE_ID"
    }
}

使用者編輯留言串中的留言回覆。

google.workspace.drive.reply.v3.edited
包含資源資料
{
    "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"
    }
}
不包含資源資料
{
    "reply": {
      "id": "REPLY_ID",
      "comment_id": "COMMENT_ID",
      "file_id": "FILE_ID"
    }
}

使用者刪除留言串中的留言回覆。

google.workspace.drive.reply.v3.deleted
包含資源資料
{
    "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"
    }
}
不包含資源資料
{
    "reply": {
      "id": "REPLY_ID",
      "comment_id": "COMMENT_ID",
      "file_id": "FILE_ID"
    }
}

限制
  • 當 includeDescendants DriveOptions 中的布林值欄位為 true 時，即使觸發事件的檔案位於雲端硬碟訂閱項目所用資料夾的許多層級下方，共用雲端硬碟和資料夾的雲端硬碟訂閱項目一律會傳送事件。
  • 即使您已為資料夾建立訂閱項目，您可能仍無法接收檔案階層中的所有事件，因為使用者或應用程式可能未獲授權存取這些事件。在這種情況下，訂閱項目仍有效，但您無法存取資源，因此不會收到任何事件。
  • 系統支援訂閱所有檔案和資料夾的事件，但不支援訂閱共用雲端硬碟的根資料夾。訂閱功能僅支援共用雲端硬碟內的檔案和資料夾。直接對共用雲端硬碟的根資料夾進行變更，不會觸發事件。
  • 授權訂閱的使用者必須擁有與訂閱事件相應的檔案權限。
  • 訂閱項目只會接收使用者透過 Google Workspace 帳戶或 Google 帳戶存取的資源事件。