Obter notificações de alteração para equipes e canais usando o Microsoft Graph

  • Artigo

As notificações de alteração permitem que você se inscreva para alterações (criar, atualizar e excluir) de equipes e canais. Pode ser notificado sempre que uma equipa ou canal for criado, atualizado ou eliminado. 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 a equipa ou recurso de canal . Em alternativa, saiba mais sobre as notificações de alteração de outros recursos do Microsoft Teams.

Observação

Se pedir uma subscrição expirationDateTime que seja superior a 1 hora no futuro, terá de subscrever notificações de ciclo de vida ao incluir uma propriedade lifecycleNotificationUrl no pedido de subscrição. Caso contrário, o pedido de subscrição falhará com a seguinte mensagem de erro: lifecycleNotificationUrl é uma propriedade necessária para a criação da subscrição neste recurso quando o valor expirationDateTime estiver definido como superior a 1 hora.

Inscrever-se para alterações em qualquer equipe no nível de locatário

Para obter notificações de alteração para todas as alterações (criar, atualizar e excluir) relacionadas a qualquer equipe de um locatário, inscreva-se em /teams. 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 Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.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",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Inscrever-se para alterações em uma equipe em particular

Para obter notificações de alteração para todas as alterações relacionadas a uma equipe em particular de um locatário, inscreva-se em /teams/{team-id}. 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) Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All
Delegada (conta pessoal da Microsoft) Sem suporte.
Application TeamSettings.Read.Group*, TeamSettings.ReadWrite.Group*, Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.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": "deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Inscrever-se para alterações em qualquer canal no nível de locatário

Para obter notificações de alteração para todas as alterações (criar, atualizar e eliminar) relacionadas com qualquer canal num inquilino, subscreva /teams/getAllChannels. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Continue com este artigo sobre cenários para o contexto de canal ou chat . Em alternativa, saiba mais sobre as notificações de alteração de outros recursos do Microsoft Teams.

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 Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.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/getAllChannels",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Inscrever-se para alterações em qualquer canal em particular

Para obter notificações de alteração para todas as alterações relacionadas a qualquer canal em particular, inscreva-se em /teams/{team-id}/channels. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Seguem-se exemplos de eventos que geram notificações para este recurso:

  • O nome a apresentar de um canal é atualizado na equipa.
  • É criado um canal privado na equipa.
  • Um canal partilhado pertencente a esta equipa é partilhado ou não partilhado com outra equipa.
  • Um canal partilhado pertencente a outra equipa é partilhado com esta equipa.
  • As propriedades de um canal, como isFavoriteByDefault ou description, são atualizadas.
  • Um canal é excluído.

Nota: Para o contexto delegado, apenas os utilizadores autorizados receberão notificações para canais privados/partilhados. Por exemplo, qualquer pessoa que pertença à equipa (exceto os convidados) pode subscrever este recurso em contexto delegado, mas apenas os utilizadores que têm acesso a canais privados e partilhados receberão notificações sobre eventos que ocorrem nesses canais.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte.
Application ChannelSettings.Read.Group*, ChannelSettings.ReadWrite.Group*, Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.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}/channels",
  "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 é para uma alteração de propriedade 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('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.Team",
            "@odata.id": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

A carga de notificação descriptografada parece com o seguinte. A carga está de acordo com o esquema de equipes. A carga é semelhante à devolvida pelas operações GET.

Nota:discoveryDefinições e classSettings não são expostos em dados de payload.

{
  "id": "4c533ad3-e1dd-4277-a672-92ab64ed225c",
  "createdDateTime": "2021-03-18T10:31:14.597Z",
  "displayName": "Sample name",
  "description": "Sample description",
  "internalId": "19:2077546f765a42c1ba71236f4df70aa2@thread.tacv2",
  "specialization": "none",
  "visibility": "public",
  "webUrl": "https://teams.microsoft.com/l/team/19:2077546f724a42c1ba71236f4df79aa2%40thread.tacv2/conversations?groupId=4c533ad3-e1dd-4277-a672-92ab64ed225c&tenantId=0f2e8f59-862a-483b-9ca8-82a10665e17d",
  "isArchived": false,
  "isMembershipLimitedToOwners": false,
  "memberSettings": {
    "allowCreateUpdateChannels": true,
    "allowCreatePrivateChannels": true,
    "allowDeleteChannels": true,
    "allowAddRemoveApps": true,
    "allowCreateUpdateRemoveTabs": true,
    "allowCreateUpdateRemoveConnectors": true
  },
  "guestSettings": {
    "allowCreateUpdateChannels": false,
    "allowDeleteChannels": false
  },
  "messagingSettings": {
    "allowUserEditMessages": true,
    "allowUserDeleteMessages": true,
    "allowOwnerDeleteMessages": true,
    "allowTeamMentions": true,
    "allowChannelMentions": true
  },
  "funSettings": {
    "allowGiphy": true,
    "giphyContentRating": "moderate",
    "allowStickersAndMemes": true,
    "allowCustomMemes": true
  }
}

Para notificações com dados de recursos, a carga se parece com o seguinte. Esta carga é para uma alteração de propriedade em um canal.

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')/channels('19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2')",
        "resourceData": {
            "id": "19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2",
            "@odata.type": "#Microsoft.Graph.Channel",
            "@odata.id": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')/channels('19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

A carga de notificação descriptografada parece com o seguinte. A carga está de acordo com o esquema de canais. A carga é semelhante à devolvida pelas operações GET.

{
  "id": "19:a3f841d969cd4ae0a7cbe847fc10b371@thread.tacv2",
  "createdDateTime": "2020-02-14T01:10:03.592Z",
  "displayName": "General",
  "description": "Sample Channel description",
  "isFavoriteByDefault": true,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3Aa3f841d969cd4ae0a7cbe847fc10b371%40thread.tacv2/General?groupId=7ed9bdab-9c7d-4c10-a25d-3f4ff0e34577&tenantId=0f2d8f49-862a-493b-9ca8-82a10637e17d",
  "membershipType": "standard",
  "moderationSettings": 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 subscrições para notificações sem dados de recursos não necessitam de um certificado de encriptação (porque o Microsoft Graph não envia os dados de recursos reais).

Para notificações sem dados de recursos, a carga se parecerá com o seguinte. Essa carga é para uma alteração de propriedade 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('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.Teams",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')"
  }
}

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 devolvem sempre o estado atual da mensagem. Se a mensagem for alterada entre quando a notificação é enviada e quando a mensagem é obtida, a operação devolve a mensagem atualizada.

Observação: o endereço de email do canal não retorna na carga.

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

{
  "id": "19:a3f841d969cd4ae0a7cbe847fc10b371@thread.tacv2",
  "createdDateTime": "2020-02-14T01:10:03.592Z",
  "displayName": "General",
  "description": "Sample Channel description",
  "isFavoriteByDefault": true,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3Aa3f841d969cd4ae0a7cbe847fc10b371%40thread.tacv2/General?groupId=7ed9bdab-9c7d-4c10-a25d-3f4ff0e34577&tenantId=0f2d8f49-862a-493b-9ca8-82a10637e17d",
  "membershipType": "standard",
  "moderationSettings": null
}

Conteúdo relacionado