使用增量查询跟踪 Microsoft Graph 数据更改
Delta 查询(也称为 更改跟踪)使应用程序能够发现新创建、更新或删除的实体,而无需对每个请求执行目标资源的完全读取。 Microsoft Graph 应用程序可以使用 delta 查询和本地数据存储高效地同步更改。
使用增量查询有助于避免不断轮询Microsoft Graph,因为应用仅请求自上次请求以来更改的数据。 此模式允许应用程序减少请求的数据量,从而降低请求成本,因此可能会限制请求 被限制的可能性。
通常的调用模式如下:
应用程序在所需资源上使用 delta 函数发出 GET 请求。 例如,
GET https://graph.microsoft.com/v1.0/users/delta
。提示
/delta
是完全限定名称/microsoft.graph.delta
的快捷方式。 Microsoft Graph SDK 生成的请求使用完全限定的名称。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 响应包括 集合中当前 存在的资源。 不会返回在初始增量查询之前删除的资源。 初始请求前进行的更新在返回的资源上按其最新状态进行汇总。
当应用程序需要了解对资源的更改时,它会使用
@odata.deltaLink
在步骤 2 中收到的 URL 发出请求。 应用程序可以在完成步骤 2 后或检查更改时立即发出此请求。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 查询响应中,使用标准表示形式表示受支持资源的新建实例。
更新的实例由其 ID 表示 ,至少具有 更新的属性,但可能包括其他属性。
用户和组的关系表示为标准资源表示形式的注释。 这些批注使用 格式propertyName@delta。 批注包含在初始增量查询请求的响应中。
- 在更改跟踪过程中,不支持对存储在主数据存储外部的关系进行更改。 有关详细信息,请参阅 不跟踪主数据存储外部存储的属性的更改。
已删除的实例由其 ID 和 @removed 对象表示。 @removed 对象可能包含有关删除实例的原因的其他信息。 例如,
"@removed": {"reason": "changed"}
。 可能的 @removed 原因可以是changed
或deleted
。changed
表示该项已被删除,可以从 deletedItems 恢复。deleted
指示项目已删除且无法还原。-
从 deletedItems 存储中删除的项也显示为
deleted
。
可以在初始增量查询响应中和跟踪 ()
@odata.nextLink
响应中返回@removed对象。 例如,仍可从已删除的项还原的已删除目录对象显示为"@removed": {"reason": "changed"}
。 使用增量查询请求的客户端应设计为处理响应中的这些对象。-
从 deletedItems 存储中删除的项也显示为
从 deletedItems 还原的实例在增量查询响应中显示为新创建的实例。
备注
如果某个实体在特定条件下多次更改,则单个实体可以在响应中多次包含。 增量查询可以使应用程序列出所有更改,但不能确保实体在单个响应中是统一的。
目前,以下资源支持 delta 查询。 如前所述,v1.0 中提供的某些资源具有其相应的 增量 函数仍处于预览状态。
注意:标有星号 (*) 的资源的 delta 函数仅在终结点上
/beta
可用。
备注
1 OneDrive 和 SharePoint 资源的使用模式与其他受支持的资源相似,但语法存在一些细微差异。 有关当前语法的详细信息,请参阅 driveItem: delta 和 listItem: delta。
2 Planner 资源的使用模式与其他受支持的资源相似,但存在一些差异。 有关详细信息,请参阅 planner: delta。
支持的资源增量查询适用于托管在公有云、美国政府Microsoft云以及由世纪互联运营的 Microsoft 云中国的客户。
某些资源包含存储在资源的主数据存储外部的属性。 例如, 用户 资源数据主要存储在 Microsoft Entra ID 中,但其某些属性(如 技能)存储在 SharePoint Online 中。 目前,只有存储在主数据存储中的属性才会触发增量查询中的更改;不支持在主数据存储区外部存储的属性作为更改跟踪的一部分。 因此,更改这些属性中的任何一个都不会导致对象显示在增量查询响应中。
有关存储在主数据存储外部的属性的详细信息,请参阅 用户 和 组 文档。
在资源实例更改的时间与跟踪的更改反映在增量查询响应中的时间之间,预计会有不同的延迟。
有时,由于复制延迟,在选择 @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 并处理这些更改以使本地数据存储保持同步,从而大大降低其请求被限制的机会。
在以下教程中详细了解增量查询: