使用增量查询跟踪 Microsoft Graph 数据更改(预览)

Delta 查询使应用程序能够发现新创建、更新或删除的实体,无需使用每个请求对目标资源执行完全读取。Microsoft Graph 应用程序可以使用 delta 查询和本地数据存储高效地同步更改。

使用 delta 查询来跟踪资源集合的更改

通常的调用模式如下:

  1. 应用程序首先对所需资源运行 delta 函数以调用 GET 请求。
  2. Microsoft Graph 将发送一个包含已请求资源和状态令牌的响应。

    a.如果返回了 nextLink URL,则会话中存在要检索的其他数据页面。应用程序继续使用 nextLink URL 发出请求,直到响应中包含 deltaLink URL。

    b.如果返回了 deltaLink URL,则未返回关于资源现有状态的更多数据。为了执行以后的请求,应用程序使用 deltaLink URL 了解资源更改。

  3. 当应用程序需要了解资源更改时,会使用步骤 2 中收到的 deltaLink URL 发出新请求。可能在完成步骤 2 或应用程序检查更改时立即发出此请求。

  4. Microsoft Graph 返回响应,描述自上一个请求以来的资源更改和 nextLink URL 或 deltaLink URL。

状态令牌

增量查询 GET 响应中始终返回 nextLinkdeltaLink 响应头中指定的 URL。nextLink URL 包含的是 skipTokendeltaLink URL 包含的是 deltaToken

这些令牌对客户端不透明。以下是需要了解的详细信息:

  • 每个令牌都反映状态,并表示一轮更改跟踪中的响应快照。
  • 状态令牌还会进行编码,并包括初始 delta 查询请求中指定的其他查询参数(如 $select)。因此,不需要在后续 delta 查询请求中重复这些操作。
  • 执行增量查询时,可以将 nextLinkdeltaLink URL 复制并应用到下一个 delta 函数调用,无需检查 URL 的内容(包括其状态令牌)。

可选的查询参数

如果客户使用查询参数,则它必须在初始请求中指定。Microsoft Graph 自动将指定参数编码为响应中提供的 nextLinkdeltaLink。调用应用程序只需预先指定其所需的查询参数一次。Microsoft Graph 将为所有后续请求自动添加指定参数。

对于用户和组,在使用某些查询参数时受到限制:

  • 如果使用的是 $select 查询参数,则该参数表示客户倾向于仅跟踪 $select 语句中指定的属性或关系的更改。如果未选中的属性发生更改,则属性已更改的资源将不会出现在后续请求之后的 delta 响应中。
  • 不支持 $expand

delta 查询响应中的资源表示形式

  • 在 delta 查询响应中,使用标准表示形式表示受支持资源的新建实例。

  • 更新实例由它们的 id 表示,至少具有已更新的属性,但可能也包含其他属性。

  • 用户和组的关系更改被表示为对标准资源表示形式的注释。这些注释将使用 propertyName@delta 格式,仅当客户使用 $select 参数显式选择跟踪关系更改时才会出现。

  • 删除的实例仅使用其 id@removed 节点表示。@removed 节点可能包含有关为何删除该实例的其他信息。

对以后更改的说明:删除的实例的 @removed 节点当前以 “@removed” : “reason for removal” 的格式出现。但是,未来将会进行重大更改。在 delta 查询从 /beta 移动到 /v1.0 之前,将在删除的节点内嵌套一个对象,以提供更多信息。例如,@removed {reason: “reason for removal”}。此对象可以在以后展开,以包含有关此删除的其他元数据。

支持的资源

当前 Delta 查询支持在 Microsoft Graph /beta 终结点上预览以下资源:

资源集合 API
主日历的日历视图(日期范围)中的事件 事件资源的 delta 函数
资源的 delta 函数
邮件文件夹 邮件文件夹资源的 delta 函数
文件夹中的邮件 邮件资源的 delta 函数
私人联系人文件夹 联系人文件夹资源的 delta 函数
文件夹中的私人联系人 联系人资源的 delta 函数
用户 用户资源的 delta 函数
驱动器项目* driveItem 资源的 delta 函数

* v1.0 已支持跟踪对驱动器及其子级所做的更改。使用模式与其他支持资源类似,仅存在一些小的语法差异。以后将更新驱动器增量查询,以与其他资源类型保持一致。有关当前语法的详细信息,请访问 https://developer.microsoft.com/zh-cn/graph/docs/api-reference/v1.0/api/item_delta

先决条件

在对某个特定资源执行 delta 查询时也需要阅读该资源所需的相同权限

已知限制

有关使用 delta 查询的已知限制,请参阅已知问题文章中的 delta 查询部分

Delta 查询请求示例