Обновление подписки
Пространство имен: microsoft.graph
Важно!
API версии /beta
в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Возобновление подписки путем увеличения срока действия.
В таблице в разделе Разрешения перечислены ресурсы, поддерживающие подписку на уведомления об изменениях.
Срок действия подписок истекает через период времени, который зависит от типа ресурса. Чтобы избежать отсутствия уведомлений об изменениях, приложение должно продлевать свои подписки заблаговременно до даты окончания срока действия. Сведения о максимальной длине подписки для каждого типа ресурсов см. в разделе Подписка .
Этот API доступен в следующих национальных облачных развертываниях.
Глобальная служба | Правительство США L4 | Правительство США L5 (DOD) | Китай управляется 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Разрешения
В зависимости от ресурса и типа требующегося разрешения (делегированное или для приложения) разрешение, указанное в приведенной ниже таблице, является наименее привилегированным разрешением, необходимым для вызова этого API. Чтобы получить дополнительные сведения, в том числе о соблюдении осторожности перед выбором разрешений с повышенными привилегиями, найдите следующие разрешения в разделе Разрешения.
Примечание.
Некоторые ресурсы поддерживают уведомления об изменениях в нескольких сценариях, каждый из которых может требовать разных разрешений. В таких случаях используйте путь к ресурсу, чтобы дифференцировать сценарии.
Поддерживаемый ресурс | Делегированное (рабочая или учебная учетная запись) | Делегированное (личная учетная запись Майкрософт) | Приложение |
---|---|---|---|
ApprovalItems | Не поддерживается. | Не поддерживается. | ApprovalSolution.ReadWrite.All |
callRecord | Не поддерживается. | Не поддерживается. | 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 |
callRecording appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings Запись звонков, которая становится доступной на собрании, где установлено определенное приложение Teams. |
Не поддерживается. | Не поддерживается. | OnlineMeetingRecording.Read.All, OnlineMeetingRecording.Read.Chat |
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 |
callTranscript appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts Расшифровка звонка, которая становится доступной на собрании, где установлено определенное приложение Teams. |
Не поддерживается. | Не поддерживается. | OnlineMeetingTranscript.Read.All, OnlineMeetingTranscript.Read.Chat |
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 /chats Все чаты в организации. |
Не поддерживается. | Не поддерживается. | Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
chat /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, Group.Read.All, Group.ReadWrite.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/getAllMembers Участники во всех командах в организации. |
Не поддерживается. | Не поддерживается. | TeamMember.Read.All, TeamMember.ReadWrite.All |
conversationMember /teams/{id}/members Участники определенной команды. |
TeamMember.Read.All | Не поддерживается. | TeamMember.Read.All |
conversationMember /teams/{id}/channels/getAllMembers Участники всех частных каналов определенной команды. |
Не поддерживается. | Не поддерживается. | ChannelMember.Read.All |
conversationMember /teams/getAllChannels/getAllMembers |
Не поддерживается. | Не поддерживается. | ChannelMember.Read.All |
driveItem (личное хранилище OneDrive пользователя) | Не поддерживается. | Files.ReadWrite | Не поддерживается. |
driveItem (OneDrive для работы или учебы) | Files.ReadWrite.All | Не поддерживается. | Files.ReadWrite.All |
event | Calendars.Read | Calendars.Read | Calendars.Read |
group | Group.Read.All | Не поддерживается. | Group.Read.All |
group conversation | Group.Read.All | Не поддерживается. | Не поддерживается. |
list | Sites.ReadWrite.All | Не поддерживается. | Sites.ReadWrite.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 |
собрание по сети | Не поддерживается. | Не поддерживается. | OnlineMeetings.Read.All, OnlineMeetings.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 |
team /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 | Не поддерживается. |
user | User.Read.All | User.Read.All | User.Read.All |
virtualEventWebinar | VirtualEvent.Read | Не поддерживается. | VirtualEvent.Read.All |
baseTask (не рекомендуется) | Tasks.ReadWrite | Tasks.ReadWrite | Не поддерживается. |
Примечание.
Следующие разрешения используют согласие для конкретного ресурса:
- OnlineMeetingRecording.Read.Chat
- OnlineMeetingTranscript.Read.Chat
- ChatSettings.Read.Chat
- ChatSettings.ReadWrite.Chat
- Chat.Manage.Chat
- ChannelMessage.Read.Group
- ChatMember.Read.Chat
chatMessage
Подписки chatMessage можно указать, чтобы включить данные ресурсов. Если задано включение данных ресурсов (includeResourceData имеет значение true
), требуется шифрование. Подписку нельзя создать, если для таких подписок не указан encryptionCertificate.
Необходимо использовать Prefer: include-unknown-enum-members
заголовок запроса, чтобы получить следующие значения в перечислении chatMessagemessageTypeс возможностью развития: systemEventMessage
for /teams/{id}/channels/{id}/messages
и /chats/{id}/messages
resource.
Примечание.
/teams/getAllMessages
, /chats/getAllMessages
, /me/chats/getAllMessages
, /users/{id}/chats/getAllMessages
и /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
являются лимитными API; могут применяться модели оплаты и требования к лицензированию .
/teams/getAllMessages
и /chats/getAllMessages
поддерживают как model=A
model=B
модели оплаты, /me/chats/getAllMessages
так и , /users/{id}/chats/getAllMessages
и /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
поддерживают только model=B
.
Если в запросе не указана модель оплаты, будет использоваться режим оценки по умолчанию.
Примечание.
Чтобы добавить или изменить модель оплаты для подписанного ресурса уведомления об изменениях, необходимо создать новую подписку на уведомление об изменениях с новой моделью оплаты. Обновление существующего уведомления об изменениях не работает.
conversationMember
Подписки conversationMember можно указать для включения данных ресурсов. Если задано включение данных ресурсов (includeResourceData имеет значение true
), требуется шифрование. Создание подписки завершается сбоем, если не указан encryptionCertificate.
Примечание.
/teams/getAllMembers
, /chats/getAllMembers
и /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
являются лимитными API- интерфейсами; могут применяться модели оплаты и требования к лицензированию .
/teams/getAllMembers
и /chats/getAllMembers
поддерживают как модели оплаты, так model=A
и model=B
.
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
поддерживает только model=B
.
Если в запросе не указана модель оплаты, будет использоваться режим оценки по умолчанию.
Примечание.
Чтобы добавить или изменить модель оплаты для подписанного ресурса уведомления об изменениях, необходимо создать новую подписку на уведомление об изменениях с новой моделью оплаты. Обновление существующего уведомления об изменениях не работает.
команда, канал и чат
Подписки на команды, каналы и чат можно указать для включения данных ресурсов. Если задано включение данных ресурсов (includeResourceData имеет значение true
), требуется шифрование. Создание подписки завершается сбоем, если не указан encryptionCertificate.
Параметр строки запроса notifyOnUserSpecificProperties можно использовать при подписке на изменения в определенном чате или на уровне пользователя. Если параметр строки запроса notifyOnUserSpecificPropertiestrue
задан во время создания подписки, подписчику отправляются два типа полезных данных. Один тип содержит свойства, зависящие от пользователя, а другой отправляется без них. Дополнительные сведения см. в статье Получение уведомлений об изменениях для чатов с помощью Microsoft Graph.
Примечание.
/appCatalogs/teamsApps/{id}/installedToChats
имеет требования к лицензированию и оплате, в частности, поддерживает только model=B
.
Если модель не указана, будет использоваться режим оценки.
Примечание.
Чтобы добавить или изменить модель оплаты для подписанного ресурса уведомления об изменениях, необходимо создать новую подписку на уведомление об изменениях с новой моделью оплаты. Обновление существующего уведомления об изменениях не работает.
Пример запроса
Укажите параметр запроса model
в свойстве ресурса в тексте запроса.
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
"changeType": "created",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"resource": "chats/getAllMessages?model=A",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"clientState": "secretClientValue",
"latestSupportedTlsVersion": "v1_2"
}
driveItem
К подпискам на элементы OneDrive применяются дополнительные ограничения. Ограничения применяются для создания, а также управления (получение, обновление и удаление) подписками.
В личном хранилище OneDrive можно подписаться на корневую папку или любую вложенную папку в этом хранилище. В OneDrive для работы или учебы можно подписаться только на корневую папку. Уведомления об изменениях отправляются для запрошенных изменений в папке с подпиской или любом файле, папке или других экземплярах driveItem в ее иерархии. Вы не можете подписаться на экземпляры drive или driveItem , которые не являются папками, например на отдельные файлы.
contact, event и message
Вы можете подписаться на изменения в ресурсах контактов, событий или сообщений Outlook и при необходимости указать в полезных данных запроса POST, включать ли зашифрованные данные ресурсов в уведомления.
Для операций создания и управления (получение, обновление и удаление) подписке требуется область чтения ресурса. Например, чтобы получать уведомления об изменениях в сообщениях, приложению необходимо разрешение Mail.Read. Уведомления об изменениях Outlook поддерживают области делегированных разрешений и разрешений приложений. Обратите внимание на указанные ниже ограничения.
Делегированные разрешения поддерживают подписку на элементы в папках только в почтовом ящике пользователя, выполнившего вход. Например, вы не можете использовать делегированное разрешение Calendars.Read для подписки на события в почтовом ящике другого пользователя.
Чтобы подписаться на уведомления об изменениях контактов Outlook, событий или сообщений в общих или делегированных папках:
- Используйте соответствующее разрешение приложения для подписки на изменения элементов в папке или почтовом ящике любого пользователя в клиенте.
- Не используйте разрешения на общий доступ Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared и их коллеги на чтение и запись), так как они не поддерживают подписку на уведомления об изменении элементов в общих или делегированных папках.
onlineMeetings, присутствие
OnlineMeeting и подписки присутствия требуют шифрования для уведомлений с данными ресурсов. Создание подписки завершается сбоем , если шифрованиеCertificate и encryptionCertificateId не указано, если данные ресурса нужны в уведомлениях. Дополнительные сведения о присутствии и подписках на собрания по сети см. в разделах Получение уведомлений об изменениях для обновлений присутствия в Microsoft Teams и Получение уведомлений об изменениях для собраний по сети.
virtualEventWebinar
Подписки на виртуальные события поддерживают только базовые уведомления и ограничены несколькими сущностями виртуального события. Дополнительные сведения о поддерживаемых типах подписок см. в статье Получение уведомлений об изменениях для обновлений виртуальных событий Microsoft Teams.
HTTP-запрос
PATCH /subscriptions/{id}
Заголовки запросов
Имя | Тип | Описание |
---|---|---|
Authorization | string | Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Текст запроса
Укажите в тексте запроса только значения обновляемых свойств. Существующие свойства, которые не включены в текст запроса, сохраняют свои предыдущие значения или пересчитываются на основе изменений других значений свойств.
В следующей таблице указаны свойства, которые можно обновить.
Имя | Тип | Описание |
---|---|---|
expirationDateTime | DateTimeOffset | Указывает дату и время окончания срока действия подписки в формате UTC. Для максимальной поддерживаемой подписки продолжительность времени зависит от ресурса. |
Отклик
В случае успеха этот метод возвращает код отклика 200 OK
и объект subscription в тексте отклика.
Подробнее о том, как возвращаются ошибки, см. в статье Возвращение ошибок.
Пример
Запрос
Ниже показан пример запроса.
PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-type: application/json
{
"expirationDateTime":"2016-11-22T18:23:45.9356913Z"
}
Отклик
Ниже приводится пример отклика.
HTTP/1.1 200 OK
Content-type: application/json
{
"id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
"resource":"me/messages",
"applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
"changeType":"created,updated",
"clientState":"secretClientValue",
"notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
"lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
"expirationDateTime":"2016-11-22T18:23:45.9356913Z",
"creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
"latestSupportedTlsVersion": "v1_2",
"encryptionCertificate": "",
"encryptionCertificateId": "",
"includeResourceData": false,
"notificationContentType": "application/json"
}