Настройка уведомлений об изменениях в данных ресурса
Уведомления об изменениях позволяют приложениям получать оповещения, когда ресурс Microsoft Graph их интересует изменения; т. е. создано, обновлено или удалено. Microsoft Graph отправляет уведомления в указанную конечную точку клиента, а клиентская служба обрабатывает уведомления в соответствии с бизнес-требованиями. Например, служба может получать больше данных, обновлять кэш и представления и т. д.
Зачем получать уведомления об изменениях?
Уведомления об изменениях следуют модели, управляемой событиями, когда клиенты получают оповещения при внесении изменений, а не опрашивает Microsoft Graph. В зависимости от бизнес-логики уведомления об изменениях подходят в следующих случаях:
- Вы подписываетесь на ресурс, который часто изменяется.
- Вы должны реагировать на изменения почти в режиме реального времени.
- Вы хотите избежать частого опроса Microsoft Graph, что может привести к превышению ограничений регулирования.
Типы уведомлений об изменениях
Microsoft Graph поддерживает три типа уведомлений об изменениях:
- Основные уведомления: уведомления об изменении, которые не содержат данные ресурса, кроме идентификатора измененного ресурса. Когда приложение получает базовое уведомление, служба может использовать идентификатор для запроса к измененным объектам.
- Расширенные уведомления: уведомления об изменениях, включающие данные ресурсов измененного объекта. Дополнительные сведения о расширенных уведомлениях см. в разделе Расширенные уведомления.
- Уведомления жизненного цикла. Уведомления, предупреждающие клиента о том, что он рискует отсутствовать уведомления об изменениях из-за жизненного цикла подписки. Дополнительные сведения об уведомлениях о жизненном цикле см. в разделе Уведомления о жизненном цикле.
Получение уведомлений об изменениях
Microsoft Graph может доставлять уведомления об изменениях клиентам по следующим каналам.
- Веб-перехватчики. Дополнительные сведения см. в статье Получение уведомлений об изменениях с помощью веб-перехватчиков.
- Центры событий Azure. Дополнительные сведения см. в разделе Получение уведомлений об изменениях через Центры событий Azure.
- Сетка событий Azure (предварительная версия). Дополнительные сведения см. в статье Получение уведомлений об изменениях с помощью Сетка событий Azure.
Управление подписками
Клиенты могут создавать, продлевать и удалять подписки. Пока подписка активна и когда изменения происходят в ресурсе с подпиской, Microsoft Graph отправляет уведомления об изменениях в указанную конечную точку уведомления.
Вы управляете подпиской с помощью типа ресурса подписки и связанных с ним методов. Microsoft Graph отправляет уведомления об изменениях в структуре, определенной в типе ресурса changeNotificationCollection.
Поддерживаемые ресурсы
Приложение может подписаться на изменения в ресурсах Microsoft Graph, перечисленных в таблице.
Примечание.
Подписки на ресурсы, помеченные звездочкой (*), доступны только в конечной точке /beta .
| Ресурс | Поддерживаемые пути к ресурсам | Ограничения |
|---|---|---|
| Облачная печать printer | Изменяется, когда задание печати готово к скачиванию (событие jobFetchable): /print/printers/{id}/jobs |
- |
| Облачная печать printTaskDefinition | Изменяется при наличии допустимого задания в очереди (событие jobStarted): /print/printtaskdefinition/{id}/tasks |
- |
| 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. |
| список на сайте 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.
| Ресурс | Максимальный срок действия |
|---|---|
| Оповещение безопасности | 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 минут (до семи дней) |
| Пользователь, группа, другие ресурсы каталога | 41 760 минут (до 29 дней) |
| onlineMeeting | 4 230 минут (до трех дней) |
| presence | 60 минут (1 час) |
| printer печати | 4 230 минут (до трех дней) |
| printTaskDefinition печати | 4 230 минут (до трех дней) |
| todoTask | 4 230 минут (до трех дней) Веб-перехватчики для этого ресурса доступны только в глобальной конечной точке, а не в национальных облаках. |
| baseTask (не рекомендуется) | 4 230 минут (до трех дней) |
Примечание. Для существующих приложений и новых приложений не должно превышаться допустимое значение. В будущем любые запросы на создание или продление подписки со значением, превышающим максимальное, будут завершаться ошибкой.
Задержка
В следующей таблице указаны ожидаемые задержки между возникновением события в службе и доставкой уведомления об изменении.
| Ресурс | Средняя задержка | Максимальная задержка |
|---|---|---|
| оповещение1 | Менее 3 минут | 5 минут |
| Утверждения | Менее 10 секунд | 40 секунд |
| calendar | Менее 1 минуты | 3 минуты |
| callRecord | Менее 15 минут | 60 минут |
| callRecording | Менее 10 секунд | 60 минут |
| callTranscript | Менее 10 секунд | 60 минут |
| channel | Менее 10 секунд | 60 минут |
| chat | Менее 10 секунд | 60 минут |
| chatMessage | Менее 10 секунд | 1 минута |
| contact | Менее 1 минуты | 3 минуты |
| conversation | Неизвестно | Неизвестно |
| conversationMember | Менее 10 секунд | 60 минут |
| driveItem | Менее 1 минуты | 5 минут |
| event | Неизвестно | Неизвестно |
| group | Неизвестно | Неизвестно |
| list | Менее 1 минуты | 5 минут |
| 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 Задержка, предоставляемая для ресурса оповещений , применяется только после создания оповещения. Он не включает время, необходимое правилу для создания оповещений на основе данных.
Примеры кода
Указанные ниже примеры кода доступны на сайте GitHub.
- Обучающий модуль по Microsoft Graph: использование уведомлений об изменениях и отслеживание изменений с помощью Microsoft Graph
- Пример веб-перехватчиков Microsoft Graph для Node.js
- Пример веб-перехватчиков Microsoft Graph для ASP.NET Core
- Пример веб-перехватчиков Microsoft Graph для Java Spring