使用英语阅读

通过


获取用户的增量更改

Microsoft Graph 中的增量查询允许通过一系列增量请求查询对受支持资源的添加、删除或更新。 对于用户,增量查询使你可以发现更改,而无需提取用户组来比较更改。

将用户与本地配置文件存储同步的客户端可以使用增量查询进行初始完全同步以及后续增量同步。 通常,客户端对租户中的所有用户执行初始完全同步,然后定期获取对用户的增量更改。

获取对用户的更改

使用 增量 函数通过一个或多个 GET 请求跟踪用户更改。 GET 请求具有以下特征:

  • 在 URL 路径前面附加的 delta 函数。
  • 状态令牌 (上一个 GET delta 函数调用中的 deltatokenskipToken) 。
  • [可选]任何支持的查询参数

示例

本文介绍一系列用于跟踪用户更改的示例请求:

  1. 初始请求响应
  2. nextLink 请求响应
  3. 最终的 nextLink 请求响应
  4. deltaLink 请求deltaLink 响应

初始请求

若要跟踪用户资源中的更改,请发出请求,并将 增量 函数作为 URL 段。

提示

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

记下以下各项:

  • 请求中包含可选的 $select 查询参数,以演示如何在以后的请求中自动包含查询参数。 如果需要,必须在初始请求中指定查询参数。
    • 仅跟踪 包含的属性 $select 是否发生更改。 如果未 $select 指定 ,则会跟踪对象的所有属性以查找更改。
  • 初始请求不包括状态令牌。 状态令牌用于后续请求。
GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,givenName,surname

初始响应

如果成功,此方法的响应正文返回200 OK响应代码和用户集合对象。 假设整个用户集太大,则响应在参数中包含@odata.nextLink@odata.nextLink状态令牌。

本示例中,返回 @odata.nextLink URL,表示此会话存在要检索的更多数据页面。 $skiptoken请注意 URL 中的 。 初始请求的 $select 查询参数已编码为 @odata.nextLink URL。

响应还包含 @removed ID 86462606-fde0-4fc4-9e0c-a20eb73e54c6为 的用户的注释。 注释 @removed 是在以下方案中添加的:

  • 如果用户遭删除,项中包含注释:@removed 值为 "reason": "changed"
  • 永久删除用户时,项包含一个注释:@removed值为 "reason": "deleted"
  • 创建用户或从已删除项容器还原用户时,没有注释。
HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users(displayName,givenName,surname)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa",
  "value": [
    {
      "displayName":"Cameron White",
      "givenName":"Cameron",
      "surname":"White",
      "id":"ffff7b1a-13b6-477b-8c0c-380905cd99f7"
    },
    {
      "displayName":"Delia Dennis",
      "givenName":"Delia",
      "surname":"Dennis",
      "id":"605d1257-ffff-40b6-8e6f-528a53f5dc55"
    },
    {
      "id": "86462606-fde0-4fc4-9e0c-a20eb73e54c6",
      "@removed": {
        "reason": "deleted"
      }
    },
    {
      "displayName": "Conf Room Adams",
      "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
    }
  ]
}

第二个请求指定上一个响应中返回的 skipToken。 请注意,$select 参数已编码并包含在 skipToken 中。

GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa

响应包含另一个@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#users",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"Mallory Cortez",
      "givenName":"Mallory",
      "surname":"Cortez",
      "id":"d8c37826-ffff-4cae-b348-e2725b1e814b"
    },
    {
      "displayName":"Diego Sicilian",
      "givenName":"Diego",
      "surname":"Sicilian",
      "id":"8b1ee412-cd8f-4d59-ffff-24010edb9f1f"
    }
  ]
}

第三个请求使用上次同步请求返回的最新 skipToken

GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7

此响应包含一个 @odata.deltaLink URL,该 URL 指示没有关于用户对象现有状态的更多数据。 对于将来的请求,应用程序使用 @odata.deltaLink URL 了解用户的其他更改。 保存 deltatoken并在后续请求 URL 中使用它来发现对用户的更多更改。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460",
  "value": [
    {
      "displayName":"Lidia Holloway",
      "givenName":"Lidia",
      "surname":"Holloway",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "displayName":"Patti Fernandez",
      "givenName":"Patti",
      "surname":"Fernandez",
      "id":"f6ede700-27d0-4c42-bfb9-4dffff43c74a"
    }
  ]
}

deltatoken使用上次响应中的 ,可获取自上次请求以来向用户添加、删除或更新) (更改。

GET https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460

如果没有更改, @odata.deltaLink 则返回 不带结果的 - value 属性为空数组。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=MF1LuFYbK6Lw4DtZ4o9PDrcGekRP65WEJfDmM0H26l4v9zILCPFiPwSAAeRBghxgiwsXEfywcVQ9R8VEWuYAB50Yw3KvJ-8Z1zamVotGX2b_AHVS_Z-3b0NAtmGpod",
  "value": []
}

如果有更改,则包含已更改的用户对象的集合。 响应还包含 @odata.nextLink@odata.deltaLink(如果要检索多个更改页面)。 实现遵循 @odata.nextLink 的相同模式,并为将来的调用保留最终 @odata.deltaLink

备注

此请求可能对最近创建、更新或删除的组具有复制延迟。 请在一段时间后重试 @odata.nextLink@odata.deltaLink 以检索最新更改。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=MF1LuFYbK6Lw4DtZ4o9PDrcGekRP65WEJfDmM0H26l4v9zILCPFiPwSAAeRBghxgiwsXEfywcVQ9R8VEWuYAB50Yw3KvJ-8Z1zamVotGX2b_AHVS_Z-3b0NAtmGpod",
  "value": [
    {
      "displayName":"MOD Administrator",
      "givenName":"MOD",
      "surname":"Administrator",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "id":"8ffff70c-1c63-4860-b963-e34ec660931d",
      "@removed": {
         "reason": "changed"
      }
    }
  ]
}