本页介绍了您的应用可以使用 Google Workspace Events API 订阅的 Google 云端硬盘事件。确定需要哪些类型的事件后，创建订阅即可开始接收来自云端硬盘的事件。
如需详细了解如何为云端硬盘开发应用，请参阅 Google Drive API 概览。
支持的云端硬盘事件
Google Workspace 订阅可让您接收有关云端硬盘中以下类型更改的事件：
您可以监控哪些资源中的事件
如需接收事件，您需要指定要监控的云端硬盘资源，该资源称为订阅的目标资源。
Google Workspace Events API 支持以下 Drive 目标资源：
| 目标资源 | 格式 | 限制（如适用） |
|---|---|---|
| 文件 | //googleapis.com/drive/v3/files/FILE
其中，FILE 是 Drive API |
授权订阅的用户必须拥有订阅中相对于订阅事件的文件权限。 |
| 共享云端硬盘 | //googleapis.com/drive/v3/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 事件的结构。
下表显示了订阅 Drive 资源时支持的事件类型：
| Event type | 格式 | 资源数据 | ||
|---|---|---|---|---|
| 文件订阅 | ||||
| 文件已添加到文件夹或共享云端硬盘。 |
|
|
||
| 文件被移至某个文件夹或共享云端硬盘。 |
|
|
||
| 文件被修改或上传了新修订版本。 |
|
|
||
| 文件被删除。 |
|
|
||
| 文件被移至回收站。 |
|
|
||
| 文件已从回收站中移除。 |
|
|
||
| 系统会针对文件创建访问提案。 |
|
|
||
| 针对某个文件的访问提案已解决。 |
|
|
||
| 订阅共享云端硬盘 | ||||
| 文件已添加到文件夹或共享云端硬盘。 |
|
|
||
| 文件被移至某个文件夹或共享云端硬盘。 |
|
|
||
| 文件被修改或上传了新修订版本。 |
|
|
||
| 文件被删除。 |
|
|
||
| 文件被移至回收站。 |
|
|
||
| 文件已从回收站中移除。 |
|
|
||
| 系统会针对文件创建访问提案。 |
|
|
||
| 针对某个文件的访问提案已解决。 |
|
|
||
事件数据
本部分介绍了 Google 云端硬盘中的事件的事件数据和有效负载示例。
当您的 Google Workspace 订阅收到来自 Google 云端硬盘的事件时，data 字段会包含相应事件的载荷。此载荷包含有关发生更改的 Google Workspace 资源的信息。例如，如果您已订阅文件事件，则这些事件的载荷包含有关发生更改的 file 资源的信息。
事件载荷中的资源数据
创建订阅时，您可以指定希望载荷包含资源详细信息还是仅包含资源名称。例如，如果您想接收有关云端硬盘中文件的事件，可以指定要在事件载荷中接收 files 资源的哪些字段。
下表提供了订阅 Drive 资源的 JSON 载荷示例。文件 ID 包含字母、数字和一些特殊字符，结构为 files/^[01][0-9a-zA-Z_-]+$/。例如 files/1aaabbbAAABBB111222-_。对于订阅接收的每个事件，载荷都会显示在事件的 data 字段中：
| 示例 | Event type | JSON 载荷 |
|---|---|---|
用户将文件添加到文件夹或共享云端硬盘。 |
|
包含资源数据
{
"fileCreatedEvent": {
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
}
排除资源数据
{
"fileCreatedEvent": {
"file": {
"id": "FILE_ID"
}
}
}
|
用户将文件移至文件夹或共享云端硬盘。 |
|
包含资源数据
{
"fileMovedEvent": {
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
}
排除资源数据
{
"fileMovedEvent": {
"file": {
"id": "FILE_ID"
}
}
}
|
用户修改文件或上传新修订版本。 |
|
包含资源数据
{
"fileContentChangedEvent": {
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
}
排除资源数据
{
"fileContentChangedEvent": {
"file": {
"id": "FILE_ID"
}
}
}
|
用户删除文件。 |
|
包含资源数据
{
"fileDeletedEvent": {
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
}
排除资源数据
{
"fileDeletedEvent": {
"file": {
"id": "FILE_ID"
}
}
}
|
用户将文件放入回收站。 |
|
包含资源数据
{
"fileTrashedEvent": {
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
}
排除资源数据
{
"fileTrashedEvent": {
"file": {
"id": "FILE_ID"
}
}
}
|
用户从回收站中恢复文件。 |
|
包含资源数据
{
"fileUntrashedEvent": {
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
}
排除资源数据
{
"fileUntrashedEvent": {
"file": {
"id": "FILE_ID"
}
}
}
|
用户针对文件创建访问权限提案。 |
|
包含资源数据
{
"accessProposalCreatedEvent": {
"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"
}
]
}
]
}
}
排除资源数据
{
"accessProposalCreatedEvent": {
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
}
|
用户解决文件访问提案。 |
|
包含资源数据
{
"accessProposalResolvedEvent": {
"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"
}
]
}
]
}
}
排除资源数据
{
"accessProposalResolvedEvent": {
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
}
|
限制
- 当
DriveOptions中的includeDescendants布尔值字段为true时，即使触发事件的文件嵌套在用于云端硬盘订阅的文件夹下方很多层，共享云端硬盘和文件夹上的云端硬盘订阅也始终会调度事件。 - 即使您已在某个文件夹中创建订阅，您也可能无法收到文件层次结构中的所有事件，因为用户或应用可能未被授予对这些事件的访问权限。在这种情况下，订阅仍处于有效状态，但您不会收到自己无权访问的资源的任何事件。
- 订阅功能支持所有文件和文件夹的事件，但不支持共享云端硬盘的根文件夹。订阅功能仅适用于共享云端硬盘内的文件和文件夹。直接对共享云端硬盘的根文件夹所做的更改不会触发事件。
- 授权订阅的用户必须对相应文件拥有权限，才能订阅相应事件。
- 订阅仅接收用户通过其 Google Workspace 账号或 Google 账号有权访问的资源的事件。