Recevoir des notifications de modification pour les conversations à l’aide de Microsoft Graph

  • Article

Les notifications de modification vous permettent de vous abonner aux modifications (création et mise à jour) apportées aux conversations. Vous pouvez recevoir une notification chaque fois qu’une conversation est créée ou mise à jour. Vous pouvez également obtenir les données de ressource dans les notifications et ainsi éviter d’appeler l’API pour obtenir la charge utile.

Poursuivez avec cet article sur les scénarios de la ressource de conversation . Vous pouvez également découvrir les notifications de modification pour d’autres ressources Microsoft Teams.

Remarque

Si vous demandez un abonnement expirationDateTime supérieur à 1 heure à l’avenir, vous devez vous abonner aux notifications de cycle de vie en incluant une propriété lifecycleNotificationUrl dans votre demande d’abonnement. Sinon, votre demande d’abonnement échoue avec le message d’erreur suivant : lifecycleNotificationUrl est une propriété obligatoire pour la création d’abonnement sur cette ressource lorsque la valeur expirationDateTime est définie sur plus d’une heure.

S’abonner aux modifications dans n’importe quelle conversation au niveau du client

Pour recevoir les notifications pour toutes les modifications (création et mise à jour) relatives à une conversation dans un client, abonnez-vous à /chats. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Non prise en charge.
Déléguée (compte Microsoft personnel) Non prise en charge.
Application Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Exemple

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S’abonner aux modifications dans une conversation particulière

Pour recevoir les notifications pour toutes les modifications relatives à une conversation en particulier dans un client, abonnez-vous à /chats/{id}. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Déléguée (compte Microsoft personnel) Non prise en charge.
Application ChatSettings.Read.Chat*, ChatSettings.ReadWrite.Chat*, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Remarque : Les autorisations marquées avec * utilisent une autorisation propre aux ressources.

Exemple

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{id}",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Notifications avec des données de ressource

Pour les notifications avec des données de ressource, la charge utile se présente comme suit. Cette charge utile concerne une modification de propriété dans une conversation.

{
    "value": [{
        "subscriptionId": "352887e3-9be0-4b6f-a4e6-dec118d857db",
        "changeType": "Created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-06-03T09:50:37.719033+00:00",
        "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
        "resourceData": {
            "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
            "@odata.type": "#microsoft.graph.chat",
            "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
        },
        "EncryptedContent": {
            "data": "<<--EncryptedContent-->>",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        }
            "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
        }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Pour plus d’informations sur la validation des jetons et le déchiffrement de la charge utile, consultez Configurer des notifications de modification comprenant des données de ressource.

La charge utile de la notification déchiffrée se présente comme suit. La charge utile est conforme au schéma conversations. La charge utile est similaire à celle renvoyée par les opérations GET.

{
  "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
  "topic": null,
  "createdDateTime": "2021-06-03T14:25:04+05:30",
  "lastUpdatedDateTime": "2021-06-03T14:25:04.387Z",
  "chatType": "oneOnOne",
  "members": [
    {
      "userId": "976f4b31-fd01-4e0b-9178-29cc40c14438",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyM5NzZmNGIzMS1mZDAxLTRlMGItOTE3OC0yOWNjNDBjMTQ0Mzg=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    },
    {
      "userId": "ee723d3d-22d0-4394-9c32-5764d68f4672",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyNlZTcyM2QzZC0yMmQwLTQzOTQtOWMzMi01NzY0ZDY4ZjQ2NzI=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": []
}

S’abonner aux modifications apportées à une conversation dans un locataire où une application Teams est installée

Pour obtenir des notifications de modification pour toutes les modifications liées à une conversation dans un locataire où une application Teams spécifique est installée, abonnez-vous à /appCatalogs/teamsApps/{teams-app-id}/installedToChats. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

Remarque: cette API a des exigences de licences et de paiement. Il prend en charge le paramètre de requête model=B. Si aucun modèle n’est spécifié, le mode d’évaluation sera utilisé.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Non prise en charge.
Déléguée (compte Microsoft personnel) Non prise en charge.
Application Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled

Exemple

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/appCatalogs/teamsApps/386bbcdb-1e1c-4f3f-b7d0-ad7b9ea6cf7c/installedToChats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Notifications sans les données de ressource

La charge utile suivante décrit les informations envoyées dans la demande de notifications sans données de ressource. Cette charge utile particulière signifie qu’une conversation a été créée.

{
  "subscriptionId": "8d85051d-779d-45bc-be92-e433f0a5d8ac",
  "changeType": "Created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-06-03T10:26:09.8959595+00:00",
  "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
  "resourceData": {
    "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
    "@odata.type": "#microsoft.graph.chat",
    "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
  }
}

Les propriétés resource et @odata.id peuvent être utilisées pour effectuer des appels vers Microsoft Graph afin d’obtenir la charge utile des détails d’une conversation. Les appels GET retournent toujours l’état actuel des détails de la conversation. Si les détails de la conversation ont été mis à jour entre le moment où la notification est envoyée et le moment où les détails de la conversation sont récupérés, l’opération retourne les détails de conversation mis à jour.

Contenu connexe