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.

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

Les abonnements ont 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.

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.

Exemple : notifications de présence de base

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

Exemple : notifications de présence avec des données de ressources

Les notifications de présence avec des données de ressource ont les propriétés supplémentaires suivantes chiffrées dans la charge utile :

  • Informations de disponibilité ou de présence de base (disponibles, absents, occupés)
  • Activité ou informations complémentaires à la disponibilité (en réunion, en appel)

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

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