Receba notificações de alteração de membros em equipes e canais usando o Microsoft Graph

  • Artigo

As notificações de alteração permitem que você assine alterações de associação (criar, atualizar e excluir) em uma equipe ou canal privado. Você pode ser notificado sempre que um membro é adicionado, removido ou atualizado em uma equipe ou em um canal privado. Você também pode obter os dados do recurso nas notificações e, portanto, evitar chamar a API para obter o conteúdo.

Continue com este artigo sobre cenários para o recurso conversationMember no contexto de equipe ou canal . Ou descubra sobre notificações de alteração para outros recursos do Microsoft Teams.

Observação

Se você solicitar uma assinatura expirationDateTime com mais de 1 hora no futuro, você deverá assinar notificações de ciclo de vida incluindo uma propriedade lifecycleNotificationUrl em sua solicitação de assinatura. Caso contrário, sua solicitação de assinatura falhará com a seguinte mensagem de erro: lifecycleNotificationUrl é uma propriedade necessária para criação de assinatura nesse recurso quando o valor expirationDateTime for definido como maior que 1 hora.

Inscrever-se para receber alterações na associação de uma equipe específica

Para obter notificações de alterações para alterações de membros em uma equipe específica, inscreva-se em /teams/{team-id}/members. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) TeamMember.Read.All, TeamMember.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte.
Aplicativo TeamMember.Read.Group*, TeamMember.Read.All, TeamMember.ReadWrite.All

Nota: As permissões marcadas com * são suportadas como parte do consentimento específico do recurso.

Exemplo

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

Assinar alterações de associação em todas as equipes em todo o locatário

Para obter notificações de alteração para alterações de associação em todas as equipes em todo o locatário, assine /teams/getAllMembers. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Sem suporte.
Delegado (conta pessoal da Microsoft) Sem suporte.
Aplicativo TeamMember.Read.All, TeamMember.ReadWrite.All

Exemplo

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

Assinar alterações de associação em todos os canais em todo o locatário (versão prévia)

Para obter notificações de alteração para alterações de associação em todos os canais em todo o locatário, assine /teams/getAllChannels/getAllMembers. Este recurso oferece suporte a incluindo dados de recursos na notificação. Atualmente, há suporte apenas para canais privados. Esta assinatura está disponível apenas no ponto de extremidade beta.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Sem suporte.
Delegado (conta pessoal da Microsoft) Sem suporte.
Aplicativo ChannelMember.Read.All, ChannelMember.ReadWrite.All

Exemplo

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

Assinar alterações de associação em todos os canais privados e compartilhados de uma equipe específica

Para obter notificações de alteração para alterações de associação em todos os canais privados e compartilhados em uma equipe específica, assine /teams/{team-id}/channels/getAllMembers. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Observação: esta API tem requisitos de licenciamento e pagamento. Ela suporta os parâmetros de consulta model=A e model=B. Se nenhum modelo for especificado, o modo de avaliação será usado.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) ChannelMember.Read.All.
Delegado (conta pessoal da Microsoft) Sem suporte.
Aplicativo ChannelMember.Read.All

Exemplo

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

Notificações com dados de recursos

Para notificações com dados de recursos, a carga se parece com a seguinte. Essa carga útil é para uma alteração de associação em uma equipe.

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

A carga útil para os eventos de adesão ao canal é semelhante à carga útil anterior, exceto que o recurso propriedade aponta para um membro do canal em vez de um membro da equipe.

Para obter detalhes sobre como validar tokens e descriptografar a carga útil, consulte Definir notificações de alteração que incluem dados de recursos.

A carga de notificação descriptografada parece com a seguinte. O conteúdo está em conformidade com o esquema aaduserconversationmember. A carga é semelhante à devolvida pelas operações GET.

{
  "id": "/ZWUwZjVhZTItOGJjNi00YWU1LTg0NjYtN2RhZWViYmZhMDYyIyM3Mzc2MWYwNi0yYWM5LTQ2OWMtOWYxMC0yNzlhOGNjMjY3Zjk=",
  "roles": [
    "owner"
  ],
  "displayName": "John Doe",
  "userId": "8b081ef6-4792-4def-b2c9-c363a1bf41d5",
  "email": null
}

Notificações sem dados de recursos

Notificações sem dados de recursos dão informações suficientes para fazer chamadas GET para obter o conteúdo da mensagem. As assinaturas de notificações sem dados de recurso não exigem um certificado de criptografia (porque o Microsoft Graph não envia os dados reais do recurso).

Para notificações sem dados de recursos, a carga se parecerá com o seguinte. Essa carga útil é para uma alteração de associação em uma equipe.

{
  "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=')"
  }
}

A carga útil para os eventos de adesão ao canal é semelhante à carga útil anterior, exceto que o recurso propriedade aponta para um membro do canal em vez de um membro da equipe.

As propriedades recurso e @odata.id podem ser usados para fazer chamadas para o Microsoft Graph para obter o conteúdo para a mensagem. As chamadas GET sempre retornam o estado atual da mensagem. Se a mensagem for alterada entre quando a notificação for enviada e quando a mensagem for recuperada, a operação retornará a mensagem atualizada.

Conteúdo relacionado