Получение уведомлений об изменениях с помощью API Microsoft Graph

  • Статья

Пространство имен: microsoft.graph

REST API Microsoft Graph использует механизм веб-перехватчиков для доставки уведомлений об изменениях клиентам. Клиент — это веб-служба, которая настраивает свой URL-адрес для получения уведомлений. С помощью уведомлений клиентские приложения обновляют свое состояние при изменениях. Дополнительные сведения, включая сведения о подписке и обработке входящих уведомлений, см. в статье Настройка уведомлений об изменениях в пользовательских данных.

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

Примечание.

Подписки на ресурсы, помеченные звездочкой (*), доступны только в конечной точке /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		 Квоты максимальной подписки:
  • На приложение (для всех клиентов вместе взятых): 50 000 подписок.
  • На клиента (для всех приложений вместе взятых): 1000 подписок во всех приложениях.
  • На сочетание приложения и клиента: 100 подписок.

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

    Известная проблема, связанная с изменением типа подписки.
    		•
    список на сайте 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}    		 -
    callRecord в Teams Изменения во всех записях звонков: /communications/callRecords Квоты максимальной подписки:
  • На организацию: всего 100 подписок.
    		•
    Чат Teams Изменения в любом чате в клиенте: /chats

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

    Изменения во всех чатах в организации, где установлено определенное приложение Teams: /appCatalogs/teamsApps/{id}/installedToChats    		 Квоты максимальной подписки:
  • Для каждого приложения и чата: 1 подписка.
  • На организацию: всего 10 000 подписок.
    		•
    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

    Изменения членства во всех чатах: /teams/getAllMembers    		 Квоты максимальной подписки:
  • Для каждого приложения и команды: 1 подписка.
  • На организацию: всего 10 000 подписок.
    		•
    Teams onlineMeeting* Изменения в онлайн-собрании: /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl}
    presence в Teams Изменения в присутствии одного пользователя: /communications/presences/{id}

    Изменения в присутствии нескольких пользователей: /communications/presences?$filter=id in ({id},{id}...)
    Команда Teams Изменения в любой команде в клиенте: /teams

    Изменения в конкретной команде: /teams/{id}    		 Квоты максимальной подписки:
  • Для каждого приложения и команды: 1 подписка.
  • На организацию: всего 10 000 подписок.
    		•
    todoTask Изменения для всех задач в определенном списке задач: /me/todo/lists/{todoTaskListId}/tasks -
    user Изменения для всех пользователей: /users

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

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

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

    Известная проблема, связанная с изменением типа подписки.
    		•

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

    Примечание. Любой путь ресурса, начинающийся с /users/{id}, может принимать /me для указания вошедшего пользователя.

    Разрешения

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

    Тип разрешения Поддерживаемые типы ресурсов
    Делегированное — рабочая или учебная учетная запись alert, channel, contact, conversation, conversationMember, driveItem, event, group, list, message, team, todoTask, user
    Делегированное — личная учетная запись Майкрософт contact, driveItem, event, list, message, todoTask
    Application alert, callRecord, channel, chatMessage, contact, conversationMember, driveItem, event, group, list, message, printer, printTaskDefinition, team, user

    См. также