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
Делегированное (личная учетная запись Майкрософт)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

Чтобы начать отслеживать изменения, выполните запрос к ресурсу users, включающий функцию delta.To begin tracking changes, you make a request including the delta function on the users resource.

GET /users/delta

Параметры запросаQuery parameters

Отслеживание изменений в ресурсе users — это цикл из одного или нескольких вызовов функции 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 автоматически кодирует указанные параметры в маркере, входящем в состав URL-адреса nextLink или deltaLink, включенного в отклик.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.

Копируйте и применяйте URL-адрес nextLink или deltaLink из предыдущего ответа в последующих запросах, так как в нем уже содержаться закодированные параметры.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 Этот маркер состояния возвращается в URL-адресе deltaLink предыдущего вызова функции delta для той же коллекции пользователей и указывает на завершение этого цикла отслеживания изменений. Сохраните URL-адрес deltaLink с этим маркером и примените его в первом запросе следующего цикла отслеживания изменений для этой коллекции.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 строкаstring Этот маркер состояния возвращается в URL-адресе nextLink предыдущего вызова функции delta и указывает, что в коллекции пользователей остаются неотслеженные изменения.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.

Параметры запросов ODataOData query parameters

Этот метод поддерживает необязательные параметры запросов OData для настройки отклика.This method supports optional OData Query Parameters to help customize the response.

  • Вы можете использовать параметр запроса $select так же, как в любом другом запросе GET, чтобы задать только те свойства, которые необходимы для эффективной работы. Свойство 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>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 и объект коллекции user в тексте отклика.If successful, this method returns 200 OK response code and user collection object in the response body. Оклик также содержит URL-адрес nextLink или deltaLink.The response also includes a nextLink URL or a deltaLink URL.

  • Если возвращается URL-адрес nextLink:If a nextLink URL is returned:

    • Это означает, что во время сеанса получены не все страницы данных.This indicates there are additional pages of data to be retrieved in the session. Приложение продолжает отправлять запросы, используя URL-адрес nextLink, пока в отклик не будет включен URL-адрес deltaLink.The application continues making requests using the nextLink URL until a deltaLink URL is included in the response.
    • Отклик включает тот же набор свойств, что и начальный разностный запрос.The response includes the same set of properties as in the initial delta query request. Это позволяет фиксировать полное текущее состояние объектов при запуске разностного цикла.This allows you to capture the full current state of the objects when initiating the delta cycle.
  • Если возвращается URL-адрес deltaLink:If a deltaLink URL is returned:

    • Это означает, что больше нет данных о текущем состоянии ресурса.This indicates there is no more data about the existing state of the resource to be returned. Сохраните и используйте URL-адрес deltaLink, чтобы узнавать об изменениях ресурса в следующем цикле.Save and use the deltaLink URL to learn about changes to the resource in the next round.
    • Вы можете указать заголовок Prefer:return=minimal, чтобы включить в значения отклика только свойства, измененные с момента создания deltaLink.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.

По умолчанию: возвращение свойств, совпадающих с начальным разностным запросомDefault: return the same properties as initial delta request

По умолчанию запросы с использованием deltaLink или nextLink возвращают те же свойства, которые выбраны в начальном разностном запросе, следующим образом: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. Кроме того, разностные отклики отличаются большими размерами, так как они содержат все значения свойств, как показано в примере 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.)

Примечание. Заголовок можно добавить в запрос deltaLink в любой момент разностного цикла.Note: The header can be added to a deltaLink request at any point in time in the delta cycle. Заголовок влияет только на набор свойств, включенный в отклик, и не влияет на способ выполнения разностного запроса.The header only affects the set of properties included in the response and it does not affect how the delta query is executed. См. пример 3.See 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 не включено, то есть оно не изменилось с последнего разностного запроса; displayName и jobTitle включены, то есть их значения изменились.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