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.

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

Las suscripciones tienen 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.

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.

Ejemplo: Notificaciones de presencia básicas

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

Ejemplo: Notificaciones de presencia con datos de recursos

Las notificaciones de presencia con datos de recursos tienen las siguientes propiedades adicionales cifradas en la carga:

  • Disponibilidad o información de presencia base (disponible, ausente, ocupado)
  • Actividad o información complementaria a la disponibilidad (en una reunión, en llamada)

[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.

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