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

  • Статья

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

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

Примечание.

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

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

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

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) TeamMember.Read.All, TeamMember.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение TeamMember.Read.Group*, TeamMember.Read.All, TeamMember.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}/members",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

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

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

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Не поддерживается.
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение TeamMember.Read.All, TeamMember.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/getAllMembers",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2022-08-10T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Подписка на изменения членства во всех каналах в клиенте (предварительная версия)

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

Разрешения

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

Пример

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

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

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

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

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

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) ChannelMember.Read.All.
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение ChannelMember.Read.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/getAllMembers",
  "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('ee0f5ae2-8bc6-4ae5-8466-7daeebbfa062')/members('ZWUwZjVhZTItOGJjNi00YWU1LTg0NjYtN2RhZWViYmZhMDYyIyM3Mzc2MWYwNi0yYWM5LTQ2OWMtOWYxMC0yNzlhOGNjMjY3Zjk=')",
        "resourceData": {
            "id": "ZWUwZjVhZTItOGJjNi00YWU1LTg0NjYtN2RhZWViYmZhMDYyIyM3Mzc2MWYwNi0yYWM5LTQ2OWMtOWYxMC0yNzlhOGNjMjY3Zjk=",
            "@odata.type": "#Microsoft.Graph.aadUserConversationMember",
            "@odata.id": "teams('ee0f5ae2-8bc6-4ae5-8466-7daeebbfa062')/members('ZWUwZjVhZTItOGJjNi00YWU1LTg0NjYtN2RhZWViYmZhMDYyIyM3Mzc2MWYwNi0yYWM5LTQ2OWMtOWYxMC0yNzlhOGNjMjY3Zjk=')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

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

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

{
  "id": "/ZWUwZjVhZTItOGJjNi00YWU1LTg0NjYtN2RhZWViYmZhMDYyIyM3Mzc2MWYwNi0yYWM5LTQ2OWMtOWYxMC0yNzlhOGNjMjY3Zjk=",
  "roles": [
    "owner"
  ],
  "displayName": "John Doe",
  "userId": "8b081ef6-4792-4def-b2c9-c363a1bf41d5",
  "email": 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('ee0f5ae2-8bc6-4ae5-8466-7daeebbfa062')/members('ZWUwZjVhZTItOGJjNi00YWU1LTg0NjYtN2RhZWViYmZhMDYyIyM3Mzc2MWYwNi0yYWM5LTQ2OWMtOWYxMC0yNzlhOGNjMjY3Zjk=')",
  "resourceData": {
    "id": "ZWUwZjVhZTItOGJjNi00YWU1LTg0NjYtN2RhZWViYmZhMDYyIyM3Mzc2MWYwNi0yYWM5LTQ2OWMtOWYxMC0yNzlhOGNjMjY3Zjk",
    "@odata.type": "#Microsoft.Graph.aadUserConversationMember",
    "@odata.id": "teams('ee0f5ae2-8bc6-4ae5-8466-7daeebbfa062')/members('ZWUwZjVhZTItOGJjNi00YWU1LTg0NjYtN2RhZWViYmZhMDYyIyM3Mzc2MWYwNi0yYWM5LTQ2OWMtOWYxMC0yNzlhOGNjMjY3Zjk=')"
  }
}

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

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

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