使用增量查询跟踪 Microsoft Graph 数据更改

  • 项目

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

使用增量查询有助于避免不断轮询 Microsoft Graph，因为应用仅请求自上次请求以来更改的数据。 此模式允许应用程序减少请求的数据量，从而降低请求成本，因此可能会限制请求 被限制的可能性。

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

通常的调用模式如下：

  1. 应用程序在所需资源上使用 delta 函数发出 GET 请求。 例如，GET https://graph.microsoft.com/v1.0/users/delta。

    提示

    /delta 是完全限定名称 /microsoft.graph.delta的快捷方式。 Microsoft Graph SDK 生成的请求使用完全限定的名称。

  2. Microsoft Graph 使用请求的资源和 状态令牌进行响应。

    a. 如果 Microsoft Graph 返回 @odata.nextLink URL，则会话中需要检索更多的数据页，即使当前响应包含空结果也是如此。 应用程序使用该 @odata.nextLink URL 继续发出检索所有数据页的请求，直到 Microsoft Graph 在响应中返回 @odata.deltaLink URL。

    b. 如果 Microsoft Graph 返回 @odata.deltaLink URL，则当前会话中没有有关要返回的资源的现有状态的更多数据。 对于将来的请求，应用程序使用 @odata.deltaLink URL 来了解对资源的更改。

    注意

    步骤 2 中的 Microsoft Graph 响应包括 集合中当前 存在的资源。 不会返回在初始增量查询之前删除的资源。 初始请求前进行的更新在返回的资源上按其最新状态进行汇总。

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

  4. Microsoft Graph 返回响应（@odata.nextLink URL 或 @odata.deltaLink URL），其中描述了自上一个请求以来的资源变更。

注意

  • 存储在用户和组等Microsoft Entra ID (中的资源) 支持“立即同步”方案。 这样一来，便可以跳过第 1 步和第 2 步（如果不想检索资源完整状态的话），并改为请求获取最新 @odata.deltaLink。 将 $deltatoken=latest 追加到 delta 函数中，这样响应就会包含 @odata.deltaLink，而不包含资源数据。 OneDrive 和 SharePoint 中的资源也支持此功能，但需要 token=latest 这样做。
  • $select某些Microsoft Entra资源支持 和 $deltaLink 查询参数，以便客户可以更改要跟踪的现有 @odata.deltaLink的属性。 不支持同时 $select 包含 和 $skiptoken 的增量查询。

状态令牌

增量查询 GET 响应始终包括在 或 @odata.deltaLink 响应标头中指定的 @odata.nextLink URL。 URL @odata.nextLink 包括 $skiptoken，URL @odata.deltaLink 包含 $deltatoken。

这些令牌对客户端应用不透明，但很重要，如下所示：

  • 每个令牌都反映状态，并表示一轮更改跟踪中的响应快照。
  • 状态标记 (编码并包含查询参数，例如 $select 初始增量查询请求中指定的) 。 因此，请勿修改后续增量查询请求以重复这些查询参数。
  • 执行增量查询时，可以将 @odata.nextLink 或 @odata.deltaLink URL 复制并应用到下一个 delta 函数调用，无需检查 URL 的内容（包括其状态令牌）。

可选的查询参数

如果客户端使用查询参数， 则必须 在初始请求中指定它。 Microsoft Graph 会自动将指定的查询参数编码为 @odata.nextLink 响应中的 或 @odata.deltaLink 以及所有后续 @odata.nextLink 或 @odata.deltaLink URL。

请注意以下可选查询参数的常规有限支持：

  • $orderby

    不要假设从增量查询返回的响应的特定序列。 假设同一项目可以显示在 @odata.nextLink 序列的任意位置，并以合并逻辑进行处理。

  • $top

    每页中的对象数量可能因资源类型和资源更改类型而异。

对于消息资源，请参阅增量查询中的查询参数支持的详细信息。

对于用户和组资源，在使用某些查询参数时受到限制：

  • 不支持 $expand。

  • 不支持 $top。

  • 不支持 $orderby。

  • $select如果使用查询参数，则 参数指示客户端倾向于仅跟踪语句中指定的属性或关系上的$select更改。 如果对未选择的属性发生更改，则后续请求后，该属性更改的资源不会出现在增量响应中。

  • $select 还分别支持用户和组的 管理 器和 成员 导航属性。 选择这些属性可以跟踪对用户管理器和组成员身份的更改。

  • 范围筛选器允许跟踪对一个或多个特定用户或组的更改， 仅按对象 ID 进行筛选。 例如，以下请求会返回与查询筛选器中指定的 ID 相匹配的组的更改。

https://graph.microsoft.com/beta/groups/delta/?$filter=id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'

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

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

  • 更新的实例由其 ID 表示 ，至少具有 更新的属性，但可能包括其他属性。

  • 用户和组的关系表示为标准资源表示形式的注释。 这些批注使用 格式propertyName@delta。 批注包含在初始增量查询请求的响应中。

  • 已删除的实例由其 ID 和 @removed 对象表示。 @removed 对象可能包含有关删除实例的原因的其他信息。 例如，"@removed": {"reason": "changed"}。 可能的 @removed 原因可以是changed 或 deleted。

    • changed表示该项已被删除，可以从 deletedItems 恢复。

    • deleted 指示项目已删除且无法还原。

      可以在初始增量查询响应中和跟踪 () @odata.nextLink 响应中返回@removed对象。 例如，仍可从已删除的项还原的已删除目录对象显示为 "@removed": {"reason": "changed"}。 使用增量查询请求的客户端应设计为处理响应中的这些对象。

  • 从 deletedItems 还原的实例在增量查询响应中显示为新创建的实例。

注意

如果某个实体在特定条件下多次更改，则单个实体可以在响应中多次包含。 增量查询可以使应用程序列出所有更改，但不能确保实体在单个响应中是统一的。

支持的资源

目前，以下资源支持 delta 查询。 如前所述，v1.0 中提供的某些资源具有其相应的 增量 函数仍处于预览状态。

注意：标有星号 (*) 的资源的 delta 函数仅在终结点上 /beta 可用。

资源集合 API
application 应用程序：delta 函数
administrativeUnit administrativeUnit：delta 函数
callRecording * callRecording：delta 函数
callTranscript * callTranscript：delta 函数
chatMessage chatMessage：delta 函数
设备 device：delta 函数
directoryRole directoryRole：delta 函数
directoryObject directoryObject：delta 函数
driveItem1 driveItem：delta 函数
educationAssignment educationAssignment：delta 函数
educationCategory educationCategory： delta 函数
educationClass educationClass：delta 函数
educationSchool educationSchool：delta 函数
educationUser educationUser： delta 函数
事件 event：delta 函数
组 组：delta 函数
listItem1 listItem：delta 函数
mailFolder mailFolder：delta 函数
邮件 message： delta 函数
orgContact orgContact： delta 函数
oAuth2PermissionGrant oAuth2PermissionGrant： delta 函数
contactFolder contactFolder：delta 函数
联系人 资源 contact： delta 函数
plannerBucket * plannerBucket： delta 函数
plannerUser2 plannerUser：delta 函数
sites 站点资源的 delta 函数
servicePrincipal servicePrincipal： delta 函数
todoTask todoTask： delta 函数
todoTaskList todoTaskList： delta 函数
user user：delta 函数

注意

1 OneDrive 和 SharePoint 资源的使用模式与其他受支持的资源相似，但语法存在一些细微差异。 有关当前语法的详细信息，请参阅 driveItem： delta 和 listItem： delta。

2 Planner 资源的使用模式与其他受支持的资源类似，但存在一些差异。 有关详细信息，请参阅 planner： delta。

国家云

支持的资源增量查询适用于由世纪互联运营的公有云、Microsoft Cloud for US Government和 Microsoft 云中国托管的客户。

限制

不会跟踪main数据存储外部存储的属性的更改

某些资源包含存储在资源main数据存储外部的属性。 例如，用户资源数据主要存储在 Microsoft Entra ID 中，但其某些属性（如技能）存储在 SharePoint Online 中。 目前，只有存储在 main 数据存储中的属性会触发增量查询中的更改;main数据存储外部存储的属性不支持作为更改跟踪的一部分。 因此，更改这些属性中的任何一个都不会导致对象显示在增量查询响应中。

有关存储在 main 数据存储外部的属性的详细信息，请参阅用户和组文档。

处理延迟

在资源实例更改的时间与跟踪的更改反映在增量查询响应中的时间之间，预计会有不同的延迟。

有时，由于复制延迟，在选择 @odata.nextLink 或 @odata.deltaLink时，对 对象的更改可能不会立即显示。 请在一段时间后重试 @odata.nextLink 或 @odata.deltaLink 以检索最新更改。

重新发送

应用程序必须为重播做好准备，重新发送是在后续响应中出现相同更改时发生的。 虽然增量查询会尽最大努力减少重播，但仍有可能。

同步重置

Delta 查询可以返回一个410 Gone响应代码和一个 Location 标头，其中包含一个空的$deltatoken请求 URL（与初始查询相同）。 此状态通常会发生，以防止由于目标租户的内部维护或迁移而导致数据不一致，并指示应用程序必须重新启动，且目标租户的完全同步。

令牌持续时间

增量令牌仅在客户端应用程序需要再次运行完整同步前的特定时间段内有效。

  • 目录对象的时限为 7 天内。
  • 教育对象（educationSchool、educationUser 和 educationClass）的时限为 7 天内。
  • 对于 (邮件、 mailFolder、 event、 contact、 contactFolder、 todoTask 和 todoTaskList) 的 Outlook 实体，上限不是固定的;它取决于内部增量令牌缓存的大小。 因为缓存中不断添加新 delta 令牌，因此超过缓存容量后，旧 delta 令牌将被删除。

如果令牌过期，服务应响应带有错误代码的 40X 系列错误，例如 syncStateNotFound。 有关详细信息，请参阅 Microsoft Graph 中的错误代码。

合并增量查询和更改通知

应用可以使用 Microsoft Graph 更改通知 来订阅在特定资源发生更改时收到通知。 然后，应用程序可使用 delta 查询来请求自上次请求以来的所有更改。

应用程序可以使用此策略几乎消除仅针对受支持资源 () 需要频繁轮询 Microsoft Graph 并处理这些更改以使本地数据存储保持同步，从而大大降低其请求被限制的机会。

相关内容

在以下教程中详细了解增量查询：