Alterar as notificações para os recursos do Microsoft Teams

  • Artigo

Alterar as notificações dos recursos do Microsoft Teams com o Microsoft Graph permite-lhe subscrever as alterações de um recurso (criar, atualizar e eliminar). As notificações de alteração fornecem um modelo de baixa latência, permitindo-lhe manter uma subscrição. Também pode obter os dados de recursos nas notificações e evitar chamar a API para obter o payload.

Observação

O tempo máximo que uma subscrição pode durar é de 60 minutos; no entanto, as subscrições podem ser renovadas até que o autor da chamada tenha permissão para aceder ao recurso.

Tipoos de notificações de alteração

O Microsoft Teams dá suporte a dois tipos de notificações de alteração:

  • Alterar notificação para controlar todas as alterações relacionadas a um recurso no locatário: Por exemplo, você pode assinar alterações em mensagens em qualquer canal no locatário e ser notificado sempre que uma mensagem for criada, atualizada ou excluída em qualquer canal no locatário. Estas notificações podem ter requisitos de licenciamento e pagamento, tais como notificações de alteração para mensagens e associação.

  • Altere a notificação para controlar todas as alterações de um recurso específico: Por exemplo, pode subscrever alterações em mensagens num canal específico e ser notificado sempre que uma mensagem for criada, atualizada ou eliminada.

Para obter detalhes sobre quais recursos dão suporte a quais tipos de notificações de alteração, consulte Notificações de Alteração do Microsoft Graph.

Recursos com suporte

A tabela seguinte lista os recursos do Microsoft Teams que suportam notificações de alteração e os respetivos caminhos de recursos correspondentes. Aplique o caminho do recurso para o seu cenário, conforme especificado ao criar uma subscrição. O tipo de payload do caminho do recurso é o tipo na coluna "Recurso" ou numa coleção desse tipo.

Observação

As subscrições de recursos marcados com um asterisco (*) só estão disponíveis no /beta ponto final.

Recurso Trajetórias dos recursos com suporte Os dados do recurso podem ser incluídos nas notificações
Chamada do TeamsRegisto Todas as gravações numa organização: communications/onlineMeetings/getAllRecordings
Todas as gravações para uma reunião específica: communications/onlineMeetings/{onlineMeetingId}/recordings
Uma gravação de chamada que fica disponível numa reunião organizada por um utilizador específico: users/{userId}/onlineMeetings/getAllRecordings
Uma gravação de chamada que fica disponível numa reunião onde está instalada uma determinada aplicação do Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings *		 Sim
Chamada do TeamsTranscript Todas as transcrições numa organização: communications/onlineMeetings/getAllTranscripts
Todas as transcrições de uma reunião específica: communications/onlineMeetings/{onlineMeetingId}/transcripts
Uma transcrição de chamada que fica disponível numa reunião organizada por um utilizador específico: users/{userId}/onlineMeetings/getAllTranscripts
Uma transcrição de chamadas que fica disponível numa reunião onde está instalada uma determinada aplicação do Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts *		 Sim
Canal do Teams Alterações nos canais em todas as equipes:
/teams/getAllChannels
Alterações no canal em uma equipe específica:
/teams/{id}/channels		 Sim
Chat do Teams Alterações em qualquer chat no locatário:
/chats
Alterações em um chat específico:
/chats/{id}
Alterações a qualquer conversa no inquilino onde está instalada uma determinada aplicação do Teams:
/appCatalogs/teamsApps/{id}/installedToChats		 Sim
Teams chatMessage Alterações nas mensagens de chat em todos os canais de todas as equipes:
/teams/getAllMessages
Alterações nas mensagens de um chat específico:
/teams/{id}/channels/{id}/messages
Alterações nas mensagens de todos os chats:
/chats/getAllMessages
Alterações nas mensagens de um chat específico:
/chats/{id}/messages
Alterações nas mensagens de chat em todos os chats de que um usuário específico faz parte:
/users/{id}/chats/getAllMessages
Alterações às mensagens de chat em todas as conversas no inquilino onde está instalada uma determinada aplicação do Teams:
/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages		 Sim
conversationMember do Teams Alterações na associação em uma equipe específica:
/teams/{id}/members
Alterações na associação em um chat específico:
/chats/{id}/members
Alterações na associação em todos os chats:
/chats/getAllMembers
Alterações na associação em todos os canais em uma equipe específica:
teams/{id}/channels/getAllMembers
Alterações à associação em todas as conversas no inquilino onde está instalada uma determinada aplicação do Teams:
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
Alterações à associação em todos os canais no inquilino:
teams/getAllChannels/getAllMembers		 Sim
Equipe do Teams Alterações em qualquer equipe no locatário:
/teams
Alterações em uma equipe específica:
/teams/{id}		 Sim
Teams teamsAppInstallation Alterações quando uma determinada aplicação do Teams é instalada, atualizada ou eliminada:
/appCatalogs/teamsApps/{teams-app-id}/installations		 Sim

Cargas de notificação

Pode receber a notificação com ou sem dados de recursos, consoante a sua subscrição. Subscrever com dados de recursos permite-lhe obter o payload da mensagem e a notificação, removendo a necessidade de efetuar uma chamada de volta e obter o conteúdo.

Notificações com dados de recursos

Para notificações com dados de recursos, a carga se parece com a seguinte. Essa carga é para uma notificação correspondente ao recurso de mensagem de chat. A notificação real inclui as propriedades resource e resourceData, que representam o recurso que disparou a notificação.

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.chatMessage",
            "@odata.id": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Para obter detalhes sobre como validar tokens e desencriptar o payload, veja Configurar notificações de alteração que incluem dados de recursos.

A carga de notificação descriptografada parece com a seguinte. A carga descriptografada para o exemplo anterior está em conformidade com o esquema chatMessage. A carga é semelhante à devolvida pelas operações GET.

{
  "id": "1612289992105",
  "replyToId": null,
  "etag": "1612289992105",
  "messageType": "message",
  "createdDateTime": "2021-02-02T18:19:52Z",
  "lastModifiedDateTime": "2021-02-02T18:19:52.105Z",
  "lastEditedDateTime": null,
  "deletedDateTime": null,
  "subject": null,
  "summary": null,
  "chatId": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces",
  "importance": "normal",
  "locale": "en-us",
  "webUrl": null,
  "from": {
    "application": null,
    "device": null,
    "user": {
      "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
      "displayName": "Ramjot Singh",
      "userIdentityType": "aadUser"
    },
    "conversation": null
  },
  "body": {
    "contentType": "text",
    "content": "test"
  },
  "channelIdentity": null,
  "attachments": [],
  "mentions": [],
  "policyViolation": null,
  "reactions": [],
  "replies": [],
  "hostedContents": []
}

Notificações sem dados de recursos

Notificações sem dados de recurso fornecem informações suficientes para fazer chamadas GET para obter o recurso. As subscrições para notificações sem dados de recursos não necessitam de um certificado de encriptação (porque os dados de recursos reais não são enviados).

A carga parece ser a seguinte. Este conteúdo é para uma mensagem enviada em um canal.

{
  "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')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.chatMessage",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')"
  }
}

O exemplo anterior mostra uma notificação correspondente a um recurso de mensagem de chat. A notificação real inclui as propriedades resource e resourceData, que representam o recurso que disparou a notificação. As propriedades recurso e @odata.id podem ser usados para fazer chamadas para o Microsoft Graph para obter a carga do recurso.

Observação

As chamadas GET sempre retornarão o estado atual do recurso. Se o recurso for alterado entre quando a notificação for enviada e quando o recurso for recuperado, a operação retornará o recurso atualizado.

Conteúdo relacionado