Obter notificações de alteração para atualizações de presença no Microsoft Teams
As notificações de alteração no Microsoft Graph permitem-lhe subscrever alterações nas informações de presença do utilizador no Microsoft Teams. As notificações de alteração fornecem uma alternativa à consulta de presença com as APIs GET presence e POST getPresencesByUserId .
Utilize webhooks para subscrever as informações de presença dos utilizadores e receber notificações quando ocorrerem alterações. Para obter informações gerais sobre webhooks, consulte Notificações de alteração do Microsoft API do Graph.
Observação
A partir de 30 de junho de 2024, para obter as alterações que ocorreram a uma chamada de reunião ativa, recomendamos que subscreva notificações avançadas.
Permissões
| Tipo de permissão | Permissões (da com menos para a com mais privilégios) | Versões com suporte |
|---|---|---|
| Delegado (conta corporativa ou de estudante) | Presence.Read.All. | V1, beta. |
| Delegado (conta pessoal da Microsoft) | Sem suporte. | Sem suporte. |
| Aplicativo | Sem suporte. | Sem suporte. |
Recursos suportados para presença
Um único utilizador pode criar uma subscrição de presença por aplicação exclusiva com um tempo de expiração máximo de uma hora. Uma subscrição pode ser renovada através da API atualizar subscrição antes de expirar ou pode ser criada uma nova subscrição para o mesmo recurso após a expiração. As subscrições de presença suportam notificações com dados de recursos, permitindo a entrega de informações mais detalhadas juntamente com notificações de alteração. Para obter mais informações, veja Configurar notificações de alteração com dados de recursos.
A tabela seguinte lista os tipos de alterações de presença que pode subscrever. Para obter mais informações, veja Criar subscrição.
| Tipo de subscrição de presença | URL do Recurso | Tipos de alteração suportados |
|---|---|---|
| Alterações de presença de utilizador único | communications/presences/{id} |
Atualizado |
| Alterações de presença de utilizadores em massa (máximo de 650 IDs de utilizador) | communications/presences?$filter=id in ('{id}', '{id}', ...) |
Atualizado |
Subscrever alterações de presença
Para subscrever as alterações de presença, pode definir o recurso no payload da subscrição para communications/presences/{id} onde o campo {id} tem de ser substituído pelo GUID do ID de utilizador da presença do utilizador. Esta subscrição fornece notificações de alteração quando a presença do utilizador é alterada.
Defina includeResourceData como true e forneça os valores adequados para encryptionCertificate e encryptionCertificateId para subscrever notificações avançadas.
Exemplo: Payloads de subscrição de presença de utilizador único
{
"changeType": "updated",
"notificationUrl": "https://webhook.contoso.com/api",
"lifecycleNotificationUrl": "https://webhook.contoso.com/api",
"resource": "communications/presences/{id}",
"expirationDateTime": "2023-09-14T10:00:00.0000000Z",
"includeResourceData": true,
"encryptionCertificate": "{encryption certificate}",
"encryptionCertificateId": "{certificate id}",
"clientState": "{secret client state}"
}
Subscrever a presença de vários utilizadores
As subscrições em massa para a presença de utilizadores podem ser criadas ao definir o valor do recurso de subscrição como /communications/presences?$filter=id in ('{id}', '{id}',...), em que {id} representa um GUID de IDs de utilizador dos utilizadores. Pode subscrever um máximo de 650 utilizadores numa única subscrição. As alterações de presença dos IDs de utilizador geram uma notificação.
Exemplo: Payloads de subscrição de presença de vários utilizadores
{
"changeType": "updated",
"notificationUrl": "https://webhook.contoso.com/api",
"lifecycleNotificationUrl": "https://webhook.contoso.com/api",
"resource": "/communications/presences?$filter=id in ('{id}', '{id}',...)",
"expirationDateTime": "2023-09-14T10:00:00.0000000Z",
"includeResourceData": true,
"encryptionCertificate": "{encryption certificate}",
"encryptionCertificateId": "{certificate id}",
"clientState": "{secret client state}"
}
Receber notificações de eventos de presença
As notificações de alteração de eventos de presença são acionadas quando são efetuadas alterações à disponibilidade e atividade de um utilizador.
Notificações de presença básicas
As notificações básicas notificam os subscritores sobre a identidade do recurso que foi alterado. Quando receber estas informações, deve fazer uma chamada GET separada para obter os detalhes dos dados. Para notificações de presença básicas, recebe informações sobre qual a presença do utilizador alterada, mas não existem dados sobre os detalhes da presença do utilizador. Pode utilizar as APIs de presença GET para detetar o estado de disponibilidade e atividade do utilizador.
Exemplo de payload
{
"value": [{
"subscriptionId": "{Subscription id}",
"clientState": "{secret client state}",
"changeType": "updated",
"tenantId": "{Organization/Tenant id}",
"resource": "communications/presences/{id}",
"subscriptionExpirationDateTime": "2023-09-14T10:00:00.0000000Z",
"resourceData": {
"@odata.id": "users/{User Id}/presence",
"@odata.type": "#microsoft.graph.presence",
"id": "{User Id}"
},
"organizationId": "{Organization/Tenant id}",
}]
}
Notificações de presença avançada
As notificações avançadas notificam os subscritores sobre as alterações que ocorreram a um recurso. Para notificações de presença avançada, os subscritores são notificados quando o utilizador Availability e Activity o são alterados no encryptedContent.data. Para obter informações sobre como subscrever notificações avançadas e desencriptar dados, veja Configurar notificações de alteração que incluem dados de recursos.
Observação
A disponibilidade e a atividade podem ser o mesmo valor.
Para obter mais informações sobre possíveis combinações de disponibilidade e atividade, veja Propriedades de presença.
Exemplo de payload
{
"value": [{
"subscriptionId": "{Subscription id}",
"clientState": "{secret client state}",
"changeType": "updated",
"tenantId": "{Organization/Tenant id}",
"resource": "communications/presences/{id}",
"subscriptionExpirationDateTime": "2023-09-14T10:00:00.0000000Z",
"resourceData": {
"@odata.id": "users/{User Id}/presence",
"@odata.type": "#microsoft.graph.presence",
"id": "{User Id}"
},
"organizationId": "{Organization/Tenant id}",
"encryptedContent": {
"data": "{Encrypted content}",
"dataSignature": "{Encrypted data signature}",
"dataKey": "{Encrypted data key for encrypting content}",
"encryptionCertificateId": "{User specified id of encryption certificate}",
"encryptionCertificateThumbprint": "{Encrpytion certification thumbprint}"
}
}],
"validationTokens": ["{Validation Tokens}"]
}
Exemplo: Notificações desencriptadas com dados de recursos
{
"@odata.id": "users/{User Id}/presence",
"@odata.type": "#microsoft.graph.presence",
"id": "{User Id}",
"availability": "{Availability}",
"activity": "{Activity}"
}