Microsoft Graph中的增量查询,可用于查询支持的资源的添加、删除或更新。 它通过一系列 增量 请求启用。 对于组,增量查询使你可以发现更改,而无需提取整组来比较更改。
以后,对本地配置文件存储使用同步组功能的客户端可以将增量查询用于初始完全同步和后续增量同步。通常,客户会对租户中的所有组进行初始完全同步,之后定期获取对组的增量更改。
跟踪对组的更改
使用 增量 函数通过一个或多个 GET 请求跟踪组更改。 GET 请求类似于 列表组 请求,但 URL 中包含以下额外对象除外:
- delta 函数。
- 上一个 GET delta 函数调用的 状态令牌(deltaToken 或 skipToken)。
示例:跟踪组更改
下面的示例演示了一系列跟踪组更改的请求:
在响应中记下以下内容:
- 删除组(Microsoft 365组)时,项包含批注:
@removed值为"reason": "changed"。 - 永久删除组(安全组或 永久删除Microsoft 365组)时,项将包含一个批注:
@removed值为"reason": "deleted"。 - 创建或还原组时,没有批注。
初始请求
若要跟踪组资源中的更改,请发出请求,并将 增量 函数作为 URL 段。
记下以下各项:
- 请求中包含可选的
$select查询参数,以演示如何在以后的请求中自动包含查询参数。 - 可选的
$select查询参数还用于显示如何一起检索组成员和组对象。 这允许跟踪成员身份变更,例如当用户被添加到组或从组中删除时。 - 初始请求不包括状态令牌。状态令牌将用于后续请求中。
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members
初始响应
如果成功,此方法在响应正文中返回 200 OK 响应代码和组集合对象。 如果整个组集过大而无法适应一个响应,那么还将包括一个包含状态令牌的 @odata.nextLink。
此示例中包含 @odata.nextLink;原始 $select 查询参数则在状态令牌中进行了编码。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups(displayName,description)",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
"value": [
{
"displayName":"All Company",
"description":"This is the default group for everyone in the network",
"id":"c2f798fd-f95d-4623-8824-63aec21fffff",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "693acd06-2877-4339-8ade-b704261fe7a0"
},
{
"@odata.type": "#microsoft.graph.user",
"id": "49320844-be99-4164-8167-87ff5d047ace"
}
]
},
{
"displayName":"sg-HR",
"description":"All HR personnel",
"id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
}
]
}
Note:
members@delta属性包含在第一个组对象(所有公司)中,并且包含该组的两个当前成员。 sg-HR 不包含该属性,因为该组没有任何成员。
nextLink 请求
第二个请求使用上一个响应中的 @odata.nextLink,其中包含 skipToken。 请注意,$select参数在编码并包含在令牌中时并不明显存在。
GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ
nextLink 响应
响应包含另一个@odata.nextLink,其中有一个新的skipToken值,这表示为组跟踪的更多更改可用。 在更多请求中使用 @odata.nextLink URL,直到在最终响应中返回@odata.deltaLink URL(在 @odata.deltaLink 参数中)。 即使值为空数组也是如此。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
"value": [
{
"displayName":"Mark 8 Project Team",
"description":"Mark 8 Project Team",
"id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "632f6bb2-3ec8-4c1f-9073-0027a8c68593"
}
]
},
{
"displayName":"Sales and Marketing",
"description":"Sales and Marketing",
"id":"421e797f-9406-4934-b778-4908421e3505",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "3c8ac7c4-d365-4df9-abfa-356a9dd7763c"
},
{
"@odata.type": "#microsoft.graph.user",
"id": "49320844-be99-4164-8167-87ff5d047ace"
}
]
}
]
}
最终 nextLink 请求
第三个请求使用上次同步请求返回的最新 @odata.nextLink。
GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7
最终 nextLink 响应
当返回 @odata.deltaLink URL 时,不再返回关于组对象现有状态的数据。为了执行以后的请求,应用程序使用 @odata.deltaLink URL 了解组的其他更改。保存 deltaToken,并在后续请求 URL 中使用它来发现组的更多更改。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
"@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
"value": [
{
"displayName":"All Employees",
"id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
},
{
"displayName":"Remote living",
"description":"Remote living",
"id":"421e797f-9406-ffff-b778-4908421e3505"
}
]
}
deltaLink 请求
使用上次响应中的@odata.deltaLink,你将收到自上次请求以来组的更改(添加、删除或更新)。更改包括:
- 新创建的组对象。
- 已删除的组对象。
- 已更改属性的组对象(例如,已修改 displayName )。
- 已为其添加或移除成员对象的组对象。
GET https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw
deltaLink 响应
如果未发生任何更改,则返回 @odata.deltaLink 而不返回结果 - 值 属性为空数组。 请确保将应用程序中的以前链接替换为新链接以便在日后调用中使用。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
"@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
"value": []
}
如果发生更改,则包含已更改组的集合。 响应还包含 @odata.nextLink 或 @odata.deltaLink(如果要检索多个更改页面)。 实现遵循 @odata.nextLink 的相同模式,并为将来的调用保留最终 @odata.deltaLink。
Note: 此请求可能对最近创建、更新或删除的组具有复制延迟。 请在一段时间后重试
@odata.nextLink或@odata.deltaLink以检索最新更改。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
"@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
"value": [
{
"displayName": "TestGroup3",
"description": "A test group for change tracking",
"id": "2e5807ce-58f3-4a94-9b37-ffff2e085957",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
"@removed": {
"reason": "deleted"
}
},
{
"@odata.type": "#microsoft.graph.user",
"id": "37de1ae3-408f-4702-8636-20824abda004"
}
]
}
]
}
上一个示例响应的一些注意事项如下:
-
这些对象连同一组相同的属性一起返回,这些属性最初通过
$select查询参数指定。 -
同时包括已更改和未更改的属性。在上述示例中,
description属性具有新值,而displayName属性未发生更改。 -
members@delta包含对组成员身份的以下更改。-
列表中的第一个用户已经从组中删除 - 要么删除成员身份,要么删除用户对象本身。
@removed属性对此进行了说明。 只有被永久删除的用户才会从组中删除。 已临时删除的用户保留其组成员身份,并且在永久删除之前不会出现在增量结果中。 有关详细信息,请参阅目录(已删除的项)。 -
第二个用户已添加到组。
-
逐页查看大型组中的成员
默认情况下,当未指定$select查询参数或显式指定$select=members参数时,members@delta 属性包含在组对象中。 对于具有多个成员的组,可能所有成员都无法适应单个响应。 实现以下模式来处理此类情况。
Note: 此模式既适用于组状态的初始检索,也适用于获取增量更改的后续调用。
假设运行以下增量查询 - 捕获组的初始完整状态,或稍后获取增量更改:
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members
- Microsoft Graph 可能返回一个仅包含一个组对象的响应,其中
members@delta属性中有一个大型成员列表:
第一页
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
"value": [
{
"displayName":"LargeGroup",
"description":"A group containing thousands of users",
"id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
"@removed": {
"reason": "deleted"
}
},
{
"@odata.type": "#microsoft.graph.user",
"id": "37de1ae3-408f-4702-8636-20824abda004"
},
<...more users here...>
]
}
<...no more groups included - this group filled out the entire response...>
]
}
- 遵循
@odata.nextLink时,可能会收到包含同一组对象的响应。 将返回相同的属性值,但members@delta属性现在包含不同的用户列表。
第二页
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
"value": [
{
"displayName":"LargeGroup",
"description":"A group containing thousands of users",
"id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "c08a463b-7b8a-40a4-aa31-f9bf690b9551",
"@removed": {
"reason": "deleted"
}
},
{
"@odata.type": "#microsoft.graph.user",
"id": "23423fa6-821e-44b2-aae4-d039d33884c2"
},
<...more users here...>
]
}
<...no more groups included - this group filled out the entire response...>
]
}
- 最终,将以此方式返回整个成员列表,并且其他组将开始在响应中显示。
建议使用以下最佳做法来正确处理此模式:
- 始终按照
@odata.nextLink操作,并在本地合并每个组的状态:当收到与同一个组相关的响应时,使用它们在应用程序中构建完整的成员身份列表。 - 不要假定特定的响应序列。假设同一组可以显示在
@odata.nextLink序列的任意位置,并以合并逻辑进行处理。
另请参阅
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 Jumaodhiss)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
