Поделиться через


Получение добавочных изменений для пользователей

Разностный запрос в Microsoft Graph позволяет запрашивать добавления, удаления или обновления поддерживаемых ресурсов с помощью ряда разностных запросов. Для пользователей разностный запрос позволяет обнаруживать изменения, не извлекая весь набор пользователей для сравнения изменений.

Клиенты, выполняющие синхронизацию пользователей с локальным хранилищем профилей, смогут использовать разностный запрос как для первичной полной синхронизации, так и для последующей добавочной синхронизации. Как правило, клиент выполняет начальную полную синхронизацию всех пользователей в клиенте, а затем периодически получает добавочные изменения для пользователей.

Отслеживание изменений пользователей

Отслеживайте изменения пользователей с помощью одного или нескольких запросов GET с помощью функции delta. Запрос GET имеет следующие характеристики:

  • Функция delta , предопределенная URL-пути.
  • Маркер состояния (deltatoken или skipToken) из предыдущего вызова разностной функции GET.
  • [Необязательно] Любые поддерживаемые параметры запроса

Пример

В этой статье показана серия примеров запросов для отслеживания изменений пользователей:

  1. Исходный запрос и ответ
  2. Запрос nextLink и отклик
  3. Последний запрос nextLink и отклик
  4. Запрос deltaLink и отклик deltaLink

Исходный запрос

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

Совет

/delta — это ярлык для полного имени /microsoft.graph.delta. Запросы, созданные пакетами SDK Для Microsoft Graph, используют полное имя.

Обратите внимание на следующие элементы:

  • Необязательный параметр $select включен в запрос, чтобы продемонстрировать, как параметры запроса автоматически включаются в последующие запросы. При необходимости параметры запроса должны быть указаны в начальном запросе.
    • На наличие изменений отслеживаются только свойства, включенные в $select . Если $select параметр не указан, все свойства объекта отслеживаются на наличие изменений.
  • Исходный запрос не включает маркер состояния. Маркеры состояния используются в последующих запросах.
GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,givenName,surname

Исходный отклик

В случае успеха этот метод возвращает код отклика 200 OK и объект коллекции user в тексте отклика. При условии, что весь набор пользователей слишком велик, ответ включает @odata.nextLink маркер состояния в @odata.nextLink параметре .

В этом примере возвращается URL-адрес @odata.nextLink. Это означает, что в текущем сеансе можно получить дополнительные страницы данных. Обратите внимание на в $skiptoken URL-адресе. Параметр $select из исходного запроса кодируется в URL-адресе @odata.nextLink.

Ответ также содержит заметку @removed для пользователя с идентификатором 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, означающим, что доступны дополнительные изменения, которые были отслежены для пользователей. Используйте URL-адрес @odata.nextLink в других запросах, пока URL-адрес @odata.deltaLink (в параметре @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, чтобы узнавать о других изменениях пользователей. Сохраните маркер 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"
      }
    }
  ]
}