Отслеживание изменений в данных Microsoft Graph с помощью разностного запроса

  • Статья

Разностный запрос, также называемый отслеживанием изменений, позволяет приложениям обнаруживать вновь созданные, обновленные или удаленные сущности без полного считывания целевого ресурса с каждым запросом. Приложения Microsoft Graph могут использовать запросы изменений, чтобы эффективно синхронизировать изменения с локальным хранилищем данных.

Использование разностного запроса позволяет избежать постоянного опроса Microsoft Graph, так как приложение запрашивает только данные, измененные с момента последнего запроса. Этот шаблон позволяет приложению уменьшить объем запрашиваемых данных, тем самым уменьшая затраты на запрос и, таким образом, скорее всего, ограничивает вероятность регулирования запросов.

Отслеживание изменений в коллекции ресурсов с помощью запроса изменений

Ниже представлен типичный шаблон вызова.

  1. Приложение выполняет запрос GET с функцией delta для нужного ресурса. Например, GET https://graph.microsoft.com/v1.0/users/delta.

    Совет

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

  2. Microsoft Graph отвечает запрошенным ресурсом и маркером состояния.

    А. Если Microsoft Graph возвращает @odata.nextLink URL-адрес, в сеансе будет больше страниц данных, даже если текущий ответ содержит пустой результат. Приложение использует @odata.nextLink URL-адрес для выполнения запросов на получение всех страниц данных до тех пор, пока Microsoft Graph не вернет @odata.deltaLink URL-адрес в ответе.

    Б. Если Microsoft Graph возвращает @odata.deltaLink URL-адрес, больше нет данных о существующем состоянии ресурса, возвращаемого в текущем сеансе. В последующих запросах приложение использует URL-адрес @odata.deltaLink, чтобы узнавать об изменениях ресурса.

    Примечание.

    Ответ Microsoft Graph на шаге 2 включает ресурсы, которые в настоящее время существуют в коллекции. Ресурсы, которые были удалены до первоначального разностного запроса, не возвращаются. Обновления, внесенные до исходного запроса, обобщаются в возвращаемом ресурсе в их последнем состоянии.

  3. Когда приложению нужно узнать об изменениях ресурса, оно использует @odata.deltaLink URL-адрес, полученный на шаге 2, для выполнения запросов. Приложение может выполнить этот запрос сразу после выполнения шага 2 или при проверке наличия изменений.

  4. Microsoft Graph возвращает описание изменений ресурса с момента последнего запроса вместе с URL-адресом @odata.nextLink или @odata.deltaLink.

Примечание.

  • Ресурсы, хранящиеся в Microsoft Entra ID (например, пользователи и группы), поддерживают сценарии синхронизации. Это позволит пропустить действия 1 и 2 (если вы не хотите получать полное состояние ресурса) и запросить последнюю @odata.deltaLink. Добавьте $deltatoken=latest к функции delta, и ответ будет содержать ссылку @odata.deltaLink, но не будет содержать данные ресурсов. Ресурсы в OneDrive и SharePoint также поддерживают эту функцию, но требуются token=latest .
  • $selectПараметры и $deltaLink запроса поддерживаются для некоторых ресурсов Microsoft Entra, чтобы клиенты могли изменять свойства, которые они хотят отслеживать для существующего @odata.deltaLink. Разностные запросы с обоими $select и $skiptoken не поддерживаются.

Маркеры состояния

Ответ GET на запрос изменений всегда включает URL-адрес, указанный в заголовке @odata.nextLink или @odata.deltaLink. URL-адрес @odata.nextLink содержит $skiptoken, а @odata.deltaLink URL-адрес — $deltatoken.

Эти маркеры непрозрачны для клиентского приложения, но важны следующим образом:

  • Каждый маркер отражает состояние и представляет моментальный снимок ресурса в этом цикле отслеживания изменений.
  • Маркеры состояния кодируют и включают параметры запроса (например, $select), указанные в исходном разностном запросе. Поэтому не изменяйте последующие разностные запросы для повторения этих параметров запроса.
  • Совершая запрос изменений, вы можете скопировать и применить URL-адрес @odata.nextLink или @odata.deltaLink при следующем вызове функции delta, не проверяя содержимое URL-адреса, в том числе маркер состояния.

Необязательные параметры запросов

Если клиент использует параметр запроса, он должен быть указан в начальном запросе. Microsoft Graph автоматически кодирует указанный параметр запроса в @odata.nextLink или @odata.deltaLink в ответе и во всех последующих @odata.nextLink URL-адресах или @odata.deltaLink .

Обратите внимание на общую ограниченную поддержку следующих необязательных параметров запроса:

  • $orderby

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

  • $top

    Число объектов на каждой странице зависит от типа ресурса и типа изменений, внесенных в ресурс.

См. сведения о поддержке параметров разностного запроса для ресурса message.

Для ресурсов user и group действуют ограничения на применение некоторых параметров запроса:

  • $expand не поддерживается.

  • $top не поддерживается.

  • $orderby не поддерживается.

  • $select Если используется параметр запроса, параметр указывает, что клиент предпочитает отслеживать только изменения свойств или связей, указанных в инструкции $select . Если изменение происходит в свойстве, которое не выбрано, ресурс, для которого было изменено это свойство, не отображается в разностном ответе после последующего запроса.

  • $select также поддерживает свойства навигации руководителя и участников для пользователей и групп соответственно. Выбор этих свойств позволяет отслеживать изменения руководства и участия в группах для пользователя.

  • Фильтры области позволяют отслеживать изменения для одного или нескольких конкретных пользователей или групп, фильтруя только по идентификатору объекта. Например, следующий запрос возвращает изменения для групп, соответствующих идентификаторам, указанным в фильтре запроса.

https://graph.microsoft.com/beta/groups/delta/?$filter=id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'

Представление ресурсов в отклике на разностный запрос

  • Новые экземпляры поддерживаемого ресурса представлены в ответе на запрос изменений с помощью стандартных свойств.

  • Обновленные экземпляры представлены идентификатором по крайней мере с обновленными свойствами, но могут быть включены и другие свойства.

  • Связи между пользователями и группами представлены в виде заметок к стандартному представлению ресурса. В этих заметках используется формат propertyName@delta. Заметки включаются в ответ начального разностного запроса.

  • Удаленные экземпляры представлены идентификатором и объектом @removed . Объект @removed может содержать дополнительные сведения о том, почему экземпляр был удален. Например, "@removed": {"reason": "changed"}. Возможные причины @removed могут быть changed или deleted.

    • changed указывает, что элемент удален и может быть восстановлен из deletedItems.

    • deleted указывает, что элемент удален и не может быть восстановлен.

      Объект @removed можно вернуть в начальном ответе разностного запроса и в отслеживаемых ответах (@odata.nextLink). Например, удаленный объект каталога, который по-прежнему можно восстановить из удаленных элементов, отображается как "@removed": {"reason": "changed"}. Клиенты, использующие разностные запросы, должны быть разработаны для обработки этих объектов в ответах.

  • Экземпляры, восстановленные из deletedItems , отображаются как только что созданные экземпляры в ответе разностного запроса.

Примечание.

Одна сущность может содержаться в ответе несколько раз, если эта сущность была изменена несколько раз и при определенных условиях. Запрос изменений позволяют вашему приложению перечислять все изменения, но не могут гарантировать, что объекты объединены в одном ответе.

Поддерживаемые ресурсы

Разностные запросы поддерживаются для указанных ниже ресурсов. Некоторые ресурсы, доступные в версии 1.0, имеют соответствующие разностные функции по-прежнему в состоянии предварительного просмотра, как указано.

Примечание. Функция delta для ресурсов, помеченных звездочкой (*), доступна только в конечной точке /beta .

Коллекция ресурсов API
application application: delta function
administrativeUnit administrativeUnit: функция delta
callRecording * callRecording: функция delta
callTranscript * callTranscript: разностная функция
chatMessage chatMessage: функция delta
device устройство: функция delta
directoryRole directoryRole: функция delta
directoryObject directoryObject: функция delta
driveItem1 driveItem: функция delta
educationAssignment educationAssignment: разностная функция
educationCategory educationCategory: функция delta
educationClass educationClass: функция delta
educationSchool educationSchool: delta function
educationUser educationUser: функция delta
event event: функция delta
group group: delta function
listItem1 listItem: разностная функция
mailFolder mailFolder: функция delta
message message: функция delta
orgContact orgContact: delta function
oAuth2PermissionGrant oAuth2PermissionGrant: функция delta
contactFolder contactFolder: разностная функция
ресурс contact contact: функция delta
plannerBucket * plannerBucket: функция delta
plannerUser2 plannerUser: функция delta
sites Функция delta ресурса сайта
servicePrincipal servicePrincipal: функция delta
todoTask todoTask: функция delta
todoTaskList todoTaskList: разностная функция
user user: функция delta

Примечание.

1 Шаблон использования ресурсов OneDrive и SharePoint аналогичен другим поддерживаемым ресурсам с некоторыми незначительными синтаксические различия. Дополнительные сведения о текущем синтаксисе см. в разделах driveItem: delta и listItem: delta.

2 Шаблон использования Планировщик ресурсов аналогичен другим поддерживаемым ресурсам с несколькими отличиями. Дополнительные сведения см. в разделе Planner: delta.

Национальные облачные развертывания

Разностные запросы для поддерживаемых ресурсов доступны для клиентов, размещенных в общедоступном облаке, Microsoft Cloud for US Government и Microsoft Cloud для Китая, управляемых компанией 21Vianet.

Ограничения

Изменения свойств, хранящихся за пределами хранилища данных main, не отслеживаются

Некоторые ресурсы содержат свойства, которые хранятся за пределами main хранилища данных для ресурса. Например, данные пользовательского ресурса в основном хранятся в Microsoft Entra ID, но некоторые из его свойств, таких как навыки, хранятся в SharePoint Online. В настоящее время изменения в разностном запросе вызываются только свойствами, хранящимися в хранилище данных main. Свойства, хранящиеся за пределами хранилища данных main, не поддерживаются в рамках отслеживания изменений. Таким образом, изменение любого из этих свойств не приводит к отображению объекта в ответе разностного запроса.

Дополнительные сведения о свойствах, хранящихся за пределами хранилища данных main, см. в документации по пользователям и группам.

Задержка обработки

Ожидайте различные задержки между временем изменения экземпляра ресурса и временем отражения отслеживаемого изменения в ответе разностного запроса.

Иногда из-за задержек репликации изменения объекта могут отображаться не сразу при выборе @odata.nextLink@odata.deltaLinkили . Повторите @odata.nextLink или @odata.deltaLink через некоторое время, чтобы получить последние изменения.

Повторения

Ваше приложение должно быть готово к повторениям, которые происходят, когда одинаковое изменение возникает в последующих откликах. Несмотря на то, что разностный запрос делает все возможное для сокращения воспроизведения, они по-прежнему возможны.

Сброс синхронизации

Разностный запрос может возвращать код отклика 410 Gone и заголовок Расположения, содержащий пустой URL-адрес запроса $deltatoken (такой же, как и исходный запрос). Это состояние обычно происходит для предотвращения несоответствия данных из-за внутреннего обслуживания или миграции целевого клиента. Это указывает на то, что приложение должно перезапуститься с полной синхронизацией целевого клиента.

Длительность маркера

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

  • Для объектов каталога ограничение составляет семь дней.
  • Для образовательных объектов (educationSchool, educationUser и educationClass) ограничение составляет семь дней.
  • Для сущностей Outlook (message, mailFolder, event, contact, contactFolder, todoTask и todoTaskList) верхний предел не установлен; Он зависит от размера внутреннего кэша разностных маркеров. Хотя новые разностные маркеры непрерывно добавляются в кэш, после превышения емкости кэша старые разностные маркеры удаляются.

В случае истечения срока действия маркера служба должна ответить ошибкой серии 40X с кодами ошибок, такими как syncStateNotFound. Дополнительные сведения см. в разделе Коды ошибок в Microsoft Graph.

Объединение разностных запросов и уведомлений об изменениях

Приложение может использовать уведомления об изменениях Microsoft Graph, чтобы подписаться на уведомления об изменении определенного ресурса. В дальнейшем приложение может использовать разностный запрос, чтобы запросить все изменения с момента предыдущего запроса.

Приложения могут использовать эту стратегию почти для устранения (только для поддерживаемых ресурсов) необходимости частого опроса Microsoft Graph и обработки этих изменений, чтобы обеспечить синхронизацию локального хранилища данных, что значительно снижает вероятность регулирования их запросов.

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

Дополнительные сведения о разностном запросе см. в следующих руководствах.