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

  • Статья

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

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

Примечание.

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

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

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

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

Разрешения

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

Пример

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

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

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

Чтобы получать уведомления об изменениях участников определенного чата, подпишитесь на /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

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

Пример

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

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

Подпишитесь на изменения в членстве в любом чате в клиенте, где установлено приложение Teams.

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

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

Разрешения

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

Пример

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/getAllMembers",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

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

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

{
    "value": [{
        "subscriptionId": "c0125ef2-7a87-4e94-aa71-b995510f369b",
        "changeType": "Created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-06-03T11:04:58.5537601+00:00",
        "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')/members('MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyMyZmM2MDY2My0xOWEyLTRhYTQtODUyYy1mN2JhNGU5MGFkYTI=')",
        "resourceData": {
            "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyMyZmM2MDY2My0xOWEyLTRhYTQtODUyYy1mN2JhNGU5MGFkYTI=",
            "@odata.type": "#microsoft.graph.aadUserConversationMember",
            "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')/members('MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyMyZmM2MDY2My0xOWEyLTRhYTQtODUyYy1mN2JhNGU5MGFkYTI=')"
        },
        "EncryptedContent": {
            "data": "<<--EncryptedContent-->>",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

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

{
    "userId": "2fc60663-19a2-4aa4-852c-f7ba4e90ada2",
    "email": null,
    "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
    "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyMyZmM2MDY2My0xOWEyLTRhYTQtODUyYy1mN2JhNGU5MGFkYTI=",
    "roles": [
    "Owner"
    ],
    "displayName": null,
    "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
    "user": null
}

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

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

{
    "subscriptionId": "cae901f1-ad1d-41b1-95b7-37029ed327bf",
    "changeType": "Created",
    "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
    "clientState": "<<--SpecifiedClientState-->>",
    "subscriptionExpirationDateTime": "2021-06-03T10:58:54.7656077+00:00",
    "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')/members('MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyMyZmM2MDY2My0xOWEyLTRhYTQtODUyYy1mN2JhNGU5MGFkYTI=')",
    "resourceData": {
        "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyMyZmM2MDY2My0xOWEyLTRhYTQtODUyYy1mN2JhNGU5MGFkYTI=",
        "@odata.type": "#microsoft.graph.aadUserConversationMember",
        "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')/members('MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyMyZmM2MDY2My0xOWEyLTRhYTQtODUyYy1mN2JhNGU5MGFkYTI=')"
    }
}

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

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