user: delta

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Создавайте, обновляйте или удаляйте пользователей без необходимости полного чтения всей коллекции пользователей. Дополнительные сведения см. в статье Отслеживание изменений.

Примечание.

Изменения свойства licenseAssignmentStates сейчас не отслеживаются.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) User.Read.All Directory.Read.All, Directory.ReadWrite.All, User.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) Не поддерживается. Не поддерживается.
Для приложений User.Read.All Directory.Read.All, Directory.ReadWrite.All, User.ReadWrite.All

HTTP-запрос

Чтобы начать отслеживать изменения, выполните запрос к ресурсу users, включающий разностную функцию.

GET /users/delta

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

Отслеживание изменений в ресурсе users — это цикл из одного или нескольких вызовов функции delta. Если вы используете параметры запроса, отличные от $deltatoken и $skiptoken, их необходимо указать в начальном запросе delta. Microsoft Graph автоматически кодирует указанные параметры в маркере, входящем в состав URL-адреса @odata.nextLink или @odata.deltaLink, включенного в отклик.

Параметры запроса нужно указать только один раз в первом запросе.

Копируйте и применяйте URL-адрес @odata.nextLink или @odata.deltaLink из предыдущего ответа в последующих запросах, так как в нем уже содержаться закодированные параметры.

Параметр запроса Тип Описание
$deltatoken string Маркер состояния, возвращенный в @odata.deltaLink URL-адресе предыдущего вызова разностной функции для той же коллекции пользователей, что указывает на завершение этого цикла отслеживания изменений. Сохраните URL-адрес @odata.deltaLink с этим токеном и примените его в первом запросе следующего цикла отслеживания изменений для этой коллекции.
$skiptoken строка Этот маркер состояния возвращается в URL-адресе @odata.nextLink предыдущего вызова функции delta и указывает, что в коллекции пользователей остаются неотслеженные изменения.

Параметры запросов OData

Этот метод поддерживает необязательные параметры запросов OData для настройки отклика.

  • Вы можете использовать параметр запроса $select так же, как в любом другом запросе GET, чтобы задать только те свойства, которые необходимы для эффективной работы. Свойство 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 отфильтрованных объектов.

Заголовки запросов

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/json
Prefer return=minimal

Указание этого заголовка с запросом, использующим параметр @odata.deltaLink, приведет к возвращению только свойств объекта, измененных с момента последнего цикла. Необязательно.

Текст запроса

Не указывайте текст запроса для этого метода.

Отклик

В случае успеха этот метод возвращает код отклика 200 OK и объект коллекции user в тексте отклика. Оклик также содержит URL-адрес @odata.nextLink или @odata.deltaLink.

  • Если возвращается URL-адрес @odata.nextLink:

    • Это означает, что во время сеанса получены не все страницы данных. Приложение продолжает отправлять запросы, используя URL-адрес @odata.nextLink, пока в отклик не будет включен URL-адрес @odata.deltaLink.
    • Отклик включает тот же набор свойств, что и начальный разностный запрос. Это позволяет фиксировать полное текущее состояние объектов при запуске разностного цикла.

  • Если возвращается URL-адрес @odata.deltaLink:

    • Это означает, что больше нет данных о существующем состоянии возвращаемого ресурса. Сохраните и используйте URL-адрес @odata.deltaLink, чтобы узнавать об изменениях ресурса в следующем цикле.
    • Вы можете указать заголовок Prefer:return=minimal, чтобы включить в значения отклика только свойства, измененные с момента создания @odata.deltaLink.

По умолчанию: возвращение свойств, совпадающих с начальным разностным запросом

По умолчанию запросы с использованием @odata.deltaLink или @odata.nextLink возвращают те же свойства, которые выбраны в начальном разностном запросе, следующим образом:

  • Если свойство изменилось, в отклике содержится новое значение. Сюда включаются свойства с заданным значением NULL.
  • Если свойство не изменилось, старое значение включается в ответ.
  • Если свойство ранее никогда не настраивалось, оно не включается в отклик.

Примечание. При таком поведении просмотр отклика не дает возможность определить, изменилось ли свойство. Кроме того, разностные ответы, как правило, имеют большой размер, так как они содержат все значения свойств, как показано в примере 2.

Альтернатива: возвращение только измененных свойств

Добавление необязательного заголовка запроса prefer:return=minimal приводит к следующему результату:

  • Если свойство изменилось, в отклике содержится новое значение. Сюда включаются свойства с заданным значением NULL.
  • Если свойство не изменилось, оно вообще не включается в ответ. (Отличается от поведения по умолчанию.)

Примечание. Заголовок можно добавить в запрос @odata.deltaLink в любой момент разностного цикла. Заголовок влияет только на набор свойств, включенный в отклик, и не влияет на способ выполнения разностного запроса. См. пример 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"
    }
  ]
}

Связанные материалы