user: delta

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

获得新建、更新或删除的用户，无需对整个用户集合执行完整读取。 有关详细信息，请参阅更改跟踪。

注意

当前不会跟踪对 licenseAssignmentStates 属性的更改。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） User.Read.All Directory.Read.All、Directory.ReadWrite.All、User.ReadWrite.All
委派（个人 Microsoft 帐户） 不支持。 不支持。
Application User.Read.All Directory.Read.All、Directory.ReadWrite.All、User.ReadWrite.All

HTTP 请求

为开始跟踪更改，请在用户资源上发出包含 delta 函数的请求。

GET /users/delta

查询参数

跟踪用户更改会引发一组对 delta 函数的一次或多次调用。 如果要使用任意查询参数（$deltatoken 和 $skiptoken 除外），则必须在最初的 delta 请求中指定它。 Microsoft Graph 自动将指定的任意参数编码为响应中提供的 @odata.nextLink 或 @odata.deltaLink URL 的令牌部分。

只需预先指定所需的任何查询参数一次。

在后续请求中，可以复制并应用之前响应中返回的 @odata.nextLink 或 @odata.deltaLink URL，因为此 URL 已包含所需的编码参数。

查询参数 类型 说明
$deltatoken string 在上一个 delta 函数的 URL 中@odata.deltaLink返回的状态令牌调用同一用户集合，指示完成这一轮更改跟踪。 将此令牌包含在对该集合的下一组更改追踪的首次请求中，并保存和应用整个 @odata.deltaLink URL。
$skiptoken string 对之前的 delta 函数调用的 @odata.nextLink URL 中返回的状态令牌，指示同一个用户集合中有进一步的更改需要追踪。

OData 查询参数

此方法支持可选 OData 查询参数来帮助自定义响应。

  • 像在任何 GET 请求中一样，你可以使用 $select 查询参数以仅指定获取最佳性能所需的属性。 始终返回 id 属性。
  • 对 的支持有限 $filter：
    • 唯一支持的 $filter 表达式用于跟踪对特定对象 $filter=id+eq+{value} 的更改。 可以筛选多个对象。 例如，https://graph.microsoft.com/beta/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'。 筛选对象限制为 50 个。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json
Prefer return=minimal

在使用 @odata.deltaLink 的请求中执行此标头将仅返回自上一轮之后发生更改的对象属性。 可选。

请求正文

请勿提供此方法的请求正文。

响应

如果成功，此方法的响应正文返回200 OK响应代码和用户集合对象。 该响应还包括 @odata.nextLinkURL 或 @odata.deltaLinkURL。

  • 如果返回 @odata.nextLinkURL：

    • 这表示绘画中存在要检索的其他数据页面。 应用程序继续使用 @odata.nextLink URL 发出请求，直到响应中包含 @odata.deltaLink URL。
    • 响应包含与初始 Delta 查询请求相同的属性集。 这使你能够在发起 Delta 循环时捕获对象当前的完整状态。

  • 如果返回 @odata.deltaLinkURL：

    • 这表示没有关于要返回的资源现有状态的更多数据。 保存并使用 @odata.deltaLink URL 来了解下一轮资源更改。
    • 只有对于在签发 @odata.deltaLink 之后更改的属性，你才可以选择指定 Prefer:return=minimal 标头以包含在响应值中。

默认：返回与初始 Delta 请求相同的属性

默认情况下，使用 @odata.deltaLink 或 @odata.nextLink 的请求将通过以下方式返回与初始 Delta 查询中选择的相同属性：

  • 如果属性已更改，则新值将包括在响应中。 这包括设为 Null 值的属性。
  • 如果属性未更改，则响应中包含旧值。
  • 如果之前从未设置属性，则它不会包括在响应中。

注意：如果出现此行为，那么通过查看响应无法区分属性是否已更改。 此外，增量响应往往很大，因为它们包含所有属性值 - 如 示例 2 所示。

备用：仅返回更改的属性

添加可选请求标头 - prefer:return=minimal - 将导致出现以下行为：

  • 如果属性已更改，则新值将包括在响应中。 这包括设为 Null 值的属性。
  • 如果属性未更改，则响应中根本不包含该属性。 （不同于默认行为。）

注意：可以在 Delta 循环中的任何时间点将标头添加到 @odata.deltaLink 请求中。 标头仅影响响应中包含的属性集，它不会影响执行 Delta 查询的方式。 请参阅示例 3。

示例

示例 1：默认属性

请求

以下示例显示了一个请求。 没有 $select 参数，因此会跟踪并返回一组默认的属性。

GET https://graph.microsoft.com/beta/users/delta

响应

下面是使用 @odata.deltaLink 从查询初始化中获取的 响应的示例。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/beta/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "businessPhones": [
          "+1 425 555 0109"
      ],
      "displayName": "Adele Vance",
      "givenName": "Adele",
      "jobTitle": "Retail Manager",
      "mail": "AdeleV@contoso.com",
      "mobilePhone": "+1 425 555 0109",
      "officeLocation": "18/2111",
      "preferredLanguage": "en-US",
      "surname": "Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

示例 2：选择三个属性

请求

下一个示例所示为通过默认响应行为选择三种更改跟踪属性时的初始请求。

GET https://graph.microsoft.com/beta/users/delta?$select=displayName,jobTitle,mobilePhone

响应

下面是使用 @odata.deltaLink 从查询初始化中获取的 响应的示例。 所有这三个属性都包含在响应中，并且不知道自获取 后 @odata.deltaLink 哪些属性已更改。

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/beta/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "Adele Vance",
      "jobTitle": "Retail Manager",
      "mobilePhone": "+1 425 555 0109"
    }
  ]
}

示例 3：备用最小响应行为

请求

下一个示例所示为通过备用最小响应行为选择三种更改跟踪属性时的初始请求。

GET https://graph.microsoft.com/beta/users/delta?$select=displayName,jobTitle,mobilePhone
Prefer: return=minimal

响应

下面是使用 @odata.deltaLink 从查询初始化中获取的 响应的示例。 属性 mobilePhone 未包含在内，这意味着它自上次增量查询以来没有更改; displayName 并且 jobTitle 包含此属性意味着其值已更改。

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/beta/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "Vance Adele",
      "jobTitle": "Product Marketing Manager"
    }
  ]
}

相关内容