Obtener notificaciones de cambios para actualizaciones de presencia en Microsoft Teams

Las notificaciones de cambios de Microsoft Graph le permiten suscribirse a los cambios en la información de presencia del usuario en Microsoft Teams. Las notificaciones de cambios 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 recibir notificaciones cuando se produzcan cambios. Para obtener información general sobre los webhooks, consulte Notificaciones de cambio de la API de Microsoft Graph API.

Esta API está disponible en las siguientes implementaciones en la nube nacional.

Permisos

Recursos admitidos para la presencia

Un solo usuario puede crear una suscripción de presencia por aplicación única con un tiempo máximo de expiración de una hora. Se puede renovar una suscripción a través de la API de suscripción Update antes de que expire, o se puede crear una nueva suscripción para el mismo recurso después de que expire. Las suscripciones de presencia admiten notificaciones con datos de recursos, lo que permite entregar información más detallada junto con 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 Crear suscripción.

Suscribirse a los cambios de presencia

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

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

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 id. de usuario de los usuarios. Se puede suscribir un máximo de 650 usuarios en una sola suscripción. Los cambios de presencia de los identificadores de usuario generan una notificación.

Ejemplo: Cargas de suscripción de presencia de varios usuarios

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

Recibir notificaciones de eventos de presencia

Las notificaciones de cambio para eventos de presencia se activan 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 sobre la identidad del recurso que cambió. Cuando reciba esta información, debe realizar una llamada GET por separado para obtener los detalles de los datos. Para las notificaciones de presencia básicas, recibirá información sobre qué ha cambiado la presencia del usuario, pero no datos sobre los detalles de la presencia del usuario. Puede usar las API de presencia GET para detectar el estado de disponibilidad y 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 sobre los cambios que se han producido en un recurso. En el caso de las notificaciones de Availability presencia enriquecidas, se notifica a los suscriptores cuando el usuario y Activity cambia 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 incluyan datos de recursos.

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

• Presencia
• Cambiar las notificaciones a través de webhooks
• Notificaciones de cambio de la API de Microsoft Graph API