Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Пространство имен: microsoft.graph
Создание подписки для приложения прослушивателя, позволяющей ему получать уведомления об изменениях определенного типа в указанном ресурсе в Microsoft Graph.
Сведения о ресурсах, для которых можно создавать подписки, и ограничениях на подписки см. в статье Настройка уведомлений об изменениях в данных ресурсов: поддерживаемые ресурсы.
Некоторые ресурсы поддерживают расширенные уведомления, то есть уведомления, включающие данные ресурсов. Дополнительные сведения об этих ресурсах см. в разделе Настройка уведомлений об изменениях, включающих данные ресурсов: поддерживаемые ресурсы.
Этот API доступен в следующих национальных облачных развертываниях.
| Глобальная служба | Правительство США L4 | Правительство США L5 (DOD) | Китай управляется 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Разрешения
Чтобы создать подписку, приложение должно иметь разрешения на чтение для ресурса. Например, чтобы получать уведомления об изменениях для сообщений, приложению требуется Mail.Read разрешение.
В зависимости от ресурса и типа требующегося разрешения (делегированное или для приложения) разрешение, указанное в приведенной ниже таблице, является наименее привилегированным разрешением, необходимым для вызова этого API. Чтобы узнать больше, в том числе, как соблюдать осторожность перед выбором разрешений, найдите следующие разрешения в Разрешениях.
| Поддерживаемый ресурс | Делегированное (рабочая или учебная учетная запись) | Делегированное (личная учетная запись Майкрософт) | Приложение |
|---|---|---|---|
aiInteraction copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions Взаимодействие с ИИ Copilot, частью чего является конкретный пользователь. |
AiEnterpriseInteraction.Read | Не поддерживается. | AiEnterpriseInteraction.Read.All, AiEnterpriseInteraction.Read.User |
aiInteraction copilot/interactionHistory/getAllEnterpriseInteractions Взаимодействие с ИИ Copilot в организации. |
Не поддерживается. | Не поддерживается. | AiEnterpriseInteraction.Read.All |
| callRecord (/communications/callRecords) | Не поддерживается | Не поддерживается | CallRecords.Read.All |
callRecording communications/onlineMeetings/getAllRecordings Все записи в организации. |
Не поддерживается. | Не поддерживается. | OnlineMeetingRecording.Read.All |
callRecording communications/onlineMeetings/{onlineMeetingId}/recordings Все записи для определенного собрания. |
OnlineMeetingRecording.Read.All | Не поддерживается. | OnlineMeetingRecording.Read.All |
callRecording users/{userId}/onlineMeetings/getAllRecordings Запись звонка, которая становится доступной на собрании, организованном определенным пользователем. |
OnlineMeetingRecording.Read.All | Не поддерживается. | OnlineMeetingRecording.Read.All |
callTranscript communications/onlineMeetings/getAllTranscripts Все расшифровки в организации. |
Не поддерживается. | Не поддерживается. | OnlineMeetingTranscript.Read.All |
callTranscript communications/onlineMeetings/{onlineMeetingId}/transcripts Все стенограммы для определенного собрания. |
OnlineMeetingTranscript.Read.All | Не поддерживается. | OnlineMeetingTranscript.Read.All |
callTranscript users/{userId}/onlineMeetings/getAllTranscripts Расшифровка звонка, которая становится доступной на собрании, организованном определенным пользователем. |
OnlineMeetingTranscript.Read.All | Не поддерживается. | OnlineMeetingTranscript.Read.All |
| channel (/teams/getAllChannels — все каналы в организации) | Не поддерживается | Не поддерживается | Channel.ReadBasic.All, ChannelSettings.Read.All |
| channel (/teams/{id}/channels) | Channel.ReadBasic.All, ChannelSettings.Read.All | Не поддерживается | Channel.ReadBasic.All, ChannelSettings.Read.All |
| чат (/чаты — все чаты в организации) | Не поддерживается | Не поддерживается | Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
| чат (/chats/{id}) | Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Не поддерживается | ChatSettings.Read.Chat*, ChatSettings.ReadWrite.Chat*, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
|
chat /appCatalogs/teamsApps/{id}/installedToChats Все чаты в организации, где установлено определенное приложение Teams. |
Не поддерживается | Не поддерживается | Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled |
chat /users/{id}/chats Все чаты, частью которыми является конкретный пользователь. |
Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Не поддерживается. | Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
| chatMessage (/teams/{id}/channels/{id}/messages) | ChannelMessage.Read.All | Не поддерживается | ChannelMessage.Read.Group*, ChannelMessage.Read.All |
| chatMessage (/teams/getAllMessages — все сообщения канала в организации) | Не поддерживается | Не поддерживается | ChannelMessage.Read.All |
| chatMessage (/chats/{id}/messages) | Chat.Read, Chat.ReadWrite | Не поддерживается | Chat.Read.All |
| chatMessage (/chats/getAllMessages — все сообщения чата в организации) | Не поддерживается | Не поддерживается | Chat.Read.All |
| chatMessage (/users/{id}/chats/getAllMessages — сообщения чата для всех чатов, в которые входит определенный пользователь) | Chat.Read, Chat.ReadWrite | Не поддерживается | Chat.Read.All, Chat.ReadWrite.All |
|
chatMessage /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages Сообщения чата для всех чатов в организации, где установлено определенное приложение Teams. |
Не поддерживается | Не поддерживается | Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled |
| contact | Contacts.Read | Contacts.Read | Contacts.Read |
| conversationMember (/chats/getAllMembers) | Не поддерживается | Не поддерживается | ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
| conversationMember (/chats/{id}/members) | ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Не поддерживается | ChatMember.Read.Chat*, Chat.Manage.Chat*, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
|
conversationMember /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers Участники чата для всех чатов в организации, в которой установлено определенное приложение Teams. |
Не поддерживается. | Не поддерживается. | ChatMember.Read.WhereInstalled, ChatMember.ReadWrite.WhereInstalled, Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled |
| conversationMember (/teams/{id}/members) | TeamMember.Read.All | Не поддерживается | TeamMember.Read.All |
| conversationMember (/teams/{id}/channels/getAllMembers) | Не поддерживается | Не поддерживается | ChannelMember.Read.All |
| driveItem (личное хранилище OneDrive пользователя) | Не поддерживается | Files.Read | Не поддерживается |
| driveItem (OneDrive для бизнеса) | Files.Read.All | Не поддерживается | Files.Read.All |
| event | Calendars.Read | Calendars.Read | Calendars.Read |
| group | Group.Read.All | Не поддерживается | Group.Read.All |
| group conversation | Group.Read.All | Не поддерживается | Не поддерживается |
| list | Sites.Read.All | Не поддерживается | Sites.Read.All |
| message | Mail.ReadBasic, Mail.Read | Mail.ReadBasic, Mail.Read | Mail.Read |
|
offerShiftRequest (/teams/{id}/schedule/offerShiftRequests) Изменения в любом запросе на смену предложения в команде. |
Schedule.Read.All, Schedule.ReadWrite.All | Не поддерживается. | Schedule.Read.All, Schedule.ReadWrite.All |
|
openShiftChangeRequest (/teams/{id}/schedule/openShiftChangeRequests) Изменения в любом запросе на открытые смены в команде. |
Schedule.Read.All, Schedule.ReadWrite.All | Не поддерживается. | Schedule.Read.All, Schedule.ReadWrite.All |
| presence | Presence.Read.All | Не поддерживается | Не поддерживается |
| printer | Не поддерживается | Не поддерживается | Printer.Read.All, Printer.ReadWrite.All |
| printTaskDefinition | Не поддерживается | Не поддерживается | PrintTaskDefinition.ReadWrite.All |
| security alert | SecurityEvents.ReadWrite.All | Не поддерживается | SecurityEvents.ReadWrite.All |
|
shift (/teams/{id}/schedule/shifts) Изменения в любой смене в команде. |
Schedule.Read.All, Schedule.ReadWrite.All | Не поддерживается. | Schedule.Read.All, Schedule.ReadWrite.All |
|
swapShiftsChangeRequest (/teams/{id}/schedule/swapShiftsChangeRequests) Изменения в любом запросе на смену переключения в команде. |
Schedule.Read.All, Schedule.ReadWrite.All | Не поддерживается. | Schedule.Read.All, Schedule.ReadWrite.All |
| teams (/teams — все команды в организации) | Не поддерживается | Не поддерживается | Team.ReadBasic.All, TeamSettings.Read.All |
| team (/teams/{id}) | Team.ReadBasic.All, TeamSettings.Read.All | Не поддерживается | Team.ReadBasic.All, TeamSettings.Read.All |
|
timeOffRequest (/teams/{id}/schedule/timeOffRequests) Изменения в любом запросе на отгул в команде. |
Schedule.Read.All, Schedule.ReadWrite.All | Не поддерживается. | Schedule.Read.All, Schedule.ReadWrite.All |
| todoTask | Tasks.ReadWrite | Tasks.ReadWrite | Tasks.ReadWrite.All |
| user | User.Read.All | User.Read.All | User.Read.All |
| virtualEventWebinar | VirtualEvent.Read | Не поддерживается. | VirtualEvent.Read.All |
| virtualEventTownhall | VirtualEvent.Read | Не поддерживается. | VirtualEvent.Read.All |
Рекомендуется использовать разрешения, как описано в предыдущей таблице. Из-за ограничений безопасности подписки Microsoft Graph не поддерживают разрешения на доступ на запись, если требуются только разрешения на чтение.
Примечание. Разрешения, помеченные звездочкой (*), используют согласие для конкретных ресурсов.
chatMessage
Подписки chatMessage можно указать для включения данных ресурсов (параметр includeResourceData имеет значение true). В этом случае требуется шифрование, и создание подписки завершается сбоем, если для таких подписок не указан сертификат шифрования .
Prefer: include-unknown-enum-members Используйте заголовок запроса, чтобы получить следующие значения в перечислении chatMessagemessageTypeс возможностью развития: systemEventMessage for /teams/{id}/channels/{id}/messages и /chats/{id}/messages resource.
conversationMember
Подписки conversationMember можно указать для включения данных ресурсов (параметр includeResourceData имеет значение true). В этом случае требуется шифрование, и создание подписки завершается сбоем, если для таких подписок не указан сертификат шифрования .
команда, канал и чат
Подписки команд, каналов и чатов можно указать для включения данных ресурсов (параметр includeResourceData имеет значение true). В этом случае требуется шифрование, и создание подписки завершается сбоем, если для таких подписок не указан сертификат шифрования .
Параметр строки запроса notifyOnUserSpecificProperties можно использовать при подписке на изменения в определенном чате или на уровне пользователя. Если параметр строки запроса notifyOnUserSpecificPropertiestrue задан во время создания подписки, подписчику отправляются два типа полезных данных. Один тип содержит свойства, зависящие от пользователя, а другой отправляется без них. Дополнительные сведения см. в статье Получение уведомлений об изменениях для чатов с помощью Microsoft Graph.
aiInteraction
Для подписок на взаимодействие с ИИ Copilot требуется действительная лицензия Copilot, которая включает следующий план обслуживания Copilot:
- Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
Для подписок, предназначенных для взаимодействия с ИИ Copilot, частью которых является конкретный пользователь, пользователю в пути к ресурсу должны быть назначены предыдущие планы обслуживания в допустимом состоянии.
Для подписок, предназначенных для взаимодействия Copilot AI для всего клиента, клиент должен иметь действительные лицензии, которые включают все предыдущие планы обслуживания Copilot.
driveItem
Дополнительные ограничения применяются к подпискам на элементы OneDrive. Ограничения применяются для создания, а также управления (получение, обновление и удаление) подписками.
В личном хранилище OneDrive можно подписаться на корневую папку или любую вложенную папку в этом хранилище. В OneDrive для бизнеса можно подписаться только на корневую папку. Уведомления об изменениях отправляются для определенных типов изменений папки, на которую оформлена подписка, любого файла, папки или других экземпляров driveItem в ее иерархии. Вы не можете подписаться на экземпляры drive или driveItem , которые не являются папками, например на отдельные файлы.
OneDrive для бизнеса и SharePoint поддерживают отправку уведомлений приложений о событиях безопасности, которые происходят в driveItem. Чтобы подписаться на эти события, добавьте заголовок prefer:includesecuritywebhooks в запрос на создание подписки. После создания подписки вы будете получать уведомления об изменениях разрешений для элемента. Этот заголовок можно использовать в SharePoint и OneDrive для бизнеса, но не в учетных записях потребителей в OneDrive.
contact, event и message
Вы можете подписаться на изменения ресурсов Outlook contact, event или message.
Для операций создания и управления (получение, обновление и удаление) подписке требуется область чтения ресурса. Например, чтобы получать уведомления об изменениях в сообщениях, приложению необходимо разрешение Mail.Read. Уведомления об изменениях Outlook поддерживают области делегированных разрешений и разрешений приложений. Обратите внимание на указанные ниже ограничения.
Делегированные разрешения поддерживают подписку на элементы в папках только в почтовом ящике пользователя, выполнившего вход. Например, вы не можете использовать делегированное разрешение Calendars.Read для подписки на события в почтовом ящике другого пользователя.
Чтобы подписаться на уведомления об изменениях контактов Outlook, событий или сообщений в общих или делегированных папках:
- Используйте соответствующее разрешение приложения для подписки на изменения элементов в папке или почтовом ящике любого пользователя в клиенте.
- Не используйте разрешения на общий доступ Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared и их коллеги на чтение и запись), так как они не поддерживают подписку на уведомления об изменении элементов в общих или делегированных папках.
presence
Подписки на присутствие требуют шифрования любых данных ресурсов, включенных в уведомление об изменении. Всегда указывайте параметр encryptionCertificate при создании подписки, чтобы избежать сбоя. Дополнительные сведения о настройке уведомлений об изменении, чтобы включить данные ресурсов.
virtualEventWebinar и virtualEventTownhall
Подписки на виртуальные события поддерживают только базовые уведомления и ограничены несколькими сущностями виртуального события. Дополнительные сведения о поддерживаемых типах подписок см. в статье Получение уведомлений об изменениях для обновлений виртуальных событий Microsoft Teams.
HTTP-запрос
POST /subscriptions
Заголовки запросов
| Имя | Тип | Описание |
|---|---|---|
| Authorization | string | Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Текст запроса
Предоставьте в тексте запроса описание объекта subscription в формате JSON.
Отклик
В случае успеха этот метод возвращает код отклика 201 Created и объект subscription в теле отклика.
Подробнее о том, как возвращаются ошибки, см. в статье Возвращение ошибок.
Пример
Запрос
В следующем примере показан запрос на отправку уведомления об изменении при получении пользователем нового сообщения.
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
"changeType": "created",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"resource": "me/mailFolders('Inbox')/messages",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"clientState": "secretClientValue",
"latestSupportedTlsVersion": "v1_2"
}
Предоставьте в тексте запроса описание объекта subscription в формате JSON.
Поля clientState и latestSupportedTlsVersion необязательны.
Поведение повторяющихся подписок
Дублирование подписок запрещено. Если запрос подписки содержит те же значения для changeType и ресурса , что и в существующей подписке, запрос завершается ошибкой с кодом 409 ConflictHTTP и сообщением Subscription Id <> already exists for the requested combinationоб ошибке .
Примеры ресурсов
Ниже приведены допустимые значения свойства ресурса для подписки.
| Тип ресурса | Примеры |
|---|---|
| Записи звонков | communications/callRecords |
| callRecording |
communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings |
| callTranscript |
communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts |
| Сообщение чата |
chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages |
| Контакты | me/contacts |
| Беседы | groups('{id}')/conversations |
| Диски | me/drive/root |
| События | me/events |
| Группы | groups |
| Список | sites/{site-id}/lists/{list-id} |
| Почта |
me/mailfolders('inbox')/messages, me/messages |
| Присутствие |
/communications/presences/{id} (один пользователь), /communications/presences?$filter=id in ('{id}','{id}',…) (несколько пользователей) |
| printer | print/printers/{id}/jobs |
| PrintTaskDefinition | print/taskDefinitions/{id}/tasks |
| Оповещение безопасности | security/alerts?$filter=status eq 'New' |
| todoTask | /me/todo/lists/{todoTaskListId}/tasks |
| Пользователи | users |
Примечание. Любой путь, начинающийся с
me, также можно использовать сusers/{id}вместоme, чтобы указать определенного пользователя, а не текущего пользователя.
Отклик
Ниже показан пример отклика.
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
"id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
"resource": "me/mailFolders('Inbox')/messages",
"applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
"changeType": "created",
"clientState": "secretClientValue",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"expirationDateTime": "2016-11-20T18:23:45.9356913Z",
"creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
"latestSupportedTlsVersion": "v1_2",
"notificationContentType": "application/json"
}
Проверка конечной точки уведомлений
Конечная точка уведомления подписки (указанная в свойстве notificationUrl) должна поддерживать ответ на запрос проверки, как описано в статье Настройка уведомлений об изменениях в пользовательских данных. Если проверка завершилась сбоем, запрос на создание подписки возвращает ошибку 400 (неверный запрос).