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

  • Статья

Уведомления об изменениях позволяют подписаться на изменения (создание, обновление и удаление) команд и каналов. Вы можете получать уведомления при создании, обновлении или удалении команды или канала . Кроме того, вы можете получать данные ресурсов в уведомлениях и, следовательно, избегать вызова API, чтобы получить полезные данные.

Перейдите к этой статье о сценариях для ресурса команды или канала . Вы также можете узнать об уведомлениях об изменениях для других ресурсов Microsoft Teams.

Примечание.

Если вы запрашиваете срок действия подпискиDateTime , который в будущем превышает 1 час, необходимо подписаться на уведомления о жизненном цикле, включив свойство lifecycleNotificationUrl в запрос подписки. В противном случае запрос подписки завершится ошибкой со следующим сообщением об ошибке: lifecycleNotificationUrl является обязательным свойством для создания подписки на этом ресурсе, если значение expirationDateTime имеет значение больше 1 часа.

Подписка на изменения в любой команде на уровне клиента

Чтобы получать уведомления обо всех изменениях (создание, обновление и удаление), связанных с любой командой в клиенте, подпишитесь на /teams. Этот ресурс поддерживает включение данных ресурса в уведомление.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Не поддерживается.
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All

Пример

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Подписка на изменения в определенной команде

Чтобы получать уведомления обо всех изменениях, связанных с определенной командой в клиенте, подпишитесь на /teams/{team-id}. Этот ресурс поддерживает включение данных ресурса в уведомление.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All
Делегированное (личная учетная запись Майкрософт) Не поддерживается.
Приложение TeamSettings.Read.Group*, TeamSettings.ReadWrite.Group*, Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All

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

Пример

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Подписка на изменения в любом канале на уровне клиента

Чтобы получать уведомления об изменениях для всех изменений (создание, обновление и удаление), связанных с любым каналом в клиенте, подпишитесь на /teams/getAllChannels. Этот ресурс поддерживает включение данных ресурса в уведомление.

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

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Не поддерживается.
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All

Пример

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/getAllChannels",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Подписка на изменения в любом канале определенной команды

Чтобы получать уведомления обо всех изменениях, связанных с любым каналом в определенной команде, подпишитесь на /teams/{team-id}/channels. Этот ресурс поддерживает включение данных ресурса в уведомление.

Ниже приведены примеры событий, которые создают уведомления для этого ресурса.

  • Отображаемое имя канала обновляется в команде.
  • В команде создается закрытый канал.
  • Общий канал, принадлежащий этой команде, является общим или не предоставляется другим командам.
  • Общий канал, принадлежащий другой команде, предоставляется этой команде.
  • Свойства канала, например isFavoriteByDefault или description, обновляются.
  • Идет удаление канала.

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

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение ChannelSettings.Read.Group*, ChannelSettings.ReadWrite.Group*, Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All

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

Пример

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Уведомления с данными ресурсов

Для уведомлений с данными ресурсов полезные данные выглядят следующим образом. Эти полезные данные относятся к изменению свойства в команде.

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.Team",
            "@odata.id": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Расшифрованные полезные данные уведомления выглядят следующим образом. Полезные данные соответствуют схеме teams. Полезные данные похожи на результаты, возвращаемые операциями GET.

Примечание.DiscoverySettings и classSettings не предоставляются в полезных данных.

{
  "id": "4c533ad3-e1dd-4277-a672-92ab64ed225c",
  "createdDateTime": "2021-03-18T10:31:14.597Z",
  "displayName": "Sample name",
  "description": "Sample description",
  "internalId": "19:2077546f765a42c1ba71236f4df70aa2@thread.tacv2",
  "specialization": "none",
  "visibility": "public",
  "webUrl": "https://teams.microsoft.com/l/team/19:2077546f724a42c1ba71236f4df79aa2%40thread.tacv2/conversations?groupId=4c533ad3-e1dd-4277-a672-92ab64ed225c&tenantId=0f2e8f59-862a-483b-9ca8-82a10665e17d",
  "isArchived": false,
  "isMembershipLimitedToOwners": false,
  "memberSettings": {
    "allowCreateUpdateChannels": true,
    "allowCreatePrivateChannels": true,
    "allowDeleteChannels": true,
    "allowAddRemoveApps": true,
    "allowCreateUpdateRemoveTabs": true,
    "allowCreateUpdateRemoveConnectors": true
  },
  "guestSettings": {
    "allowCreateUpdateChannels": false,
    "allowDeleteChannels": false
  },
  "messagingSettings": {
    "allowUserEditMessages": true,
    "allowUserDeleteMessages": true,
    "allowOwnerDeleteMessages": true,
    "allowTeamMentions": true,
    "allowChannelMentions": true
  },
  "funSettings": {
    "allowGiphy": true,
    "giphyContentRating": "moderate",
    "allowStickersAndMemes": true,
    "allowCustomMemes": true
  }
}

Для уведомлений с данными ресурсов полезные данные выглядят следующим образом. Эти полезные данные относятся к изменению свойства в канале.

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')/channels('19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2')",
        "resourceData": {
            "id": "19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2",
            "@odata.type": "#Microsoft.Graph.Channel",
            "@odata.id": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')/channels('19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Расшифрованные полезные данные уведомления выглядят следующим образом. Полезные данные соответствуют схеме channel. Полезные данные похожи на результаты, возвращаемые операциями GET.

{
  "id": "19:a3f841d969cd4ae0a7cbe847fc10b371@thread.tacv2",
  "createdDateTime": "2020-02-14T01:10:03.592Z",
  "displayName": "General",
  "description": "Sample Channel description",
  "isFavoriteByDefault": true,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3Aa3f841d969cd4ae0a7cbe847fc10b371%40thread.tacv2/General?groupId=7ed9bdab-9c7d-4c10-a25d-3f4ff0e34577&tenantId=0f2d8f49-862a-493b-9ca8-82a10637e17d",
  "membershipType": "standard",
  "moderationSettings": null
}

Уведомления без данных о ресурсах

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

Для уведомлений без данных ресурса полезные данные выглядят следующим образом. Эти полезные данные относятся к изменению свойства в команде.

{
  "subscriptionId": "9f9d1ed0-c9cc-42e7-8d80-a7fc4b0cda3c",
  "changeType": "created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-02-02T11:26:41.0537895-08:00",
  "resource": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.Teams",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')"
  }
}

Свойства resource и @odata.id можно использовать для вызовов в Microsoft Graph, чтобы получить полезные данные для сообщения. Вызовы GET всегда возвращают текущее состояние сообщения. Если сообщение изменяется между отправкой уведомления и его получением, операция возвращает обновленное сообщение.

Примечание. Адрес электронной почты канала не возвращается в полезных данных.

Для уведомлений без данных ресурса полезные данные выглядят следующим образом. Эти полезные данные относятся к изменению свойства в команде.

{
  "id": "19:a3f841d969cd4ae0a7cbe847fc10b371@thread.tacv2",
  "createdDateTime": "2020-02-14T01:10:03.592Z",
  "displayName": "General",
  "description": "Sample Channel description",
  "isFavoriteByDefault": true,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3Aa3f841d969cd4ae0a7cbe847fc10b371%40thread.tacv2/General?groupId=7ed9bdab-9c7d-4c10-a25d-3f4ff0e34577&tenantId=0f2d8f49-862a-493b-9ca8-82a10637e17d",
  "membershipType": "standard",
  "moderationSettings": null
}

Связанные материалы