Obtención de notificaciones de cambios para las actualizaciones de presencia en Microsoft Teams

  • Artículo

Las notificaciones de cambio de Microsoft Graph le permiten suscribirse a los cambios en la información de presencia del usuario en Microsoft Teams. Las notificaciones de cambio proporcionan una alternativa al sondeo de presencia mediante las API GET presence y POST getPresencesByUserId .

Use webhooks para suscribirse a la información de presencia de los usuarios y obtener notificaciones cuando se produzcan cambios. Para obtener información general sobre webhooks, consulte Notificaciones de cambios de Microsoft Graph API.

Nota:

A partir del 30 de junio de 2024, para obtener los cambios que se produjeron en una llamada de reunión activa, se recomienda suscribirse a notificaciones enriquecidas.

Permisos

Tipo de permiso Permisos (de menos a más privilegiados) Versiones compatibles
Delegado (cuenta profesional o educativa) Presence.Read.All. V1, beta.
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación No admitida. No admitida.

Recursos admitidos para la presencia

Un único usuario puede crear una suscripción de presencia por aplicación única con un tiempo de expiración máximo de una hora. Una suscripción se puede renovar a través de update subscription API antes de que expire, o se puede crear una nueva suscripción para el mismo recurso después de la expiración. Las suscripciones de presencia admiten notificaciones con datos de recursos, lo que permite entregar información más detallada junto con las notificaciones de cambio. Para obtener más información, consulte Configuración de notificaciones de cambios con datos de recursos.

En la tabla siguiente se enumeran los tipos de cambios de presencia a los que puede suscribirse. Para obtener más información, consulte Creación de una suscripción.

Tipo de suscripción de presencia Dirección URL del recurso Tipos de cambio admitidos
Cambios de presencia de un solo usuario communications/presences/{id} Actualizado
Cambios de presencia masiva de usuarios (650 identificadores de usuario como máximo) communications/presences?$filter=id in ('{id}', '{id}', ...) Actualizado

Suscribirse a los cambios de presencia

Para suscribirse a los cambios de presencia, puede establecer el recurso de la carga de communications/presences/{id} la suscripción en donde el campo {id} debe reemplazarse por el GUID de identificador de usuario de la presencia del usuario. Esta suscripción proporciona notificaciones de cambio cuando cambia la presencia del usuario.

true Establezca includeResourceData en y proporcione los valores adecuados para encryptionCertificate y encryptionCertificateId para suscribirse a notificaciones enriquecidas.

Ejemplo: Cargas de suscripción de presencia de usuario ú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}"
}

Suscribirse a la presencia de varios usuarios

Las suscripciones masivas para la presencia del usuario se pueden crear estableciendo el valor del recurso de suscripción en /communications/presences?$filter=id in ('{id}', '{id}',...), donde {id} representa un GUID de identificadores de usuario de los usuarios. Un máximo de 650 usuarios se pueden suscribir en una sola suscripción. Los cambios de presencia de los identificadores de usuario generan una notificación.

Ejemplo: Varias cargas de suscripción de presencia de usuario

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

Recepción de notificaciones de eventos de presencia

Las notificaciones de cambio de eventos de presencia se desencadenan cuando se realizan cambios en la disponibilidad y la actividad de un usuario.

Notificaciones de presencia básicas

Las notificaciones básicas notifican a los suscriptores la identidad del recurso que cambió. Cuando reciba esta información, debe realizar una llamada GET independiente para obtener los detalles de los datos. En el caso de las notificaciones de presencia básicas, recibirá información sobre qué presencia del usuario ha cambiado, pero no datos sobre los detalles de la presencia del usuario. Puede usar las API de presencia GET para detectar el estado de la disponibilidad y la actividad del usuario.

Ejemplo de carga útil

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

Notificaciones de presencia enriquecidas

Las notificaciones enriquecidas notifican a los suscriptores los cambios que se han producido en un recurso. En el caso de las notificaciones de presencia enriquecida, los suscriptores reciben una notificación cuando el usuario Availability y Activity cambian en encryptedContent.data. Para obtener información sobre cómo suscribirse a notificaciones enriquecidas y descifrar datos, consulte Configuración de notificaciones de cambios que incluyen datos de recursos.

Nota:

La disponibilidad y la actividad pueden ser el mismo valor.

Para obtener más información sobre las posibles combinaciones de disponibilidad y actividad, consulte Propiedades de presencia.

Ejemplo de carga útil

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

Ejemplo: Notificaciones descifradas con datos de recursos

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

Contenido relacionado