Obtenir des notifications de modification pour les mises à jour de présence dans Microsoft Teams

Les notifications de modification dans Microsoft Graph vous permettent de vous abonner aux modifications apportées aux informations de présence des utilisateurs dans Microsoft Teams. Les notifications de modification offrent une alternative à l’interrogation de présence à l’aide des API GET presence et POST getPresencesByUserId .

Utilisez des webhooks pour vous abonner aux informations de présence des utilisateurs et recevoir des notifications lorsque des modifications se produisent. Pour obtenir des informations générales sur les webhooks, consultez Notifications de modification de l’API Graph Microsoft.

Cette API est disponible dans les déploiements cloud nationaux suivants.

Autorisations

Ressources prises en charge pour la présence

Un seul utilisateur peut créer un abonnement de présence par application unique avec un délai d’expiration maximal d’une heure. Un abonnement peut être renouvelé via l’API de mise à jour de l’abonnement avant son expiration, ou un nouvel abonnement peut être créé pour la même ressource après son expiration. Les abonnements de présence prennent en charge les notifications avec des données de ressources, ce qui permet de fournir des informations plus détaillées avec les notifications de modification. Pour plus d’informations, consultez Configurer des notifications de modification avec des données de ressource.

Le tableau suivant répertorie les types de changements de présence auxquels vous pouvez vous abonner. Pour plus d’informations, consultez Créer un abonnement.

S’abonner aux modifications de présence

Pour vous abonner aux changements de présence, vous pouvez définir la ressource dans la charge utile d’abonnement où communications/presences/{id} le champ {id} doit être remplacé par l’ID utilisateur GUID de la présence de l’utilisateur. Cet abonnement fournit des notifications de modification lorsque la présence de l’utilisateur change.

Définir includeResourceData et true fournir les valeurs appropriées pour encryptionCertificate et encryptionCertificateId s’abonner aux notifications enrichies.

Exemple : charges utiles d’abonnement de présence d’utilisateur unique

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

S’abonner à la présence de plusieurs utilisateurs

Les abonnements en bloc pour la présence utilisateur peuvent être créés en définissant la valeur de ressource d’abonnement sur /communications/presences?$filter=id in ('{id}', '{id}',...), où {id} représente un GUID d’ID d’utilisateur d’utilisateurs. Un maximum de 650 utilisateurs peuvent être abonnés dans un seul abonnement. Les changements de présence pour les ID utilisateur génèrent une notification.

Exemple : charges utiles d’abonnement à la présence de plusieurs utilisateurs

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

Recevoir des notifications d’événements de présence

Les notifications de modification des événements de présence sont déclenchées lorsque des modifications sont apportées à la disponibilité et à l’activité d’un utilisateur.

Notifications de présence de base

Les notifications de base informent les abonnés de l’identité de la ressource qui a changé. Lorsque vous recevez ces informations, vous devez effectuer un appel GET distinct pour obtenir les détails des données. Pour les notifications de présence de base, vous recevez des informations sur la présence de l’utilisateur qui a changé, mais aucune donnée sur les détails de la présence de l’utilisateur. Vous pouvez utiliser les API de présence GET pour découvrir l’état de la disponibilité et de l’activité de l’utilisateur.

Exemple de charge utile

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

Notifications de présence enrichies

Les notifications enrichies informent les abonnés des modifications apportées à une ressource. Pour les notifications de présence enrichies, les abonnés sont avertis lorsque l’utilisateur Availability et Activity les modifications apportées à encryptedContent.data. Pour plus d’informations sur l’abonnement aux notifications enrichies et le déchiffrement des données, consultez Configurer des notifications de modification qui incluent des données de ressources.

Pour plus d’informations sur les combinaisons possibles de disponibilité et d’activité, voir Propriétés de présence.

Exemple de charge utile

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

Exemple : notifications déchiffrées avec des données de ressource

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

Contenu connexe

• Présence
• Modifier les notifications par le biais de webhooks
• Notifications de modification de l’API Graph Microsoft