Notifications de changement pour les ressources Outlook dans Microsoft Graph

L’API Graph Microsoft 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.

• contact
• event
• message

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 d’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 des éléments dans les 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.

Chemin d’accès de la ressource

La valeur de ressource identifie la boîte aux lettres à laquelle s’abonner, par exemple users/{id}/messages. Fournir un identificateur d’utilisateur qui résout une boîte aux lettres unique et sans ambiguïté ; sinon, la création d’abonnement peut échouer par intermittence avec une 503 ServiceUnavailable erreur, telle que « Les informations de la boîte aux lettres sont périmées ».

Si vous préférez utiliser un UPN et que celui-ci commence par un GUID, tel que 3f8c2a71-6d45-4e9b-a237-81c5f0d762ae@contoso.com, la partie précédant le @ symbole peut être mal interprétée comme un GUID de boîte aux lettres plutôt que comme un UPN. Pour éviter ce problème, utilisez le préfixe de la valeur afin AAD-UPN: qu’elle soit toujours traitée comme un nom UPN. Utilisez le AAD-UPN: préfixe uniquement lorsque la valeur est l’UPN d’un compte professionnel ou scolaire.

Pour obtenir un exemple utilisant le préfixe, consultez l’exempleAAD-UPN: 2.

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

Pour inclure les données de ressource 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 lors de la création de $filter 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 de vie maximale d’un abonnement sans données de ressources Outlook est indiquée dans le tableau de durée de vie de l’abonnement.

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

En fonction de votre abonnement, les notifications incluent des données sur les ressources. 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 à l’instance du message 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.

"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 à l’aide d’un UPN commençant par un GUID

L’exemple suivant s’abonne aux notifications relatives à la création d’un message dans la boîte aux lettres d’un utilisateur dont l’UPN commence par un GUID. La resource valeur utilise le préfixe de sorte qu’Exchange AAD-UPN: la traite comme un nom d’utilisateur(-trice). Pour plus d’informations, consultez Chemin d’accès de la ressource.

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/AAD-UPN:3f8c2a71-6d45-4e9b-a237-81c5f0d762ae@contoso.com/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/AAD-UPN:3f8c2a71-6d45-4e9b-a237-81c5f0d762ae@contoso.com/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 3 : 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 4 : créer un abonnement pour recevoir des notifications de modification avec les données de ressource d’un message en fonction d’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

• Notifications de modifications Microsoft Graph
• Configurer les notifications de modifications qui incluent des données de ressource
• Présentation des API de courrier Outlook
• Vue d’ensemble des API de contacts Outlook
• Présentation des API de calendrier Outlook