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

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

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

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

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

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

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

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

Разрешения

Пример

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. Если модель не указана, будет использоваться режим оценки.

Разрешения

Пример

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.

Разрешения

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

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

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}"
}

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

Следующий запрос отправляет сообщения, содержащие 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}"
}

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

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}"
}

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

Чтобы получать уведомления только о сообщениях, в которых упоминался определенный пользователь, укажите ИД пользователя (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.

Разрешения

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

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

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}"
}

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

Следующий запрос отправляет сообщения, содержащие 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}"
}

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

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}"
}

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

Чтобы получать уведомления только о сообщениях, в которых упоминался определенный пользователь, укажите ИД пользователя (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": "/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. Если модель не указана, будет использоваться режим оценки.

Разрешения

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

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

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

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

Разрешения

Пример

POST https://graph.microsoft.com/v1.0/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 всегда возвращают текущее состояние сообщения. Если сообщение изменяется между отправкой уведомления и его получением, операция возвращает обновленное сообщение.

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

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