Ескертпе
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Жүйеге кіруді немесе каталогтарды өзгертуді байқап көруге болады.
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Каталогтарды өзгертуді байқап көруге болады.
Уведомления об изменениях позволяют приложениям получать оповещения, когда ресурс Microsoft Graph их интересует изменения; т. е. создано, обновлено или удалено. Microsoft Graph отправляет уведомления в указанную конечную точку клиента, а клиентская служба обрабатывает уведомления в соответствии с бизнес-требованиями. Например, служба может получать больше данных, обновлять кэш и представления и т. д.
Важно!
Функция уведомлений об изменениях не поддерживается в Внешняя идентификация Microsoft Entra во внешних клиентах и Azure AD клиентах B2C.
Зачем получать уведомления об изменениях?
Уведомления об изменениях следуют модели, управляемой событиями, когда клиенты получают оповещения при внесении изменений, а не опрашивает Microsoft Graph. В зависимости от бизнес-логики уведомления об изменениях подходят в следующих случаях:
- Вы подписываетесь на ресурс, который часто изменяется.
- Вы должны реагировать на изменения почти в режиме реального времени.
- Вы хотите избежать частого опроса Microsoft Graph, что может привести к превышению ограничений регулирования.
На следующем рисунке показано, как работают уведомления об изменениях, и сравнивается с отслеживанием изменений.
В следующем видео представлен обзор уведомлений об изменениях в Microsoft Graph.
Типы уведомлений об изменениях
Microsoft Graph поддерживает три типа уведомлений об изменениях:
- Основные уведомления: уведомления об изменении, которые не содержат данные ресурса, кроме идентификатора измененного ресурса. Когда приложение получает базовое уведомление, служба может использовать идентификатор для запроса измененного объекта.
- Расширенные уведомления: уведомления об изменениях, включающие данные ресурсов измененного объекта. Дополнительные сведения о расширенных уведомлениях см. в разделе Расширенные уведомления.
- Уведомления жизненного цикла. Уведомления, предупреждающие клиента о том, что он рискует отсутствовать уведомления об изменениях из-за жизненного цикла подписки. Дополнительные сведения об уведомлениях о жизненном цикле см. в разделе Уведомления о жизненном цикле.
Получение уведомлений об изменениях
Microsoft Graph может доставлять уведомления об изменениях клиентам по следующим каналам.
- Веб-перехватчики. Дополнительные сведения см. в статье Получение уведомлений об изменениях с помощью веб-перехватчиков.
- Центры событий Azure. Дополнительные сведения см. в разделе Получение уведомлений об изменениях через Центры событий Azure.
- Сетка событий Azure. Дополнительные сведения см. в статье Получение уведомлений об изменениях с помощью Сетка событий Azure.
Управление подписками
Клиенты могут создавать, продлевать и удалять подписки. Пока подписка активна и когда изменения происходят в ресурсе с подпиской, Microsoft Graph отправляет уведомления об изменениях в указанную конечную точку уведомления.
Вы управляете подпиской с помощью типа ресурса подписки и связанных с ним методов. Microsoft Graph отправляет уведомления об изменениях в структуре, определенной в типе ресурса changeNotificationCollection.
Поддерживаемые ресурсы
Приложение может подписаться на изменения в ресурсах Microsoft Graph, перечисленных в таблице. Подписки на ресурсы, помеченные звездочкой (*), доступны только в конечной точке /beta .
Примечание.
Для ресурсов Microsoft Teams ограничение на организацию в 10 000 общих подписок совместно используется во всех подписках на уведомления об изменениях Teams в клиенте. Она включает подписки, созданные для различных ресурсов Teams, таких как чаты, сообщения чата, расшифровки звонков, записи звонков, каналы, команды и участники беседы, которые учитываются в рамках одной и той же квоты организации. Когда совокупное количество активных подписок Teams достигает этого предела, любой запрос на создание дополнительной подписки для ресурса Teams завершается ошибкой 403 Forbidden .
| Ресурс | Поддерживаемые пути к ресурсам | Ограничения |
|---|---|---|
| Облачная печать 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 |
Квоты максимальной подписки: |
| 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 |
Квоты максимальной подписки: Не поддерживается для 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 |
Квоты максимальной подписки: |
| callRecord в Teams | Изменения во всех записях звонков: /communications/callRecords Изменения в отфильтрованных записях вызовов: /communications/callRecords?$filter={parameters} |
Дополнительные сведения см. в разделе Уведомления об изменении для записей вызовов. Квоты максимальной подписки: ПРИМЕЧАНИЕ: Создание записей вызовов также активирует updatedchangeType. |
| Вызовы TeamsRecording | Все записи в организации: communications/onlineMeetings/getAllRecordings Все записи для определенного собрания: communications/onlineMeetings/{onlineMeetingId}/recordings Запись звонка, которая становится доступной на собрании, организованном определенным пользователем: users/{id}/onlineMeetings/getAllRecordings Запись звонка, которая становится доступной на собрании, где установлено определенное приложение Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
Квоты максимальной подписки: |
| Вызов TeamsTranscript | Все расшифровки в организации: communications/onlineMeetings/getAllTranscripts Все расшифровки для определенного собрания: communications/onlineMeetings/{onlineMeetingId}/transcripts Расшифровка звонка, которая становится доступной на собрании, организованном определенным пользователем: users/{id}/onlineMeetings/getAllTranscripts Расшифровка звонка, которая становится доступной на собрании, где установлено определенное приложение Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
Квоты максимальной подписки: |
| Чат Teams | Изменения в любом чате в клиенте: /chats Изменения в конкретном чате: /chats/{id} Изменения в определенном чате с параметром запроса notifyOnUserSpecificProperties : /chats/{id}?notifyOnUserSpecificProperties={Boolean} Изменения во всех чатах в организации, где установлено определенное приложение Teams: /appCatalogs/teamsApps/{id}/installedToChats Изменения во всех чатах, частью которыми является конкретный пользователь: /users/{id}/chats Изменения во всех чатах, частью которыми является конкретный пользователь, с помощью параметра запроса notifyOnUserSpecificProperties : /users/{id}/chats?notifyOnUserSpecificProperties={Boolean} |
Квоты максимальной подписки: |
| chatMessage Teams | Изменения в сообщениях чата во всех каналах во всех командах: /teams/getAllMessages Изменения в сообщениях чата в определенном канале: /teams/{id}/channels/{id}/messages Изменения в сообщениях чата во всех чатах: /chats/getAllMessages Изменения в сообщениях чата в определенном чате: /chats/{id}/messages Изменения в сообщениях чата во всех чатах, в которые входит конкретный пользователь: /users/{id}/chats/getAllMessages Изменения в сообщениях чата для всех чатов в организации, где установлено определенное приложение Teams: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages |
Квоты максимальной подписки: |
| Канал Teams | Изменения каналов во всех командах: /teams/getAllChannels Изменения канала в определенной команде: /teams/{id}/channels |
Квоты максимальной подписки: |
| conversationMember в Teams | Изменения членства в определенной команде: /teams/{id}/members Изменения членства во всех каналах в определенной команде: teams/{id}/channels/getAllMembers Изменения в членстве в определенном чате: /chats/{id}/members Изменения в членстве для всех чатов в организации, где установлено определенное приложение Teams: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers Изменения членства во всех чатах: /chats/getAllMembers |
Квоты максимальной подписки: |
| 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} |
Квоты максимальной подписки: |
| Предложение Смены TeamsShiftRequest | Изменения в любом запросе на смену предложения в команде: /teams/{id}/schedule/offerShiftRequests |
Квоты максимальной подписки: |
| Teams Shifts openShiftChangeRequest | Изменения в любом запросе на открытые смены в команде: /teams/{id}/schedule/openShiftChangeRequests |
Квоты максимальной подписки: |
| Смена "Смены" в Teams | Изменения в любой смене в команде: /teams/{id}/schedule/shifts |
Квоты максимальной подписки: |
| Teams Shifts swapShiftsChangeRequest | Изменения в любом запросе на смену переключения в команде: /teams/{id}/schedule/swapShiftsChangeRequests |
Квоты максимальной подписки: |
| Время смен TeamsOffRequest | Изменения в любом запросе на отгул в команде: /teams/{id}/schedule/timeOffRequests |
Квоты максимальной подписки: |
| todoTask | Изменения для всех задач в определенном списке задач: /me/todo/lists/{todoTaskListId}/tasks |
- |
| user | Изменения для всех пользователей: /users Изменения для конкретного пользователя: /users/{id} |
Квоты максимальной подписки: Не поддерживается для личных учетных записей Майкрософт, таких как 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.
- Обучающий модуль по Microsoft Graph: использование уведомлений об изменениях и отслеживание изменений с помощью Microsoft Graph
- Пример веб-перехватчиков Microsoft Graph для Node.js
- Пример веб-перехватчиков Microsoft Graph для ASP.NET Core
- Пример веб-перехватчиков Microsoft Graph для Java Spring