本文档介绍了如何使用推送通知来 在资源发生更改时应用
概览
Google Drive API 提供推送通知,让您可以监控 资源的变化您可以利用此功能 部署应用它让您可以消除额外的网络和计算资源, 轮询资源以确定资源是否已更改而产生的费用。 每当受监控的资源发生变化时,Google Drive API 都会通知您, 应用。
如需使用推送通知,您必须完成以下两项操作:
设置接收网址或“webhook”回调接收器。
这个 是一个 HTTPS 服务器,用于处理 在资源发生更改时触发。
渠道指定了通知的路由信息 消息。在频道设置过程中,您必须指明 希望接收通知每当渠道的资源发生变化时 Google Drive API 会以
POST
的形式发送通知消息, 向该网址发送请求。
创建通知渠道
如需请求推送通知,您必须设置通知渠道 监控每个您想要监控的资源设置通知渠道后 之后,Google Drive API 会在检测到任何已查看的资源时通知您的应用, 更改。
发出监控请求
每个可观察的 Google Drive API 资源都有一个关联的
watch
方法,并且 URI 的格式如下:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
要为关于更改配置的消息设置通知渠道,请执行以下操作:
请向特定资源发送 POST
请求,
watch
方法。
每个通知渠道都与特定用户以及
特定资源(或一组资源)。watch
请求
除非当前用户
或服务账号
拥有此资源或有权访问此资源。
示例
以下代码示例展示了如何使用 channels
资源通过 files.watch
方法开始监控单个 files
资源的更改:
POST https://www.googleapis.com/drive/v3/files/fileId/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
以下代码示例展示了如何使用 channels
资源通过 changes.watch
方法开始监控所有 changes
:
POST https://www.googleapis.com/drive/v3/changes/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
必要属性
每个 watch
请求都必须提供以下字段:
-
唯一标识此内容的
id
属性字符串 新通知渠道。我们建议使用 通用唯一标识符 (UUID) 或类似名称 唯一字符串。长度上限:64 个字符。您设置的 ID 值会回显到 每个通知的
X-Goog-Channel-Id
HTTP 标头 消息。 -
一个
type
属性字符串,设置为该值web_hook
。 -
address
属性字符串,设置为监听的网址 并响应此通知渠道的通知。这是 网络钩子回调网址,并且必须使用 HTTPS。请注意,Google Drive API 能够向 仅当安装了有效的 SSL 证书时,才指定此 HTTPS 地址 。无效的证书包括:
- 自签发证书
- 由不受信任的来源签发的证书
- 已被撤消的证书
- 证书的主题与目标不匹配 主机名
可选属性
您也可以通过
watch
请求:
-
token
属性,用于指定任意字符串 值用作渠道令牌。您可以使用通知渠道 用于各种用途的令牌。例如,您可以使用 令牌来验证收到的每条消息是否都适用于 应用 - 确保系统不会发出通知 或将邮件转送到 并根据此渠道的用途说明您的应用。长度上限: 256 个字符。该令牌包含在 每条通知中包含
X-Goog-Channel-Token
HTTP 标头 消息。如果您使用通知渠道令牌,我们建议您:
使用可扩展的编码格式,例如网址查询 参数。示例:
forwardTo=hr&createdBy=mobile
请勿包含 OAuth 令牌等敏感数据。
-
expiration
属性字符串,设置为 Unix 时间戳 (以毫秒为单位)。 停止为此通知渠道发送消息。如果某个渠道有到期时间,则系统会将其添加为
X-Goog-Channel-Expiration
HTTP 标头的 格式)。 。
如需详细了解该请求,请参阅 watch
方法
适用于 API 参考文档中的 files
和 changes
方法。
观看回复
如果 watch
请求成功创建了通知
渠道,则会返回 HTTP 200 OK
状态代码。
监视响应的消息正文提供 通知渠道,如下例所示。
{ "kind": "api#channel", "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable. }
除了您在请求中发送的属性外,
返回的信息还包含 resourceId
和
resourceUri
,用于标识此资源上正在监控的资源
通知渠道。
您可以将返回的信息传递给其他通知渠道 操作,例如当您要停止接收 通知。
同步信息
创建用于监控资源的通知渠道后,
Google Drive API 会发送 sync
消息以指明:
开始接收通知。X-Goog-Resource-State
HTTP
这些邮件的标头值为 sync
。原因:网络
时间问题,可能会收到 sync
消息
您甚至无需收到 watch
方法响应。
您可以放心地忽略 sync
通知,但您可以
也会使用它例如,如果您不想保留
可以使用 X-Goog-Channel-ID
和
X-Goog-Resource-ID
调用中的值
停止接收通知。您还可以使用
sync
通知,用于进行一些初始化以为
事件。
Google Drive API 发送到的 sync
消息的格式
您的接收网址如下所示。
POST https://mydomain.com/notifications // Your receiving URL. X-Goog-Channel-ID: channel-ID-value X-Goog-Channel-Token: channel-token-value X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires. X-Goog-Resource-ID: identifier-for-the-watched-resource X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource X-Goog-Resource-State: sync X-Goog-Message-Number: 1
同步邮件始终带有 X-Goog-Message-Number
HTTP
1
的标头值。此渠道的每条后续通知都有
即使邮件和聊天消息编号相同,
不依序。
续订通知渠道
通知渠道可以设置到期时间,也可以设置一个值
由您的请求或任何 Google Drive API 内部限制决定
或默认值(使用限制性更强的值)。渠道的有效期
时间(如果有)作为 Unix 时间戳包含在内
(以毫秒为单位)。watch
此外,
到期日期和时间(以简单易懂的格式)列在每个
此渠道收到的通知消息
X-Goog-Channel-Expiration
HTTP 标头。
目前没有自动续期通知渠道的方法。时间
渠道即将到期,您必须通过调用
watch
方法。与往常一样,您必须为
新频道的 id
属性。请注意,
视为“重叠”两个通知渠道对应的时间段
同一项资源是否处于活动状态。
接收通知
每当受监控的资源发生变化时,您的应用都会收到
说明更改的通知消息。Google Drive API 会将这些
以 HTTPS POST
请求的形式发送到您指定为
此通知的 address
属性
。
解读通知消息格式
所有通知消息都包含一组 HTTP 标头
X-Goog-
前缀。
某些类型的通知还可能包含
消息正文。
标头
Google Drive API 向您的接收方发布的通知消息 网址包含以下 HTTP 标头:
标题 | 说明 |
---|---|
始终存在 | |
|
您提供的用于标识此 ID 的 UUID 或其他唯一字符串 通知渠道。 |
|
用于标识此通知的消息的整数
。对于 sync 消息,值始终为 1 。消息
通道上每一条后续消息的显示编号都会增加,
而非依序。 |
|
标识所监控资源的不透明值。此 ID 为 在各 API 版本中保持稳定。 |
|
触发通知的新资源状态。
可能的值:
sync 、add 、remove 、update 、
trash 、untrash 或 change
,了解所有最新动态。
|
|
所监控资源的 API 版本特定标识符。 |
有时会出现 | |
|
有关更改的其他详细信息。
可能的值:
content ,
parents ,
children 或
permissions
,了解所有最新动态。
不随 sync 封邮件提供。 |
|
通知渠道到期的日期和时间,以 简单易懂的格式仅当已定义时,此字段才会显示。 |
|
由您的应用设置的通知渠道令牌,以及 可用于验证通知来源。仅当 。 |
“files
”和“changes
”的通知消息为空。
示例
files
资源的更改通知消息(不包含请求正文):
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66 X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g X-Goog-Resource-State: update X-Goog-Changed: content,properties X-Goog-Message-Number: 10
changes
资源的更改通知消息,其中包括请求正文:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 118 X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43 X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes X-Goog-Resource-State: changed X-Goog-Message-Number: 23 { "kind": "drive#changes" }
有关通知的操作
如需指示成功,您可以返回以下任一状态代码:
200
、201
、202
、204
或
102
。
如果您的服务使用 Google 的 API 客户端库
并返回 500
、502
、503
或 504
(Google Drive API)
使用指数退避算法重试。
所有其他返回状态代码都被视为消息失败。
了解 Google Drive API 通知事件
本部分详细介绍了您可以 。
送达时间 | ||
---|---|---|
sync |
files 、changes |
已成功创建渠道。您应该会开始收到相关通知。 |
add |
files |
创建或共享了资源。 |
|
files |
删除或停止共享现有资源。 |
|
files |
已更新资源的一个或多个属性(元数据)。 |
|
files |
一项资源已移至回收站。 |
|
files |
已从回收站中移除一项资源。 |
|
changes |
已添加一个或多个更新日志项。 |
对于 update
事件,系统可能会提供 X-Goog-Changed
HTTP 标头。该标题包含以逗号分隔的列表,描述了已发生的更改类型。
更改类型 | 含义 |
---|---|
content |
资源内容已更新。 |
properties |
一个或多个资源属性已更新。 |
parents |
添加或移除了一个或多个资源父级。 |
children |
添加或移除了一个或多个资源子项。 |
permissions |
资源权限已更新。 |
使用 X-Goog-Changed
标头的示例:
X-Goog-Resource-State: update X-Goog-Changed: content, permissions
停止通知
expiration
属性用于控制何时自动停止通知。您可以
选择先停止接收特定频道的通知
通过调用 stop
方法过期
以下 URI:
https://www.googleapis.com/drive/v3/channels/stop
此方法要求您至少提供频道的
id
和 resourceId
属性,如
示例。请注意,如果 Google Drive API 具有多种类型的
具有 watch
方法的资源,只有一个方法
stop
方法。
只有具备适当权限的用户才能停止频道。具体而言:
- 如果频道是由常规用户账号创建的,则只有该账号 来自同一客户端的用户(通过 OAuth 2.0 客户端 ID 来标识, 身份验证令牌)可以停止渠道。
- 如果渠道是由服务账号创建的,则同一服务账号的任何用户 客户端可以停止该频道。
以下代码示例展示了如何停止接收通知:
POST https://www.googleapis.com/drive/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }