Notifications de changement pour les ressources Outlook dans Microsoft Graph

  • Article

Microsoft API Graph vous permet de vous abonner aux modifications apportées à une ressource, y compris la création, la mise à jour ou la suppression de la ressource, et de recevoir des notifications via des webhooks. Un abonnement spécifie les types de modifications souhaités à surveiller pour une ressource spécifique et inclut une URL pour qu’un point de terminaison reçoive des notifications de ces modifications.

La configuration d’un abonnement réduit la surcharge liée à l’interrogation et à la comparaison des ressources pour déduire les modifications éventuelles. Vous pouvez éventuellement spécifier dans la demande d’abonnement de chiffrer et d’inclure dans le cadre d’une notification les données de ressource qui ont changé, en enregistrant un appel d’API distinct pour obtenir la charge utile de la ressource.

Il existe une limite maximale de 1 000 abonnements actifs pour les ressources Outlook par boîte aux lettres pour toutes les applications. Vous pouvez vous abonner aux modifications apportées aux contacts, aux événements ou aux messages dans la boîte aux lettres.

S’abonner aux modifications apportées aux contacts, au calendrier ou au courrier

Pour vous abonner aux notifications de modification des ressources Outlook, commencez par créer un abonnement.

Les ressources Outlook suivantes prennent en charge les abonnements avec ou sans données de ressource dans la charge utile de notification de modification.

Création d’un abonnement

Pour créer un abonnement, spécifiez la ressource Outlook et le type de modifications (création, mise à jour ou suppression) pour lesquelles vous souhaitez recevoir des notifications. Consultez un exemple.

Demander des autorisations

La création et la gestion (obtention, mise à jour et suppression) d’un abonnement nécessitent une étendue de lecture de la ressource. Par exemple, pour recevoir des notifications de modification sur les messages, votre application a besoin de l’autorisation Mail Read. Les notifications de modification Outlook prennent en charge les étendues d’autorisation déléguées et d’application. Notez les limitations suivantes :

  • L’autorisation déléguée permet de s'abonner à des articles dans des dossiers qui se trouvent uniquement dans la boîte aux lettres de l'utilisateur connecté. Par exemple, vous ne pouvez pas utiliser l’autorisation déléguée Calendars.Read pour vous abonner à des événements dans la boîte aux lettres d’un autre utilisateur.

  • Pour vous abonner afin de modifier les notifications de contacts, d’événements ou de messages dans Outlook dans dossierspartagés ou délégués:

    • Permet de s’abonner aux modifications d’éléments dans un dossier ou une boîte aux lettres de l’autorisation d’application correspondante n’importe quel utilisateur dans le client.
    • N’utilisez pas les autorisations de partage Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared et leurs équivalents en lecture/écriture), car elles ne prennent pas en charge l’abonnement aux notifications de modification sur les éléments des dossiers partagés ou délégués.

Selon la ressource, utilisez l’autorisation la moins spécifiée dans le tableau suivant pour appeler cette API.

Ressource Chemins d'accès aux ressources pris en charge Déléguée (compte professionnel ou scolaire) Déléguée (compte Microsoft personnel) Application
contact Modification de tous les contacts personnels dans la boîte aux lettres d’un utilisateur :
/me/contacts
/users/{id}/contacts
Modifications apportées aux contacts dans le dossier de contacts d’un utilisateur :
/users/{id}/contactFolders/{id}/contacts		 Contacts.Read Contacts.Read Contacts.Read
event Modifications de tous les évènements dans la boîte aux lettres d’un utilisateur :
/me/events
/users/{id}/events		 Calendars.Read Calendars.Read Calendars.Read
message Modification de tous les messages dans la boîte aux lettres d’un utilisateur :
/me/messages
/users/{id}/messages
Modification des messages dans le dossier de courrier électronique d’un utilisateur :
/users/{id}/mailFolders/{id}/messages		 Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read

Inclure des données de ressource dans la charge utile de notification

Pour que les données de ressources figurent dans une notification de modification, vous devez spécifier les propriétés suivantes, en plus de celles que vous incluez normalement lors de la création d’un abonnement :

  • includeResourceData : définissez cette propriété sur true pour demander explicitement des données de ressource.

  • resource : cette propriété spécifie l’URL de la ressource. Veillez à utiliser le paramètre de requête $select pour spécifier explicitement les propriétés de ressource Outlook à inclure dans la charge utile de notification.

    Remarque

    N’incluez pas dans l’URL $top, $skip, $orderby, $select=Body,UniqueBodyet $expand autres que singleValueExtendedProperties ou multiValueExtendedProperties.

  • encryptionCertificate : cette propriété contient uniquement la clé publique que Microsoft Graph utilise pour chiffrer des données de ressource. Conservez la clé privée correspondante pour déchiffrer le contenu.

  • encryptionCertificateId :cette propriété est votre propre identificateur pour le certificat. Utilisez cet ID pour faire correspondre dans chaque notification de modification, quel certificat utiliser pour le déchiffrement.

Consultez un exemple pour vous abonner aux notifications de modification avec les données de ressource pour la ressource message.

Affiner les conditions d’une notification

Vous pouvez affiner les conditions d’une notification en utilisant le paramètre de requête $filter. Consultez un exemple.

Une application courante de $filter consiste à recevoir une notification en cas de modification d’une propriété de ressource spécifique. Par exemple, vous pouvez utiliser $filter pour vous abonner aux messages non lus dans un dossier (la propriété isReadest false), et inclure tous les types de modification :

  • Un message ajouté ou marqué non lu dans le dossier déclencherait une notification Created.
  • Lire un message ou le marquer comme lu dans le dossier déclencherait une notification Deleted.
  • Une modification d’une propriété, autre que IsRead, d’un message dans le dossier déclencherait une Updated notification.

Si vous n’utilisez pas de $filter lors de la création de l’abonnement :

  • L’ajout d’un message au dossier entraînerait une notification Created.
  • La lecture d’un message dans le dossier, le marquage du message comme lu, ou la modification de toute autre propriété de message d’un message dans ce dossier se traduirait par une notification Updated.
  • La suppression du message entraînerait une notification Delete.

S’abonner aux notifications de cycle de vie

Le contact, événement, et messagedes ressources Outlook prennent aussi en charge les abonnements aux notifications de cycle de vie. Des notifications de cycle de vie sont nécessaires au cas où votre application supprimerait ses abonnements ou manquerait certaines notifications de modification. Les applications doivent implémenter une logique pour détecter et récupérer à partir de la perte et reprendre un flux de notifications de modification continu. Pour en savoir plus, consultez abonnement aux notifications de cycle de vie.

Suivre la durée de vie de l’abonnement

Veillez à prolonger un abonnement avant son expiration. La durée maximale à vie pour un abonnement sans données de ressource Outlook est de 4230 minutes (moins de 3 jours), et de 1 jour avec les données de ressource.

Si vous perdez l’autorisation accordée précédemment pour un abonnement et que l’abonnement expire pendant ce temps, demandez à nouveau l’autorisation à créer un nouvel abonnement.

Recevoir des charges utiles de notification

Selon votre abonnement, les notifications peuvent inclure des données de ressource. Les abonnements avec des données de ressource vous permettent d’obtenir la charge utile des ressources ainsi que la notification, ce qui évite la surcharge liée à un appel d’API distinct pour obtenir les données de ressource modifiées.

Recevoir des notifications avec des données de ressource

Voici un exemple de charge utile d’une notification avec les données de ressource d’une ressource message. Les propriétés resource et resourceData correspondent au message instance qui a déclenché la notification. Utilisez la propriété encryptedContent pour déchiffrer les données de ressource.

{
    "value": [
      {
        "subscriptionId": "dfd11b2f-8222-4189-9545-4205c95d6235",
        "subscriptionExpirationDateTime": "2021-12-31T16:16:44.9907405+05:30",
        "changeType": "created",
        "resource": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
        "clientState": "<<--SpecifiedClientState-->>",
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
        "encryptedContent": {
          "data": "<<--EncryptedContent-->>",
          "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
          "dataSignature": "Qw/9ubWeUYJPWWXvNiGgct2FkNG2MXTRm/BLUpJM66k=",
          "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
          "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "resourceData": {
          "@odata.type": "#microsoft.graph.message",
          "@odata.id": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
          "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUR8n\"",
          "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA="
        }
      }
    ]
    "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.

Voici un exemple de charge utile de notification déchiffrée. La charge utile déchiffrée est conforme au schéma de message Outlook. La charge utile est similaire à celle retournée par une opération obtenir un message. Toutefois, la charge utile de notification contient uniquement les propriétés spécifiées avec un $selectparamètre dans la propriété ressourcede l’abonnement. Les charges utiles de notification pour d’autres ressources Outlook telles que contact et événement suivent leurs schémas respectifs.

{
    "receivedDateTime@odata.type":"#DateTimeOffset",
    "receivedDateTime":"2021-12-30T10:53:35Z",
    "subject":"TEST MESSAGE FOR RICH NOTIFICATIONS",
    "bodyPreview":"Hello,\r\n\r\nWhat\u2019s up?\r\n\r\nThanks\r\nMegan",
    "importance@odata.type":"#microsoft.graph.importance",
    "importance":"normal",
    "from": {
        "@odata.type":"#microsoft.graph.recipient",
        "emailAddress": {
            "@odata.type":"#microsoft.graph.emailAddress",
            "name":"Megan Brown",
            "address":"Megan.Brown@microsoft.com"
        }
    }
}

Recevoir les 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 la ressource. 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).

L’exemple suivant montre la charge utile d’une notification qui correspond à une ressource message Outlook. La notification réelle inclut les propriétés ressource et resourceData qui représentent la ressource qui a déclenché la notification. Utilisez 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 de la ressource.

Remarque

Les appels GET retournent toujours l’état actuel de la ressource. Si la ressource est modifiée entre le moment où la notification est envoyée et l’heure à laquelle la ressource est récupérée, l’opération retourne l’état de la ressource lors de la récupération.

"value": [
 {
   "subscriptionId": "c6126aa3-0ed8-412f-a988-71e6cee627c4",
   "subscriptionExpirationDateTime": "2022-01-02T03:12:18.2257768+05:30",
   "changeType": "created",
   "resource": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIxAAA=",
   "resourceData": {
     "@odata.type": "#Microsoft.Graph.Message",
     "@odata.id": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIAAA=",
     "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUUXn\"",
     "id": "AAMkAGUwNjQ4ZjIxAAA="
   },
   "clientState": "<<--SpecifiedClientState-->>",
   "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
 }
]

Exemples

Exemple 1 : Créer un abonnement pour recevoir des notifications de modification sans données de ressource lorsque l’utilisateur reçoit un nouveau message

L’exemple suivant demande une notification pour un message en cours de création dans la boîte aux lettres de l’utilisateur.

Demande

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "expirationDateTime": "2021-07-07T21:42:18.2257768+00:00",
    "clientState": "secretClientState"
}

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "5522bd62-7c96-4530-85b0-00b916f6151a",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientState",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T21:42:18.2257768Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": null,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": null,
    "encryptionCertificateId": null,
    "notificationUrlAppId": null
}

Exemple 2 : Créer un abonnement pour recevoir des notifications de modification avec des données de ressource lorsque l’utilisateur reçoit un nouveau message

L’exemple suivant s’abonne aux notifications avec des données de ressource pour un message en cours de création dans la boîte aux lettres de l’utilisateur. Les propriétés de la ressource message à inclure dans la charge utile de notification sont spécifiées à l’aide du paramètre de requête $select.

Demande

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "178eec5f-cf3c-4e7e-8a9c-8640deb5b5c5",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

Exemple 3 : Créer un abonnement pour obtenir des notifications de modification avec des données de ressources pour un message basé sur une condition

L’exemple suivant s’abonne aux notifications avec des données de ressource pour un message en cours de création dans le dossier Brouillons, contenant une ou plusieurs pièces jointes et d’une importance élevée.

Demande

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "239dbc5f-cf3c-4e7e-8c9c-3340abc5b5c5",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-20T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

Contenu connexe