Receba notificações de alteração para alterações de associação em canais usando o Microsoft Graph

As notificações de alteração permitem que você assine alterações de associação (criar, atualizar e excluir) em um canal privado ou compartilhado. Você pode ser notificado sempre que um membro for adicionado, removido ou atualizado em um canal privado ou compartilhado. 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 do canal . Ou descubra mais sobre notificações de alteração para outros recursos do Microsoft Teams.

Observação

Se você solicitar uma expirationDateTime de assinatura que esteja mais de uma hora no futuro, 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 is a required property for subscription creation on this resource when the expirationDateTime value is set to greater than 1 hour.

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

Para obter notificações de alteração de alterações de associação em todos os canais do locatário, assine /teams/getAllChannels/getAllMembers. Este recurso oferece suporte a incluindo dados de recursos na notificação. Atualmente, apenas canais privados são suportados. 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}"
}

Inscreva-se para receber alterações de associação em todos os canais privados e compartilhados de uma equipe específica

Para receber notificações de alteração de alteração de associação em todos os canais privados e compartilhados de uma equipe específica, inscreva-se no /teams/{team-id}/channels/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)
Delegada (conta corporativa ou de estudante) ChannelMember.Read.All, ChannelMember.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte.
Aplicativo ChannelMember.Read.All, ChannelMember.ReadWrite.All

Exemplo 1: Assinar as alterações para receber notificações de associação direta para canais privados e compartilhados

A solicitação a seguir mostra como assinar as alterações para receber notificações de associação direta para canais privados e compartilhados.

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. Este conteúdo para adicionar um membro a um canal compartilhado ou privado.

{
    "value": [{
        "subscriptionId": "755a93bc-85bb-4da4-ade4-7d325bc8eecb",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/members('MCMjMyMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOTpsUlpITDVWd3ZaczBYTjJvclRuN0RsaW5KREVUa2dTVlRIWGJETFVFS2YwMUB0aHJlYWQudGFjdjIjIzU5YjViYzY5LWNhNzMtNGZmZC1hMmUwLTg4YTc5MTE1ZDEzYg==')",
        "resourceData": {
            "id": "MCMjMyMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOTpsUlpITDVWd3ZaczBYTjJvclRuN0RsaW5KREVUa2dTVlRIWGJETFVFS2YwMUB0aHJlYWQudGFjdjIjIzU5YjViYzY5LWNhNzMtNGZmZC1hMmUwLTg4YTc5MTE1ZDEzYg==",
            "@odata.type": "#Microsoft.Graph.aadUserConversationMember",
            "@odata.id": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/members('MCMjMyMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOTpsUlpITDVWd3ZaczBYTjJvclRuN0RsaW5KREVUa2dTVlRIWGJETFVFS2YwMUB0aHJlYWQudGFjdjIjIzU5YjViYzY5LWNhNzMtNGZmZC1hMmUwLTg4YTc5MTE1ZDEzYg==')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

O conteúdo anterior mostra os eventos de associação do canal em que a propriedade de recurso se refere a um membro do canal.

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": "MCMjMyMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOTpsUlpITDVWd3ZaczBYTjJvclRuN0RsaW5KREVUa2dTVlRIWGJETFVFS2YwMUB0aHJlYWQudGFjdjIjIzU5YjViYzY5LWNhNzMtNGZmZC1hMmUwLTg4YTc5MTE1ZDEzYg==",
  "roles": [
    "owner"
  ],
  "displayName": "Test user",
  "userId": "8b081ef6-4792-4def-b2c9-c363a1bf41d5",
  "email": null,
  "tenantId": "10eda0c8-cb50-4390-8751-488c29218b02"
}

Notificações sem dados de recursos

Notificações sem dados de recursos fornecem informações suficientes para fazer chamadas GET e obter o conteúdo da associação. As assinaturas para 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. Este conteúdo é para uma alteração de associação em um canal privado ou compartilhado.

{
  "subscriptionId": "9f9d1ed0-c9cc-42e7-8d80-a7fc4b0cda3c",
  "changeType": "created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-02-02T11:26:41.0537895-08:00",
  "resource": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/members('MCMjMyMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOTpsUlpITDVWd3ZaczBYTjJvclRuN0RsaW5KREVUa2dTVlRIWGJETFVFS2YwMUB0aHJlYWQudGFjdjIjIzU5YjViYzY5LWNhNzMtNGZmZC1hMmUwLTg4YTc5MTE1ZDEzYg==')",
  "resourceData": {
    "id": "MCMjMyMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOTpsUlpITDVWd3ZaczBYTjJvclRuN0RsaW5KREVUa2dTVlRIWGJETFVFS2YwMUB0aHJlYWQudGFjdjIjIzU5YjViYzY5LWNhNzMtNGZmZC1hMmUwLTg4YTc5MTE1ZDEzYg==",
    "@odata.type": "#Microsoft.Graph.aadUserConversationMember",
    "@odata.id": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/members('MCMjMyMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOTpsUlpITDVWd3ZaczBYTjJvclRuN0RsaW5KREVUa2dTVlRIWGJETFVFS2YwMUB0aHJlYWQudGFjdjIjIzU5YjViYzY5LWNhNzMtNGZmZC1hMmUwLTg4YTc5MTE1ZDEzYg==')"
  }
}

As propriedades resource e @odata.id podem ser usadas para fazer chamadas ao Microsoft Graph para obter a carga do membro do canal.

Exemplo 2: Assinar as alterações para receber notificações de associação indireta para canais compartilhados usando parâmetros de consulta

Os parâmetros de consulta a seguir em uma solicitação de assinatura habilitam notificações para atualizações diretas e indiretas de associação.

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?notifyOnIndirectMembershipUpdate=true&suppressNotificationWhenSharedUnsharedWithTeam=true",
  "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. Esse conteúdo é para adicionar um membro a uma equipe com a qual um canal é compartilhado.

{
    "value": [{
        "subscriptionId": "755a93bc-85bb-4da4-ade4-7d325bc8eecb",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2025-07-16T10:30:34.9097561-08:00",
        "resource": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/allMembers('MCMjNCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxYjAzMWEwNy1mM2FkLTQ3YmYtYTYyOS04MWM5NmViYWFkNmZfMTk6bFJaSEw1Vnd2WnMwWE4yb3JUbjdEbGluSkRFVGtnU1ZUSFhiRExVRUtmMDFAdGhyZWFkLnRhY3YyIyMxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWI=')",
        "resourceData": {
            "id": "MCMjNCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxYjAzMWEwNy1mM2FkLTQ3YmYtYTYyOS04MWM5NmViYWFkNmZfMTk6bFJaSEw1Vnd2WnMwWE4yb3JUbjdEbGluSkRFVGtnU1ZUSFhiRExVRUtmMDFAdGhyZWFkLnRhY3YyIyMxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWI=",
            "@odata.type": "#Microsoft.Graph.aadUserConversationMember",
            "@odata.id": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/allMembers('MCMjNCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxYjAzMWEwNy1mM2FkLTQ3YmYtYTYyOS04MWM5NmViYWFkNmZfMTk6bFJaSEw1Vnd2WnMwWE4yb3JUbjdEbGluSkRFVGtnU1ZUSFhiRExVRUtmMDFAdGhyZWFkLnRhY3YyIyMxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWI=')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Na carga de notificação de associação indireta do canal anterior, a propriedade de recurso aponta para o ponto de extremidade List allMembers em vez do ponto de extremidade dos membros .

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. O conteúdo é semelhante ao retornado pelo ponto de extremidade List allMembers .

{
   "@microsoft.graph.originalSourceMembershipUrl": "tenants/('10eda0c8-cb50-4390-8751-488c29218b02')teams('1b031a07-f3ad-47bf-a629-81c96ebaad6f')/members/('MCMjMSMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxYjAzMWEwNy1mM2FkLTQ3YmYtYTYyOS04MWM5NmViYWFkNmYjIzEyNzNhMDE2LTIwMWQtNGY5NS04MDgzLTFiN2Y5OWIzZWRlYg==')",
  "id": "MCMjMyMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOTpsUlpITDVWd3ZaczBYTjJvclRuN0RsaW5KREVUa2dTVlRIWGJETFVFS2YwMUB0aHJlYWQudGFjdjIjIzU5YjViYzY5LWNhNzMtNGZmZC1hMmUwLTg4YTc5MTE1ZDEzYg==",
  "roles": [],
  "displayName": "Test user",
  "userId": "8b081ef6-4792-4def-b2c9-c363a1bf41d5",
  "email": null,
  "tenantId": "10eda0c8-cb50-4390-8751-488c29218b02"
}

A anotação @microsoft.graph.originalSourceMembershipUrl mostra a origem original do membro adicionado e pode ser usada para fazer chamadas para o Microsoft Graph para obter a carga do membro em uma equipe. A propriedade no exemplo mostra que um membro é adicionado a uma equipe com a qual um canal é compartilhado. Esta propriedade só está disponível para notificação de associação indireta. As propriedades resource e @odata.id podem ser usadas para fazer chamadas ao Microsoft Graph para obter a carga do membro direto do canal.

Observação

  • As notificações de adesão indireta estão disponíveis apenas quando você está inscrito na equipe proprietária do canal compartilhado.
  • Quando estiver inscrito em alterações para receber notificações diretas e indiretas de canais compartilhados, recomendamos que você opte por receber notificações com o recurso. Essa abordagem permite que você use a anotação @microsoft.graph.originalSourceMembershipUrl para identificar alterações diretas ou indiretas na associação.
  • Quando um assinante receber uma notificação de que um membro foi removido, use a API channel: doesUserHaveAccess para verificar se o acesso do usuário foi realmente revogado.

Assinar alterações quando um canal específico for compartilhado com ou não compartilhado de uma equipe

Os assinantes podem receber notificações de alteração quando um canal específico é compartilhado com ou não compartilhado de uma equipe.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegada (conta corporativa ou de estudante) ChannelMember.Read.All, ChannelMember.ReadWrite.All
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",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/sharedWithTeams",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2025-07-14T22:33:21.5040567Z",
  "clientState": "{secretClientState}"
}

Notificações com dados de recursos

Para notificações com dados de recursos, a carga se parece com a seguinte. Este conteúdo é para compartilhar um canal com uma equipe.

{
    "value": [{
        "subscriptionId": "7e11c492-bae9-4fa5-a7b5-71844cf8ac47",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2025-07-14T22:33:21.5040567+00:00",
        "resource": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/sharedWithTeams('04460120-3ca5-40cf-bc72-e890777256a3')",
        "resourceData": {
            "id": "04460120-3ca5-40cf-bc72-e890777256a3",
            "@odata.type": "#Microsoft.Graph.sharedWithChannelTeamInfo",
            "@odata.id": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/sharedWithTeams('04460120-3ca5-40cf-bc72-e890777256a3')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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 sharedWithChannelTeamInfo . A carga é semelhante à devolvida pelas operações GET.

{
  "isHostTeam": false,
  "id": "04460120-3ca5-40cf-bc72-e890777256a3",
  "tenantId": "10eda0c8-cb50-4390-8751-488c29218b02",
  "displayName": "My Sample Team for first"
}

Notificações sem dados de recursos

Notificações sem dados de recursos fornecem informações suficientes para fazer chamadas GET e obter o conteúdo da associação. As assinaturas para 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": "7e11c492-bae9-4fa5-a7b5-71844cf8ac47",
  "changeType": "created",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2025-07-14T22:33:21.5040567+00:00",
  "resource": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/sharedWithTeams('04460120-3ca5-40cf-bc72-e890777256a3')",
  "resourceData": {
    "id": "04460120-3ca5-40cf-bc72-e890777256a3",
    "@odata.type": "#Microsoft.Graph.sharedWithChannelTeamInfo",
    "@odata.id": "teams('cd28795b-988a-48ec-b652-781178957d8b')/channels('19:lRZHL5VwvZs0XN2orTn7DlinJDETkgSVTHXbDLUEKf01@thread.tacv2')/sharedWithTeams('04460120-3ca5-40cf-bc72-e890777256a3')"
  }
}

As propriedades de recurso e @odata.id podem ser usadas para fazer chamadas para o Microsoft Graph para obter informações sobre quando um canal é compartilhado com ou não compartilhado de uma equipe.

Depois de receber um evento de notificação que indica que um canal compartilhado foi compartilhado ou não compartilhado de uma equipe, chame a API List allMembers para atualizar a associação do canal compartilhado.

Conteúdo relacionado

  • Last updated on