使用 webhook 接收服务间通知

  • 项目

OneDrive 通过 webhook 提供服务间通知。 webhook 提供简单的通知管道，这样应用无需轮询服务，即可注意到用户驱动器更改。

如果应用有权访问的用户驱动器项发生更改，将会向所提供的 URL 发送请求，以通知所发生的更改。

常见任务

任务 HTTP 方法
新建订阅 POST /subscriptions
删除订阅 DELETE /subscriptions/{id}
更新订阅 PATCH /subscriptions/{id}

注册

若要注册申请 webhook，请添加新的订阅，以订阅表示要接收其更改通知的作用域顶级项。

若要详细了解如何注册通知 URL，请参阅添加新订阅。

通知作用域

只有当更改满足以下条件时，才会向应用发送相关 webhook 通知：

  • 应用已获用户授权，可以访问 OneDrive 内容。
  • 应用有权访问生成通知的项。
  • 订阅尚未到期。

除非单独订阅原始项，否则应用不会收到与登录用户共享的项或用户驱动器中的远程项的相关通知。

接收通知

创建订阅后，当通知作用域下的项发生更改时，OneDrive 就会向已注册的 URL 发送POST 请求。 如果多个用户在同一时间段内同时做出更改，那么向服务发送的多个通知可能会被整合到一个请求中进行批处理。

示例通知

向通知 URL 发送的 HTTP 请求在正文中包含 Webhook Notification 资源，如下所示：

{
  "value": [
    {
      "subscriptionId": "A640DFF3-0429-44FC-AF7E-30523A476864",
      "expirationDateTime": "2017-02-22T16:00:00Z",
      "resource": "/me/drive/root",
      "clientState": "client-specific string"
    }
  ]
}

可能会注意到，在通知中看不到触发通知的更改。 应用应使用 delta 谓词检测 OneDrive 项状态是否发生任何变化，并存储 syncToken 值以便下次能够收到通知。

错误处理

如果向服务发送通知时出错了，OneDrive 将遵循指数退避逻辑。 任何具有 200-299 范围外 HTTP 状态代码的响应或超时响应，将在接下来的几分钟内再次尝试。 如果请求在 15 分钟后未成功，将会删除通知。

今后仍会尝试向服务发送通知，尽管服务保留在检测到足够次数的失败后删除订阅的权利。

到期

如果在新建订阅时未定义到期日期，那么系统会自动提供此订阅的到期日期。 默认情况下，订阅被设为自创建之日起 6 个月后到期。

最佳做法

使用 webhook 时，请务必注意以下几点：

服务间

不得尝试使用 webhook 直接通知客户端设备。 每个应用都有一个对所有用户调用的 webhook URL。 此 URL 应指向所控制的服务。 可以选择让服务分析通知消息，然后根据需要将相应的推送通知转发给客户端应用。

快速响应

应用响应请求的时间有限。 应将通知更新信息排入队列，然后在单独的线程中处理这些请求。 响应 webhook 请求之前，不得尝试从 OneDrive 服务拉取更改。

预计并发通知数

在很多情况下，可能会连续快速地收到同一用户的多个通知。 例如，如果是新用户或要将一批内容上传到 OneDrive，可能会在处理首个通知前收到同一用户的多个通知。 请确保 webhook 通知的响应操作能够正确处理这种情况。