Partager via

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

  • Article

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 la 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 en cas de modifications. Pour obtenir des informations générales sur les webhooks, consultez Notifications de modification microsoft API Graph.

Remarque

À compter du 30 juin 2024, pour obtenir les modifications apportées à un appel de réunion actif, nous vous recommandons de vous abonner aux notifications enrichies.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins) Versions prises en charge
Déléguée (compte professionnel ou scolaire) Presence.Read.All. V1, bêta.
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application Non prise en charge. Non prise en charge.

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 Mettre à jour l’abonnement avant son expiration, ou un nouvel abonnement peut être créé pour la même ressource après 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 ainsi que des notifications de modification. Pour plus d’informations, consultez Configurer des notifications de modification avec des données de ressources.

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

Type d’abonnement de présence URL de ressource Types de modifications pris en charge
Modifications de la présence d’un utilisateur unique communications/presences/{id} Mis à jour
Modifications de présence d’utilisateurs en bloc (650 ID d’utilisateur maximum) communications/presences?$filter=id in ('{id}', '{id}', ...) Mis à jour

S’abonner aux modifications de présence

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

Définissez includeResourceData sur true et fournissez les valeurs appropriées pour encryptionCertificate et encryptionCertificateId pour vous 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 d’utilisateurs peuvent être créés en définissant la valeur de la ressource d’abonnement sur /communications/presences?$filter=id in ('{id}', '{id}',...), où {id} représente un GUID d’ID utilisateur des utilisateurs. Un maximum de 650 utilisateurs peuvent être abonnés dans un seul abonnement. Les modifications de présence pour les ID d’utilisateur génèrent une notification.

Exemple : Charges utiles d’abonnement de présence d’utilisateurs multiples

{
    "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 pour les é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 modifié, 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 enrichie, les abonnés sont avertis lorsque l’utilisateur Availability et change Activity dans 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.

Remarque

La disponibilité et l’activité peuvent avoir la même valeur.

Pour plus d’informations sur les combinaisons possibles de disponibilité et d’activité, consultez 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