user: deltauser: delta

命名空间:microsoft.graphNamespace: microsoft.graph

获得新建、更新或删除的用户,无需对整个用户集合执行完整读取。Get newly created, updated, or deleted users without having to perform a full read of the entire user collection. 有关详细信息,请参阅更改跟踪See change tracking for details.

权限Permissions

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) User.Read、User.ReadWrite、User.ReadBasic.All、User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All、Directory.AccessAsUser.AllUser.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) 不支持。Not supported.
应用程序Application User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.AllUser.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

HTTP 请求HTTP request

为开始跟踪更改,请在用户资源上发出包含 delta 函数的请求。To begin tracking changes, you make a request including the delta function on the users resource.

GET /users/delta

查询参数Query parameters

跟踪用户更改会引发一组对 delta 函数的一次或多次调用。Tracking changes in users incurs a round of one or more delta function calls. 如果要使用任意查询参数($deltatoken$skiptoken 除外),则必须在最初的 delta 请求中指定它。If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. Microsoft Graph 自动将指定的任意参数编码为响应中提供的 nextLinkdeltaLink URL 的令牌部分。Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response.

只需预先指定所需的任何查询参数一次。You only need to specify any desired query parameters once upfront.

在后续请求中,可以复制并应用之前响应中返回的 nextLinkdeltaLink URL,因为此 URL 已包含所需的编码参数。In subsequent requests, copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded, desired parameters.

查询参数Query parameter 类型Type 说明Description
$deltatoken$deltatoken stringstring 对同一个用户集合之前的 delta 函数调用的 deltaLink URL 中返回的状态令牌,指示该组更改跟踪的完成状态。将此令牌包含在对该集合的下一组更改追踪的首次请求中,并保存和应用整个 deltaLink URL。A state token returned in the deltaLink URL of the previous delta function call for the same user collection, indicating the completion of that round of change tracking. Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that collection.
$skiptoken$skiptoken stringstring 对之前的 delta 函数调用的 nextLink URL 中返回的状态令牌,指示同一个用户集合中有进一步的更改需要追踪。A state token returned in the nextLink URL of the previous delta function call, indicating there are further changes to be tracked in the same user collection.

OData 查询参数OData query parameters

此方法支持可选 OData 查询参数来帮助自定义响应。This method supports optional OData Query Parameters to help customize the response.

  • 像在任何 GET 请求中一样,你可以使用 $select 查询参数以仅指定获取最佳性能所需的属性。始终返回 id 属性。You can use a $select query parameter as in any GET request to specify only the properties your need for best performance. The id property is always returned.
  • 提供对 $filter 的有限支持:There is limited support for $filter:
    • 唯一支持的 $filter 表达式用于跟踪对特定对象 $filter=id+eq+{value} 的更改。The only supported $filter expression is for tracking changes on a specific object: $filter=id+eq+{value}. 可以筛选多个对象。You can filter multiple objects. 例如,https://graph.microsoft.com/v1.0/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'For example, https://graph.microsoft.com/v1.0/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'. 筛选对象不能超出 50 个。There is a limit of 50 filtered objects.

请求标头Request headers

名称Name 说明Description
AuthorizationAuthorization 持有者<令牌>Bearer <token>
Content-TypeContent-Type application/jsonapplication/json
PreferPrefer return=minimalreturn=minimal

在使用 deltaLink 的请求中执行此标头将仅返回自上一轮之后发生更改的对象属性。Specifying this header with a request that uses a deltaLink would return only the object properties that have changed since the last round. 可选。Optional.

请求正文Request body

请勿提供此方法的请求正文。Do not supply a request body for this method.

响应Response

如果成功,此方法的响应正文返回200 OK响应代码和用户集合对象。If successful, this method returns 200 OK response code and user collection object in the response body. 该响应还包括 nextLinkURL 或 deltaLinkURL。The response also includes a nextLink URL or a deltaLink URL.

  • 如果返回 nextLinkURL:If a nextLink URL is returned:

    • 这表示绘画中存在要检索的其他数据页面。This indicates there are additional pages of data to be retrieved in the session. 应用程序继续使用 nextLink URL 发出请求,直到响应中包含 deltaLink URL。The application continues making requests using the nextLink URL until a deltaLink URL is included in the response.
    • 响应包含与初始 Delta 查询请求相同的属性集。The response includes the same set of properties as in the initial delta query request. 这使你能够在发起 Delta 循环时捕获对象当前的完整状态。This allows you to capture the full current state of the objects when initiating the delta cycle.
  • 如果返回 deltaLinkURL:If a deltaLink URL is returned:

    • 这表示未返回关于资源现有状态的更多数据。This indicates there is no more data about the existing state of the resource to be returned. 保存并使用 deltaLink URL 来了解下一轮资源更改。Save and use the deltaLink URL to learn about changes to the resource in the next round.
    • 只有对于在签发 deltaLink 之后更改的属性,你才可以选择指定 Prefer:return=minimal 标头以包含在响应值中。You have a choice to specify the Prefer:return=minimal header, to include in the response values for only the properties that have changed since the time the deltaLink was issued.

默认:返回与初始 Delta 请求相同的属性Default: return the same properties as initial delta request

默认情况下,使用 deltaLinknextLink 的请求将通过以下方式返回与初始 Delta 查询中选择的相同属性:By default, requests using a deltaLink or nextLink return the same properties as selected in the initial delta query in the following ways:

  • 如果属性已更改,则新值将包括在响应中。If the property has changed, the new value is included in the response. 这包括设为 Null 值的属性。This includes properties being set to null value.
  • 如果属性未更改,则旧值将包括在响应中。If the property has not changed, the old value is included in the response.
  • 如果之前从未设置属性,则它不会包括在响应中。If the property has never been set before it will not be included in the response at all.

注意: 如果出现此行为,那么通过查看响应无法区分属性是否已更改。Note: With this behavior, by looking at the response it is not possible to tell whether a property is changing or not. 此外,Delta 响应往往过大,因为它们包含所有属性值,如示例 2 所示。Also, the delta responses tend to be large because they contain all property values - as shown in Example 2.

备用:仅返回更改的属性Alternative: return only the changed properties

添加可选请求标头 - prefer:return=minimal - 将导致出现以下行为:Adding an optional request header - prefer:return=minimal - results in the following behavior:

  • 如果属性已更改,则新值将包括在响应中。If the property has changed, the new value is included in the response. 这包括设为 Null 值的属性。This includes properties being set to null value.
  • 如果属性未更改,则该属性不会包括在响应中。If the property has not changed, the property is not included in the response at all. (不同于默认行为。)(Different from the default behavior.)

注意: 可以在 Delta 循环中的任何时间点将标头添加到 deltaLink 请求中。Note: The header can be added to a deltaLink request at any point in time in the delta cycle. 标头仅影响响应中包含的属性集,它不会影响执行 Delta 查询的方式。The header only affects the set of properties included in the response and it does not affect how the delta query is executed. 请参阅示例 3See Example 3.

示例Examples

示例 1:默认属性Example 1: Default properties

请求Request

下面展示了示例请求。The following is an example of the request. 没有 $select 参数,因为将跟踪并返回默认的属性集。There is no $select parameter, so a default set of properties is tracked and returned.

GET https://graph.microsoft.com/v1.0/users/delta

响应Response

以下示例所示为使用从查询初始化获得的 deltaLink 时的响应。The following is an example of the response when using deltaLink obtained from the query initialization.

注意: 为了提高可读性,可能缩短了此处显示的响应对象。所有属性都将通过实际调用返回。Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "businessPhones": [
          "businessPhones-value"
      ],
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "jobTitle": "jobTitle-value",
      "mail": "mail-value",
      "mobilePhone": "mobilePhone-value",
      "officeLocation": "officeLocation-value",
      "preferredLanguage": "preferredLanguage-value",
      "surname": "surname-value",
      "userPrincipalName": "userPrincipalName-value",
      "id": "id-value"
    }
  ]
}

示例 2:选择三个属性Example 2: Selecting three properties

请求Request

下一个示例所示为通过默认响应行为选择三种更改跟踪属性时的初始请求。The next example shows the initial request selecting three properties for change tracking, with default response behavior.

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

响应Response

以下示例所示为使用从查询初始化获得的 deltaLink 时的响应。The following is an example of the response when using deltaLink obtained from the query initialization. 请注意,所有三种属性将包括在响应中,并且无法知道在获得 deltaLink 之后哪些属性发生了更改。Note that all three properties are included in the response and it is not known which ones have changed since the deltaLink was obtained.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": "jobTitle-value",
      "mobilePhone": null
    }
  ]
}

示例 3:备用最小响应行为Example 3: Alternative minimal response behavior

请求Request

下一个示例所示为通过备用最小响应行为选择三种更改跟踪属性时的初始请求。The next example shows the initial request selecting three properties for change tracking, with alternative minimal response behavior.

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

响应Response

以下示例所示为使用从查询初始化获得的 deltaLink 时的响应。The following is an example of the response when using deltaLink obtained from the query initialization. 请注意,mobilePhone 属性不包括在内,这意味着它在上一轮 Delta 查询之后未发生更改;并且 displayNamejobTitle 将包括在内,这意味着其值已发生更改。Note that the mobilePhone property is not included, which means it has not changed since the last delta query; displayName and jobTitle are included which means their values have changed.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": null
    }
  ]
}

另请参阅See also