资源更改通知

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

概览

Google Drive API 提供推送通知，可让您监控资源的变化。您可以使用此功能来提升应用的性能。这样，您就可以避免轮询资源以确定资源是否已更改，产生额外的网络和计算费用。每当受监控的资源发生更改时，Google Drive API 都会通知您的应用。

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

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

    这是一个 HTTPS 服务器，用于处理资源发生更改时触发的 API 通知消息。

  • 为您要监控的每个资源端点设置（通知渠道）。

    渠道用于指定通知消息的路由信息。在频道设置过程中，您必须确定要用来接收通知的具体网址。每当渠道的资源发生变化时，Google Drive API 都会向该网址以 POST 请求的形式发送通知消息。

目前，Google Drive API 支持在 files 和 changes 方法更改时发送通知。

创建通知渠道

如需请求推送通知，您必须为要监控的每项资源设置通知渠道。设置通知渠道后，Google Drive API 会在任何受监控的资源发生更改时通知您的应用。

发出监控请求

每个可观察的 Google Drive API 资源都有一个关联的 watch 方法，其 URI 格式如下：

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

如需为有关特定资源更改的消息设置通知渠道，请向该资源的 watch 方法发送 POST 请求。

每个通知渠道都与特定用户和特定资源（或一组资源）相关联。除非当前用户或服务帐号拥有此资源或有权访问此资源，否则 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 个字符。

    您为此渠道收到的每条通知消息的 X-Goog-Channel-Id HTTP 标头都会回显您设置的 ID 值。

  • 一个设置为 web_hook 值的 type 属性字符串。

  • address 属性字符串，设置为监听和响应此通知渠道的通知的网址。这是您的网络钩子回调网址，并且必须使用 HTTPS。

    请注意，只有当您的网络服务器上安装了有效的 SSL 证书时，Google Drive API 才能向此 HTTPS 地址发送通知。无效的证书包括：

    • 自签发证书
    • 由不受信任的来源签发的证书
    • 已被撤消的证书
    • 主题与目标主机名不匹配的证书。

可选属性

您还可以使用 watch 请求指定以下可选字段：

  • token 属性，用于指定要用作渠道令牌的任意字符串值。您可以将通知渠道令牌用于各种目的。例如，您可以使用令牌来验证每条传入的消息是否都来自您的应用创建的渠道（以确保通知没有仿冒），或者根据此渠道的用途将消息路由到您应用中的正确目的地。长度上限：256 个字符。

    令牌包含在应用针对此渠道收到的每条通知消息的 X-Goog-Channel-Token HTTP 标头中。

    如果您使用通知渠道令牌，我们建议您：

    • 使用可扩展的编码格式，例如网址查询参数。示例：forwardTo=hr&createdBy=mobile

    • 请勿包含 OAuth 令牌等敏感数据。

  • expiration 属性字符串，设置为您希望 Google Drive API 停止为此通知渠道发送消息的日期和时间的 Unix 时间戳（以毫秒为单位）。

    如果某个渠道有到期时间，则系统会在应用针对该渠道收到的每条通知消息中，将该渠道作为 X-Goog-Channel-Expiration HTTP 标头的值（采用人类可读懂的格式）包含在该渠道中。

如需详细了解该请求，请参阅 API 参考文档中 files 和 changes 方法的 watch 方法。

观看回复

如果 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，用于标识此通知渠道上所监控的资源。

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

如需详细了解该响应，请参阅 API 参考文档中 files 和 changes 方法的 watch 方法。

同步信息

创建用于监控资源的通知渠道后，Google Drive API 会发送 sync 消息，以指示通知正在启动。这些消息的 X-Goog-Resource-State HTTP 标头值为 sync。由于网络计时问题，您甚至可能在您收到 watch 方法响应之前就收到 sync 消息。

您可以放心地忽略 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 属性的网址。

解读通知消息格式

所有通知消息都包含一组前缀为 X-Goog- 的 HTTP 标头。某些类型的通知还可以包含消息正文。

标头

Google Drive API 向您的接收网址发布的通知消息包含以下 HTTP 标头：

标头 说明
始终存在
X-Goog-Channel-ID 您提供的用于标识此通知渠道的 UUID 或其他唯一字符串。
X-Goog-Message-Number 用于标识此通知渠道的消息的整数。对于 sync 消息，值始终为 1。通道上的每条后续消息都会增加消息编号，但它们不依序。
X-Goog-Resource-ID 标识所监控资源的不透明值。此 ID 在各 API 版本中是稳定的。
X-Goog-Resource-State 触发通知的新资源状态。 可能的值：sync、add、remove、update、trash、untrash 或 change。
X-Goog-Resource-URI 所监控资源的 API 版本特定标识符。
有时会出现
X-Goog-Changed 有关变更的其他详细信息。 可能的值：content、parents、children 或 permissions。 不随 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"
}

有关通知的操作

如需指示成功，您可以返回以下任一状态代码：200、201、202、204 或 102。

如果您的服务使用 Google 的 API 客户端库并返回 500、502、503 或 504，则 Google Drive API 会使用指数退避算法重试。所有其他返回状态代码都被视为消息失败。

了解 Google Drive API 通知事件

本部分详细介绍了通过 Google Drive API 使用推送通知时可能会收到的通知消息。

X-Goog-Resource-State 适用对象 送达时间
sync files、changes 已成功创建渠道。您应该会开始收到相关通知。
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 属性用于控制何时自动停止通知。您可以选择在以下 URI 中调用 stop 方法，选择在特定频道过期之前停止接收该频道的通知：

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