Поделиться через


Обновление подписки

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

Возобновление подписки путем увеличения срока действия.

В таблице в разделе Разрешения перечислены ресурсы, поддерживающие подписку на уведомления об изменениях.

Срок действия подписок истекает через период времени, который зависит от типа ресурса. Чтобы избежать отсутствия уведомлений об изменениях, приложение должно продлевать свои подписки заблаговременно до даты окончания срока действия. Сведения о максимальной длине подписки для каждого типа ресурсов см. в разделе Подписка .

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet

Разрешения

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

Поддерживаемый ресурс Делегированное (рабочая или учебная учетная запись) Делегированное (личная учетная запись Майкрософт) Приложение
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
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
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.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.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
presence Presence.Read.All Не поддерживается. Не поддерживается.
printer Не поддерживается Не поддерживается Printer.Read.All, Printer.ReadWrite.All
printTaskDefinition Не поддерживается Не поддерживается PrintTaskDefinition.ReadWrite.All
security alert SecurityEvents.ReadWrite.All Не поддерживается SecurityEvents.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
todoTask Tasks.ReadWrite Tasks.ReadWrite Не поддерживается
user User.Read.All User.Read.All User.Read.All
virtualEventWebinar VirtualEvent.Read Не поддерживается. VirtualEvent.Read.All

Примечание. Разрешения, помеченные звездочкой (*), используют согласие для конкретных ресурсов.

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=Amodel=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 contact, event или message.

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

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

  • Чтобы подписаться на уведомления об изменениях контактов Outlook, событий или сообщений в общих или делегированных папках:

    • Используйте соответствующее разрешение приложения для подписки на изменения элементов в папке или почтовом ящике любого пользователя в клиенте.
    • Не используйте разрешения на общий доступ Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared и их коллеги на чтение и запись), так как они не поддерживают подписку на уведомления об изменении элементов в общих или делегированных папках.

presence

Для подписок присутствия требуется шифрование уведомлений, включающих данные ресурсов. Создание подписки завершается ошибкой, если шифрованиеCertificate и encryptionCertificateId не указаны, если уведомления должны включать данные ресурсов. Дополнительные сведения о подписках присутствия см. в статье Получение уведомлений об изменениях для обновлений присутствия в Microsoft Teams.

virtualEventWebinar

Подписки на виртуальные события поддерживают только базовые уведомления и ограничены несколькими сущностями виртуального события. Дополнительные сведения о поддерживаемых типах подписок см. в статье Получение уведомлений об изменениях для обновлений виртуальных событий Microsoft Teams.

HTTP-запрос

PATCH /subscriptions/{id}

Заголовки запросов

Имя Тип Описание
Authorization string Bearer {token}. Обязательно.

Текст запроса

Укажите в тексте запроса только значения обновляемых свойств. Существующие свойства, которые не включены в текст запроса, сохраняют свои предыдущие значения или пересчитываются на основе изменений других значений свойств.

В следующей таблице указаны свойства, которые можно обновить.

Текст запроса должен содержать по крайней мере одно из перечисленных свойств.

Имя Тип Описание
expirationDateTime DateTimeOffset Указывает дату и время окончания срока действия подписки в формате UTC. Максимальный поддерживаемый период времени подписки зависит от ресурса.
notificationUrl Строка Этот URL-адрес должен использовать протокол HTTPS. Любой параметр строки запроса, включенный в свойство notificationUrl, включается в HTTP-запрос POST, когда Microsoft Graph отправляет уведомления об изменениях.

Отклик

В случае успеха этот метод возвращает код отклика 200 OK и объект subscription в тексте отклика.

Подробнее о том, как возвращаются ошибки, см. в статье Возвращение ошибок.

Пример

Запрос

Ниже показан пример запроса.

PATCH https://graph.microsoft.com/v1.0/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":"subscription-identifier",
  "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"
}