资源更改通知

本文档介绍了如何使用推送通知来 在资源发生更改时应用

概览

Google Drive API 提供推送通知,让您可以监控 资源的变化您可以利用此功能 部署应用它让您可以消除额外的网络和计算资源, 轮询资源以确定资源是否已更改而产生的费用。 每当受监控的资源发生变化时,Google Drive API 都会通知您, 应用。

如需使用推送通知,您必须完成以下两项操作:

  • 设置接收网址或“webhook”回调接收器。

    这个 是一个 HTTPS 服务器,用于处理 在资源发生更改时触发。

  • 为每个您要部署的资源端点设置一个(通知渠道) 观看。

    渠道指定了通知的路由信息 消息。在频道设置过程中,您必须指明 希望接收通知每当渠道的资源发生变化时 Google Drive API 会以 POST 的形式发送通知消息, 向该网址发送请求。

目前,Google Drive API 支持在发生以下情况时发送通知: fileschanges 方法。

创建通知渠道

如需请求推送通知,您必须设置通知渠道 监控每个您想要监控的资源设置通知渠道后 之后,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 参考文档中的 fileschanges 方法。

观看回复

如果 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.
}

除了您在请求中发送的属性外, 返回的信息还包含 resourceIdresourceUri,用于标识此资源上正在监控的资源 通知渠道。

您可以将返回的信息传递给其他通知渠道 操作,例如当您要停止接收 通知

如需详细了解响应,请参阅 watch 适用于 API 参考中的 fileschanges 方法的方法。

同步信息

创建用于监控资源的通知渠道后, Google Drive API 会发送 sync 消息以指明: 开始接收通知。X-Goog-Resource-State HTTP 这些邮件的标头值为 sync。原因:网络 时间问题,可能会收到 sync 消息 您甚至无需收到 watch 方法响应。

您可以放心地忽略 sync 通知,但您可以 也会使用它例如,如果您不想保留 可以使用 X-Goog-Channel-IDX-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 标头:

标题 说明
始终存在
X-Goog-Channel-ID 您提供的用于标识此 ID 的 UUID 或其他唯一字符串 通知渠道。
X-Goog-Message-Number 用于标识此通知的消息的整数 。对于 sync 消息,值始终为 1。消息 通道上每一条后续消息的显示编号都会增加, 而非依序。
X-Goog-Resource-ID 标识所监控资源的不透明值。此 ID 为 在各 API 版本中保持稳定。
X-Goog-Resource-State 触发通知的新资源状态。 可能的值: syncaddremoveupdatetrashuntrashchange ,了解所有最新动态。
X-Goog-Resource-URI 所监控资源的 API 版本特定标识符。
有时会出现
X-Goog-Changed 有关更改的其他详细信息。 可能的值: content, parents, childrenpermissions ,了解所有最新动态。 不随 sync 封邮件提供。
X-Goog-Channel-Expiration 通知渠道到期的日期和时间,以 简单易懂的格式仅当已定义时,此字段才会显示。
X-Goog-Channel-Token 由您的应用设置的通知渠道令牌,以及 可用于验证通知来源。仅当 。

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"
}

有关通知的操作

如需指示成功,您可以返回以下任一状态代码: 200201202204102

如果您的服务使用 Google 的 API 客户端库 并返回 500502503504(Google Drive API) 使用指数退避算法重试。 所有其他返回状态代码都被视为消息失败。

了解 Google Drive API 通知事件

本部分详细介绍了您可以 。

X-Goog-Resource-State 适用对象 送达时间
sync fileschanges 已成功创建渠道。您应该会开始收到相关通知。
add files 创建或共享了资源。
remove files 删除或停止共享现有资源。
update files 已更新资源的一个或多个属性(元数据)。
trash files 一项资源已移至回收站。
untrash files 已从回收站中移除一项资源。
change 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

此方法要求您至少提供频道的 idresourceId 属性,如 示例。请注意,如果 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"
}