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

Настройка уведомлений об изменениях в данных ресурса

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

Важно!

Функция уведомлений об изменениях не поддерживается в Внешняя идентификация Microsoft Entra во внешних клиентах и Azure AD клиентах B2C.

Зачем получать уведомления об изменениях?

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

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

На следующем рисунке показано, как работают уведомления об изменениях, и сравнивается с отслеживанием изменений.

Иллюстрация уведомлений об изменениях и служб разностных запросов

В следующем видео представлен обзор уведомлений об изменениях в Microsoft Graph.

Типы уведомлений об изменениях

Microsoft Graph поддерживает три типа уведомлений об изменениях:

  • Основные уведомления: уведомления об изменении, которые не содержат данные ресурса, кроме идентификатора измененного ресурса. Когда приложение получает базовое уведомление, служба может использовать идентификатор для запроса измененного объекта.
  • Расширенные уведомления: уведомления об изменениях, включающие данные ресурсов измененного объекта. Дополнительные сведения о расширенных уведомлениях см. в разделе Расширенные уведомления.
  • Уведомления жизненного цикла. Уведомления, предупреждающие клиента о том, что он рискует отсутствовать уведомления об изменениях из-за жизненного цикла подписки. Дополнительные сведения об уведомлениях о жизненном цикле см. в разделе Уведомления о жизненном цикле.

Получение уведомлений об изменениях

Microsoft Graph может доставлять уведомления об изменениях клиентам по следующим каналам.

Управление подписками

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

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

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

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

Примечание.

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

Ресурс Поддерживаемые пути к ресурсам Ограничения
Облачная печать printer Изменяется, когда задание печати готово к скачиванию (событие jobFetchable): /print/printers/{id}/jobs -
Облачная печать printTaskDefinition Изменяется при наличии допустимого задания в очереди (событие jobStarted): /print/printtaskdefinition/{id}/tasks -
Copilot aiInteraction Взаимодействие с ИИ Copilot, частью чего является конкретный пользователь: copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions

Взаимодействие Copilot AI в организации: copilot/interactionHistory/getAllEnterpriseInteractions		 Квоты максимальной подписки:
  • Сочетание приложения и клиента (для подписок, отслеживая взаимодействие ИИ в клиенте): 1
  • Для каждого приложения и пользователя (для подписок, отслеживающего взаимодействие СИ, частью является конкретный пользователь): 1
  • На пользователя (для подписок, отслеживаемых взаимодействием СИ, частью является конкретный пользователь): 10 подписок.
  • На организацию: всего 10 000 подписок.
    		•
    driveItemна OneDrive (личный) Изменения содержимого в иерархии любой папки: /users/{id}/drive/root -
    driveItem в OneDrive для работы или учебы Изменения содержимого в иерархии корневой папки: /drives/{id}/root , /users/{id}/drive/root -
    group Изменения во всех группах: /groups

    Изменения в определенной группе: /groups/{id}

    Изменения владельцев определенной группы: /groups/{id}/owners

    Изменения членов определенной группы: /groups/{id}/members    		 Квоты максимальной подписки:
  • На приложение (для всех клиентов вместе взятых): 50 000 подписок.
  • На клиента (для всех приложений вместе взятых): 1000 подписок во всех приложениях.
  • На одно сочетание приложения и клиента: всего 100 подписок.

    Не поддерживается для Azure AD клиентов B2C.

    ЗАМЕТКА: Создание и обратимое удаление групп также активирует updatedchangeType.
    		•
    оповещение о мониторинге работоспособности Microsoft Entra Изменения во всех оповещениях мониторинга работоспособности: /reports/healthmonitoring/alerts

    Изменения в определенном типе оповещения: /reports/healthmonitoring/alert свойство notificationQueryOptions в полезных данных запроса задано как $filter=alertType eq '{alertType}'    		 -
    список на сайте SharePoint Изменения содержимого в списке: /sites/{site-id}/lists/{list-id} -
    Групповой чат Microsoft 365 Изменения в беседах группы: groups/{id}/conversations -
    Сообщение Outlook Изменения во всех сообщениях в почтовом ящике пользователя: /users/{id}/messages , /me/messages

    Изменения в сообщениях в папке "Входящие" пользователя: /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages    		 Допускается не более 1000 активных подписок на почтовый ящик для всех приложений.
    Событие Outlook Изменения во всех событиях в почтовом ящике пользователя: /users/{id}/events , /me/events Допускается не более 1000 активных подписок на почтовый ящик для всех приложений.
    Личный контакт Outlook Изменения для всех личных контактов в почтовом ящике пользователя: /users/{id}/contacts , /me/contacts Допускается не более 1000 активных подписок на почтовый ящик для всех приложений.
    Оповещение безопасности Изменения в конкретном оповещении: /security/alerts/{id}

    Изменения в отфильтрованных оповещениях: /security/alerts/?$filter={parameters}    		 Дополнительные сведения см. в разделе API безопасности оповещения.
    Утверждения Teams Изменения во всех утверждениях в клиенте: /solutions/approval/approvalItems Квоты максимальной подписки:
  • На клиента (для сочетания всех приложений): 1000 подписок всего во всех приложениях
  • Для каждого приложения и клиента: 1 подписка.
    		•
    callRecord в Teams Изменения во всех записях звонков: /communications/callRecords

    Изменения в отфильтрованных записях вызовов: /communications/callRecords?$filter={parameters}    		 Дополнительные сведения см. в разделе Уведомления об изменении для записей вызовов.

    Квоты максимальной подписки:
  • На организацию: всего 100 подписок.

    ЗАМЕТКА: Создание записей вызовов также активирует updatedchangeType.
    		•
    Вызовы TeamsRecording Все записи в организации: communications/onlineMeetings/getAllRecordings

    Все записи для определенного собрания: communications/onlineMeetings/{onlineMeetingId}/recordings

    Запись звонка, которая становится доступной на собрании, организованном определенным пользователем: users/{id}/onlineMeetings/getAllRecordings

    Запись звонка, которая становится доступной на собрании, где установлено определенное приложение Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings *    		 Квоты максимальной подписки:
  • Для каждого приложения и сочетания онлайн-собраний: 1
  • Для каждого приложения и пользователя: 1
  • На пользователя (для записей отслеживания подписок во всех onlineMeetings, организованных пользователем): 10 подписок.
  • На организацию: всего 10 000 подписок.
    		•
    Вызов TeamsTranscript Все расшифровки в организации: communications/onlineMeetings/getAllTranscripts

    Все расшифровки для определенного собрания: communications/onlineMeetings/{onlineMeetingId}/transcripts

    Расшифровка звонка, которая становится доступной на собрании, организованном определенным пользователем: users/{id}/onlineMeetings/getAllTranscripts

    Расшифровка звонка, которая становится доступной на собрании, где установлено определенное приложение Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts *    		 Квоты максимальной подписки:
  • Для каждого приложения и сочетания онлайн-собраний: 1
  • Для каждого приложения и пользователя: 1
  • На пользователя (для подписок, отслеживающих расшифровки во всех onlineMeetings, упорядоченных пользователем): 10 подписок.
  • На организацию: всего 10 000 подписок.
    		•
    Чат Teams Изменения в любом чате в клиенте: /chats

    Изменения в конкретном чате: /chats/{id}

    Изменения в определенном чате с параметром запроса notifyOnUserSpecificProperties : /chats/{id}?notifyOnUserSpecificProperties={Boolean}

    Изменения во всех чатах в организации, где установлено определенное приложение Teams: /appCatalogs/teamsApps/{id}/installedToChats

    Изменения во всех чатах, частью которыми является конкретный пользователь: /users/{id}/chats

    Изменения во всех чатах, частью которыми является конкретный пользователь, с помощью параметра запроса notifyOnUserSpecificProperties : /users/{id}/chats?notifyOnUserSpecificProperties={Boolean}    		 Квоты максимальной подписки:
  • Для каждого приложения и чата: 1 подписка.
  • На организацию: всего 10 000 подписок.
  • На пользователя (для подписок, отслеживающих все чаты, в которые входит конкретный пользователь): 10 подписок.
    		•
    chatMessage Teams Изменения в сообщениях чата во всех каналах во всех командах: /teams/getAllMessages

    Изменения в сообщениях чата в определенном канале: /teams/{id}/channels/{id}/messages

    Изменения в сообщениях чата во всех чатах: /chats/getAllMessages

    Изменения в сообщениях чата в определенном чате: /chats/{id}/messages

    Изменения в сообщениях чата во всех чатах, в которые входит конкретный пользователь: /users/{id}/chats/getAllMessages

    Изменения в сообщениях чата для всех чатов в организации, где установлено определенное приложение Teams: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages    		 Квоты максимальной подписки:
  • Для каждого приложения и канала или чата: 1 подписка.
  • На пользователя (для подписок, отслеживая сообщения чата во всех чатах, в которые входит пользователь): 10 подписок.
  • На организацию: всего 10 000 подписок.
    		•
    Канал Teams Изменения каналов во всех командах: /teams/getAllChannels

    Изменения канала в определенной команде: /teams/{id}/channels    		 Квоты максимальной подписки:
  • Для каждого приложения и команды: 1 подписка.
  • На организацию: всего 10 000 подписок.
    		•
    conversationMember в Teams Изменения членства в определенной команде: /teams/{id}/members

    Изменения членства во всех каналах в определенной команде: teams/{id}/channels/getAllMembers

    Изменения в членстве в определенном чате: /chats/{id}/members

    Изменения в членстве для всех чатов в организации, где установлено определенное приложение Teams: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers

    Изменения членства во всех чатах: /chats/getAllMembers    		 Квоты максимальной подписки:
  • Для каждого приложения и команды: 1 подписка.
  • На организацию: всего 10 000 подписок.
    		•
    Teams onlineMeeting* Изменения в онлайн-собрании: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents Не поддерживает использование $select для возврата только выбранных свойств. Расширенное уведомление состоит из всех свойств измененного экземпляра. Одна подписка разрешена для каждого приложения на собрание по сети. Дополнительные сведения см. в разделе Получение уведомлений об изменениях для обновлений событий звонков в Microsoft Teams.
    presence в Teams Изменения в присутствии одного пользователя: /communications/presences/{id}

    Изменения в присутствии нескольких пользователей: /communications/presences?$filter=id in ({id},{id}...)    		 Подписка на присутствие нескольких пользователей ограничена 650 отдельными пользователями. Не поддерживает использование $select для возврата только выбранных свойств. Расширенное уведомление состоит из всех свойств измененного экземпляра. Допускается одна подписка на одно приложение на каждого делегированного пользователя. Дополнительные сведения см. в разделе Получение уведомлений об изменениях для обновлений присутствия в Microsoft Teams.
    Команда Teams Изменения в любой команде в клиенте: /teams

    Изменения в конкретной команде: /teams/{id}    		 Квоты максимальной подписки:
  • Для каждого приложения и команды: 1 подписка.
  • На организацию: всего 10 000 подписок.
    		•
    Предложение Смены TeamsShiftRequest Изменения в любом запросе на смену предложения в команде: /teams/{id}/schedule/offerShiftRequests Квоты максимальной подписки:
  • Сочетание пути к приложению и ресурсу: 1 подписка на клиент.
  • На путь к ресурсу и сочетание пользователей: 10 делегированных подписок пользователей на клиент.
    		•
    Teams Shifts openShiftChangeRequest Изменения в любом запросе на открытые смены в команде: /teams/{id}/schedule/openShiftChangeRequests Квоты максимальной подписки:
  • Сочетание пути к приложению и ресурсу: 1 подписка на клиент.
  • Для каждого пользователя и пути к ресурсу: 10 подписок.
  • На организацию: всего 10 000 подписок.
    		•
    Смена "Смены" в Teams Изменения в любой смене в команде: /teams/{id}/schedule/shifts Квоты максимальной подписки:
  • Сочетание пути к приложению и ресурсу: 1 подписка на клиент.
  • Для каждого пользователя и пути к ресурсу: 10 подписок.
  • На организацию: всего 10 000 подписок.
    		•
    Teams Shifts swapShiftsChangeRequest Изменения в любом запросе на смену переключения в команде: /teams/{id}/schedule/swapShiftsChangeRequests Квоты максимальной подписки:
  • Сочетание пути к приложению и ресурсу: 1 подписка на клиент.
  • Для каждого пользователя и пути к ресурсу: 10 подписок.
  • На организацию: всего 10 000 подписок.
    		•
    Время смен TeamsOffRequest Изменения в любом запросе на отгул в команде: /teams/{id}/schedule/timeOffRequests Квоты максимальной подписки:
  • Сочетание пути к приложению и ресурсу: 1 подписка на клиент.
  • Для каждого пользователя и пути к ресурсу: 10 подписок.
  • На организацию: всего 10 000 подписок.
    		•
    todoTask Изменения для всех задач в определенном списке задач: /me/todo/lists/{todoTaskListId}/tasks -
    user Изменения для всех пользователей: /users

    Изменения для конкретного пользователя: /users/{id}    		 Квоты максимальной подписки:
  • На приложение (для всех клиентов вместе взятых): 50 000 подписок.
  • На клиента (для всех приложений в сочетании): 1000 подписок во всех приложениях
  • На одно сочетание приложения и клиента: всего 100 подписок.

    Не поддерживается для личных учетных записей Майкрософт, таких как outlook.com.

    Не поддерживается для Azure AD клиентов B2C.

    ЗАМЕТКА: Создание и обратимое удаление пользователей также активируют updatedchangeType.
    		•

    Примечание.

    Многие ресурсы имеют ограничения или квоты на количество подписок, которые можно создать для этого ресурса. При превышении этого ограничения попытки создать подписку приведут к возникновению 403 Forbidden ошибки. Свойство message ответа об ошибке будет объяснять превышенное ограничение.

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

    Время существования подписки

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

    В следующей таблице показаны максимальные сроки действия подписок на ресурс в Microsoft Graph.

    Ресурс Максимальный срок действия
    Copilot aiInteraction 4320 минут (три дня)
    Оповещение безопасности 43 200 минут (до 30 дней)
    Утверждения Teams 43 200 минут (до 30 дней)
    callRecord в Teams 4 230 минут (до трех дней)
    Вызовы TeamsRecording 4320 минут (три дня)
    Вызов TeamsTranscript 4320 минут (три дня)
    Канал Teams 4320 минут (три дня)
    Чат Teams 4320 минут (три дня)
    chatMessage Teams 4320 минут (три дня)
    conversationMember в Teams 4320 минут (три дня)
    onlineMeeting в Teams 4320 минут (три дня)
    Команда Teams 4320 минут (три дня)
    Teams teamsAppInstallation 4 320 минут (3 дня)
    Предложение Смены TeamsShiftRequest 360 минут (6 часов)
    Teams Shifts openShiftChangeRequest 360 минут (6 часов)
    Смена "Смены" в Teams 360 минут (6 часов)
    Teams Shifts swapShiftsChangeRequest 360 минут (6 часов)
    Время смен TeamsOffRequest 360 минут (6 часов)
    Групповая беседа 4 230 минут (до трех дней)
    driveItem OneDrive 42 300 минут (до 30 дней)
    Список SharePoint 42 300 минут (до 30 дней)
    Сообщение, событие, контакт Outlook 10 080 минут (до семи дней)

    Для подписок с данными ресурсов (расширенные подписки на уведомления) время существования подписки составляет 1440 минут (до одного дня).
    Пользователь, группа, другие ресурсы каталога 41 760 минут (до 29 дней)
    onlineMeeting 4 230 минут (до трех дней)
    presence 60 минут (1 час)
    printer печати 4 230 минут (до трех дней)
    printTaskDefinition печати 4 230 минут (до трех дней)
    todoTask 4 230 минут (до трех дней)

    Веб-перехватчики для этого ресурса доступны только в глобальной конечной точке, а не в национальных облаках.
    оповещение о мониторинге работоспособности Microsoft Entra 42 300 минут (до 30 дней)
    baseTask (не рекомендуется) 4 230 минут (до трех дней)

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

    Задержка

    В следующей таблице указаны ожидаемые задержки между возникновением события в службе и доставкой уведомления об изменении.

    Ресурс Средняя задержка Максимальная задержка
    aiInteraction Менее 10 секунд 60 минут
    оповещение1 Менее 3 минут 5 минут
    Утверждения Менее 10 секунд 40 секунд
    calendar Менее 1 минуты 3 минуты
    callRecord2 Менее 30 минут 150 минут
    callRecording Менее 10 секунд 60 минут
    callTranscript Менее 10 секунд 60 минут
    channel Менее 10 секунд 60 минут
    chat Менее 10 секунд 60 минут
    chatMessage Менее 10 секунд 1 минута
    contact Менее 1 минуты 3 минуты
    conversation Неизвестно Неизвестно
    conversationMember Менее 10 секунд 60 минут
    driveItem Менее 1 минуты 60 минут
    event Неизвестно Неизвестно
    group Неизвестно Неизвестно
    оповещение мониторинга работоспособности Неизвестно Неизвестно
    list Менее 1 минуты 60 минут
    message Менее 1 минуты 3 минуты
    offerShiftRequest Менее 1 минуты 60 минут
    onlineMeeting Менее 10 секунд 1 минута
    openShiftChangeRequest Менее 1 минуты 60 минут
    presence Менее 10 секунд 1 минута
    printer Менее 1 минуты 5 минут
    printTaskDefinition Менее 1 минуты 5 минут
    shift Менее 1 минуты 60 минут
    swapShiftsChangeRequest Менее 1 минуты 60 минут
    team Менее 10 секунд 60 минут
    teamsAppInstallation Менее 10 секунд 60 минут
    timeOffRequest Менее 1 минуты 60 минут
    todoTask Менее 2 минут 15 минут
    user Неизвестно Неизвестно

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

    Примеры кода

    Указанные ниже примеры кода доступны на сайте GitHub.

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

    • Last updated on