Recevez les notifications de modifications des messages de canaux et de conversations Teams à l’aide de Microsoft Graph

  • Article
  • 9 minutes de lecture

Les notifications de modifications vous permettent de vous abonner aux modifications (créer, mettre à jour et supprimer) apportées aux messages de canal ou de conversation. Les notifications de modification fournissent un modèle de faible latence en vous permettant de gérer un abonnement. 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 chatMessage dans le canal ou le contexte de conversation . Vous pouvez également découvrir les notifications de modification pour d’autres ressources Microsoft Teams.

S’abonner aux modifications au niveau du client

Pour suivre toutes les modifications apportées aux messages dans un client, vous pouvez utiliser les abonnements au niveau du client pour les messages de canal et de conversation. Pour ce faire, vous devez créer deux abonnements : un pour suivre tous les messages sur les canaux, et l’autre pour suivre tous les messages dans les conversations.

S’abonner aux messages sur tous les canaux

Pour recevoir les notifications de modification de tous les messages et réponses sur les canaux d’un client, abonnez-vous à /teams/getAllMessages. 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 paramètres de requêtemodel=A et model=B à la fois. 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 ChannelMessage.Read.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": "/teams/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S'abonner aux messages de toutes les conversations

Pour recevoir les notifications de modification de tous les messages et réponses dans les conversations d’un client, abonnez-vous à /chats/getAllMessages. 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 paramètres de requêtemodel=A et model=B à la fois. 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.Read.All

Exemple

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

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

Abonnement aux messages dans un canal

Pour effectuer le suivi des messages et des réponses dans un canal, vous pouvez créer un abonnement de notification de modifications à un niveau de canal. Pour ce faire, abonnez-vous à /teams/{team-id}/channels/{channel-id}/messages. Cette ressource prend en charge y compris les données de ressources dans la notification des modes délégué et application uniquement.

Les abonnements au niveau canal prennent également en charge la recherche basée sur les mots clés via le $searchparamètre de requête.

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) ChannelMessage.Read.All
Déléguée (compte Microsoft personnel) Non prise en charge.
Application ChannelMessage.Read.Group*, ChannelMessage.Read.All

Remarque : les autorisations marquées d’un * sont prises en charge dans le cadre du consentement spécifique à la ressource.

Exemple 1: Abonnement à tous les messages (et réponses) dans un canal

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

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

Exemple 2: Abonnement aux messages (et réponses) dans un canal contenant certains textes

La demande suivante enverra les messages contenant Hello à l’abonné.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$search=Hello",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 3: Abonnement aux messages (et réponses) dans un canal sans données de ressource

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 4: Abonnement aux messages (et réponses) dans un canal mentionnant un utilisateur spécifique

Pour obtenir des notifications uniquement pour les messages où un utilisateur spécifique a été mentionné, vous pouvez spécifier l'ID de l'utilisateur (9a6eb4d1-826b-48b1-9627-b50836c8fee9 dans cet exemple) dans la requête.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Abonnement aux messages de conversations

Pour effectuer le suivi des messages dans une conversation, vous pouvez créer un abonnement de notification de modifications à un niveau de conversation. Pour ce faire, abonnez-vous à /chats/{chat-id}/messages. Cette ressource prend en charge y compris les données de ressources dans la notification des modes délégué et application uniquement.

Les abonnements au niveau des conversations prennent également en charge la recherche basée sur les mots clés via le $searchparamètre de requête.

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.Read
Déléguée (compte Microsoft personnel) Non prise en charge.
Application ChatMessage.Read.Chat*, Chat.Read.All

Remarque : les autorisations marquées d’un * sont prises en charge dans le cadre du consentement spécifique à la ressource uniquement pour la version bêta actuellement.

Exemple 1: Abonnement aux messages de conversations

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

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

Exemple 2: Abonnement aux messages de conversations contenant certains textes

La demande suivante enverra les messages contenant Hello à l’abonné.

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

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

Exemple 3: Abonnement aux messages (et réponses) dans une conversation sans données de ressource

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Exemple 4 : Abonnement aux messages dans une conversation où un utilisateur spécifique est mentionné

Pour obtenir des notifications uniquement pour les messages dans lesquelles un utilisateur spécifique a été mentionné, vous pouvez spécifier l'ID de l'utilisateur (9a6eb4d1-826b-48b1-9627-b50836c8fee9 dans cet exemple) dans la requête.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

S’abonner aux modifications au niveau de l’utilisateur

Pour suivre les messages dans toutes les conversations dont un utilisateur particulier fait partie, vous pouvez créer un abonnement de notification de modification au niveau de l’utilisateur. Pour ce faire, abonnez-vous à /users/{user-id}/chats/getAllMessages. Cette ressource prend en charge y compris les données de ressources dans la notification des modes délégué et application uniquement.

Les abonnements de messagerie de conversation au niveau de l’utilisateur prennent également en charge la recherche basée sur les mots clés via le paramètre de requête $search.

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) Chat.Read, Chat.ReadWrite
Déléguée (compte Microsoft personnel) Non prise en charge.
Application Chat.Read.All, Chat.ReadWrite.All

Exemple : s’abonner à des messages dans toutes les conversations dont un utilisateur particulier fait partie

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

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

S’abonner aux messages d’une conversation dans un locataire où une application Teams spécifique est installée (préversion)

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

Note. Ce type de ressource est actuellement en préversion.

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.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled

Exemple

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

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

Charges utiles de notification

En fonction de votre abonnement, vous pouvez recevoir la notification avec ou sans les données de ressource. L’abonnement avec des données de ressource vous permet d’obtenir la charge utile du message ainsi que la notification, avec la suppression de la nécessité de rappeler pour obtenir le contenu.

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 un message envoyé dans une conversation.

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.chatMessage",
            "@odata.id": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')"
        },
        "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 chatMessage. La charge utile est similaire à celle renvoyée par les opérations GET.

{
  "id": "1612289992105",
  "replyToId": null,
  "etag": "1612289992105",
  "messageType": "message",
  "createdDateTime": "2021-02-02T18:19:52Z",
  "lastModifiedDateTime": "2021-02-02T18:19:52.105Z",
  "lastEditedDateTime": null,
  "deletedDateTime": null,
  "subject": null,
  "summary": null,
  "chatId": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces",
  "importance": "normal",
  "locale": "en-us",
  "webUrl": null,
  "from": {
    "application": null,
    "device": null,
    "user": {
      "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
      "displayName": "Ramjot Singh",
      "userIdentityType": "aadUser"
    },
    "conversation": null
  },
  "body": {
    "contentType": "text",
    "content": "test"
  },
  "channelIdentity": null,
  "attachments": [],
  "mentions": [],
  "policyViolation": null,
  "reactions": [],
  "replies": [],
  "hostedContents": []
}

Notifications sans les données de ressource

Les notifications sans les données de ressource vous donnent suffisamment d’informations pour passer des appels GET pour obtenir le contenu du message. Les abonnements aux notifications sans les données de ressource ne nécessitent pas de certificat de chiffrement (car les données de ressources réelles ne sont pas transmises).

La charge utile se présente comme suit. Cette charge utile concerne un message envoyé dans un canal.

 {
  "subscriptionId": "9f9d1ed0-c9cc-42e7-8d80-a7fc4b0cda3c",
  "changeType": "created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-02-02T11:26:41.0537895-08:00",
  "resource": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.chatMessage",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')"
  }
}

Les propriétés de Ressource et @odata.id peuvent être utilisées pour effectuer des appels vers Microsoft Graph afin d’obtenir la charge utile du message. Les appels GET retournent toujours l’état actuel du message. Si le message est modifié entre le moment de l’envoi de la notification et celui de la récupération du message, l’opération retourne le message mis à jour.

Voir aussi