Share via

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

  • Artigo

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 para presença usando a presença GET e as APIs GET getPresencesByUserId .

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

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 com suporte para presença

As assinaturas têm um tempo de validade máximo 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 recurso, permitindo que informações mais detalhadas sejam entregues junto com notificações de alteração. Para obter mais informações, consulte Configurar notificações de alteração com dados de recurso.

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

Tipo de assinatura de presença URL de recursos Tipos de alteração com suporte
Alterações de presença de usuário único communications/presences/{id} Atualizado
Alterações na presença do usuário em massa (no máximo 650 IDs de usuário) communications/presences?$filter=id in ('{id}', '{id}', ...) Atualizado

Assinar alterações de presença

Para assinar as alterações de presença, você pode definir o recurso na carga de 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. Essa assinatura fornece notificações de alteração quando a presença do usuário é alterada.

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

Assinaturas em massa para a 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 o {id} representa um GUID de IDs de usuário dos usuários. No máximo 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árias cargas de assinatura de presença do 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 evento de presença

As notificações de alteração para eventos de presença são disparadas quando são feitas alterações na disponibilidade e na atividade de um usuário.

Exemplo: Notificações básicas de presença

Observação

Como as notificações básicas incluem apenas a ID do recurso que foi alterado, você precisa fazer uma chamada de presença GET separada para o Microsoft Graph para acessar dados de presença do usuário. Para obter mais informações, confira Presença GET.

{
  "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}",
  }]
}

Exemplo: Notificações de presença com dados de recurso

As notificações de presença com dados de recurso têm as seguintes propriedades adicionais criptografadas no conteúdo:

  • Informações de disponibilidade ou presença base (disponíveis, ausentes, ocupados)
  • Atividade ou informações complementares à disponibilidade (em uma reunião, em chamada)

[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, consulte Propriedades de presença.

{
  "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 recurso

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

Conteúdo relacionado