Receber notificações de alteração para atualizações de presença no Microsoft Teams

As notificações de alteração no Microsoft Graph permitem que você assine alterações nas informações de presença do usuário no Microsoft Teams. As notificações de alteração fornecem uma alternativa à sondagem de presença usando as APIs GET presence e POST getPresencesByUserId .

Use webhooks para assinar as informações de presença dos usuários e receber notificações quando ocorrerem alterações. Para obter informações gerais sobre webhooks, consulte Notificações de alteração da API do Graph Microsoft.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Permissões

Recursos com suporte para presença

Um único usuário pode criar uma assinatura de presença por aplicativo exclusivo com um tempo máximo de expiração de uma hora. Uma assinatura pode ser renovada por meio da API de assinatura de atualização antes de expirar ou uma nova assinatura pode ser criada para o mesmo recurso após a expiração. As assinaturas de presença dão suporte a notificações com dados de recursos, permitindo que informações mais detalhadas sejam fornecidas juntamente com notificações de alteração. Para obter mais informações, consulte Configurar notificações de alteração com dados de recursos.

A tabela a seguir lista os tipos de alterações de presença que você pode assinar. Para obter mais informações, consulte Criar assinatura.

Assinar as alterações de presença

Para assinar alterações de presença, você pode definir o recurso no conteúdo da assinatura para communications/presences/{id} onde o campo {id} deve ser substituído pelo GUID da ID do usuário da presença do usuário. Esta assinatura fornece notificações de alteração quando a presença do usuário é alterada.

Defina includeResourceData como true e forneça valores apropriados para encryptionCertificate e encryptionCertificateId para assinar notificações avançadas.

Exemplo: cargas de assinatura de presença de usuário ú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}"
}

Assinar a presença de vários usuários

As assinaturas em massa para presença do usuário podem ser criadas definindo o valor do recurso de assinatura como /communications/presences?$filter=id in ('{id}', '{id}',...), em que {id} representa um GUID de ID de usuário. Um máximo de 650 usuários podem ser inscritos em uma única assinatura. Alterações de presença para IDs de usuário geram uma notificação.

Exemplo: vários conteúdos de assinatura de presença de usuário

{
    "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 para eventos de presença são acionadas quando são feitas alterações na disponibilidade e na atividade de um usuário.

Notificações básicas de presença

As notificações básicas notificam os assinantes sobre a identidade do recurso que foi alterado. Ao receber essas informações, você deve fazer uma chamada GET separada para obter os detalhes dos dados. Para notificações de presença básicas, você recebe informações sobre qual presença do usuário foi alterada, mas nenhum dado sobre os detalhes da presença do usuário. Você pode usar as APIs de presença GET para descobrir o estado da disponibilidade e da atividade do usuário.

Exemplo de conteúdo

{
  "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 assinantes sobre as alterações ocorridas em um recurso. Para notificações de presença avançada, os assinantes são notificados quando o usuário Availability e Activity as alterações no encryptedContent.data. Para obter informações sobre como assinar notificações avançadas e descriptografar dados, consulte Configurar notificações de alteração que incluem dados de recursos.

Para obter mais informações sobre possíveis combinações de disponibilidade e atividade, consulte Propriedades de presença.

Exemplo de conteúdo

{
  "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 descriptografadas com dados de recursos

{
    "@odata.id": "users/{User Id}/presence",
    "@odata.type": "#microsoft.graph.presence",
    "id": "{User Id}",
    "availability": "{Availability}",
    "activity": "{Activity}"
}

Conteúdo relacionado

• Presença
• Alterar notificações por meio de webhooks
• Notificações de alteração da API do Graph da Microsoft Graph