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

Статья
03/26/2023

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

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

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

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

Примечание. К этому API применяются требования лицензирования и оплаты. Он поддерживает параметры запроса model=A и model=B. Если модель не указана, будет использоваться режим оценки.

Разрешения

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

Пример

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

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

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

Примечание. К этому API применяются требования лицензирования и оплаты. Он поддерживает параметры запроса model=A и model=B. Если модель не указана, будет использоваться режим оценки.

Разрешения

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

Пример

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

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

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

Подписки на уровне канала также поддерживают поиск на основе ключевых слов с помощью параметра запроса $search.

Разрешения

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

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

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

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

Следующий запрос отправляет сообщения, содержащие Hello подписчику.

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

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

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Чтобы получать уведомления только о сообщениях, в которых упоминался определенный пользователь, укажите ИД пользователя (9a6eb4d1-826b-48b1-9627-b50836c8fee9 в этом примере) в запросе.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Чтобы отслеживать сообщения в чате, вы можете создать подписку на уведомления об изменениях на уровне чата. Для этого подпишитесь на /chats/{chat-id}/messages. Этот ресурс поддерживает включение данных ресурса в уведомление как в делегированном режиме, так и в режиме только для приложений.

Подписки на уровне чата также поддерживают поиск на основе ключевых слов с помощью параметра запроса $search.

Разрешения

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

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

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

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

Следующий запрос отправляет сообщения, содержащие Hello подписчику.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages?$search=Hello",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Чтобы отслеживать сообщения во всех чатах, в которые входит определенный пользователь, можно создать подписку на уведомления об изменениях на уровне пользователя. Для этого подпишитесь на /users/{user-id}/chats/getAllMessages. Этот ресурс поддерживает включение данных ресурса в уведомление как в делегированном режиме, так и в режиме только для приложений.

Подписки на сообщения чата на уровне пользователя также поддерживают поиск на основе ключевых слов с помощью параметра запроса $search.

Примечание. К этому API применяются требования лицензирования и оплаты. Он поддерживает параметр запроса model=B. Если модель не указана, будет использоваться режим оценки.

Разрешения

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

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

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

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

Примечание. Этот тип ресурса в настоящее время находится в предварительной версии.

Примечание. К этому API применяются требования лицензирования и оплаты. Он поддерживает параметр запроса model=B. Если модель не указана, будет использоваться режим оценки.

Разрешения

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

Пример

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/appCatalogs/teamsApps/386bbcdb-1e1c-4f3f-b7d0-ad7b9ea6cf7c/installedToChats/getAllMessages",
  "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": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.chatMessage",
            "@odata.id": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

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

{
  "id": "1612289992105",
  "replyToId": null,
  "etag": "1612289992105",
  "messageType": "message",
  "createdDateTime": "2021-02-02T18:19:52Z",
  "lastModifiedDateTime": "2021-02-02T18:19:52.105Z",
  "lastEditedDateTime": null,
  "deletedDateTime": null,
  "subject": null,
  "summary": null,
  "chatId": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces",
  "importance": "normal",
  "locale": "en-us",
  "webUrl": null,
  "from": {
    "application": null,
    "device": null,
    "user": {
      "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
      "displayName": "Ramjot Singh",
      "userIdentityType": "aadUser"
    },
    "conversation": null
  },
  "body": {
    "contentType": "text",
    "content": "test"
  },
  "channelIdentity": null,
  "attachments": [],
  "mentions": [],
  "policyViolation": null,
  "reactions": [],
  "replies": [],
  "hostedContents": []
}

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

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

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

 {
  "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')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.chatMessage",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')"
  }
}

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

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

Разрешения

Пример

Разрешения

Пример

Разрешения

Разрешения

Разрешения

Разрешения

Пример

Полезные данные уведомлений

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

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

См. также

Дополнительные ресурсы

Дополнительные ресурсы

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

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

Подписка на сообщения во всех каналах

Разрешения

Пример

Подписка на сообщения во всех чатах

Разрешения

Пример

Подписка на сообщения в канале

Разрешения

Пример 1. Подписка на все сообщения (и ответы) в канале

Пример 2. Подписка на сообщения (и ответы) в канале, содержащие определенный текст

Пример 3. Подписка на сообщения (и ответы) в канале без данных ресурса

Пример 4. Подписка на сообщения (и ответы) в канале с упоминанием определенного пользователя

Подписка на сообщения в чате

Разрешения

Пример 1. Подписка на сообщения в чате

Пример 2. Подписка на сообщения в чате, содержащие определенный текст

Пример 3. Подписка на сообщения (и ответы) в чате без данных ресурса

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

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

Разрешения

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

Подписка на сообщения любого чата в клиенте, где установлено определенное приложение Teams (предварительная версия)

Разрешения

Пример

Полезные данные уведомлений

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

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

См. также

Дополнительные ресурсы

Дополнительные ресурсы