Référence des API de REST de Notifications Push Outlook (version 2.0)

  • Article

S’applique à : Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

L’API REST de notifications Push d’Outlook envoie des notifications au moyen d’un webhook au service web côté client pour notifier les applications au sujet des modifications apportées aux données de la boîte aux lettres de l’utilisateur. Les données peuvent concerner les e-mails de l'utilisateur, son agenda, ses contacts ou ses tâches. Elles sont sécurisées par Azure Active Directory dans Office 365 ou sur les comptes Microsoft spécifiques à ces domaines : Hotmail.com, Live.com, MSN.com, Outlook.com et Passport.com.

Notes

Afin de simplifier les explications, le reste de l’article utilise Outlook.com pour inclure ces domaines de comptes Microsoft.

La version 2.0 de l’API ne vous intéresse pas ? Dans la table des matières sur la gauche, accédez à la section Référence API REST Office 365 et sélectionnez la version souhaitée.

Vue d’ensemble

Le service de notifications Push et l’API d’Office 365 fonctionne avec les clients qui fournissent un service web avec une adresse de rappel et utilisent des webhooks pour envoyer des notifications aux applications clientes. Les webhooks sont des rappels HTTP configurés par un service Web backend d’un tiers de confiance. Le service Web peut configurer les webhooks pour provoquer des événements déclencheurs sur un site pour invoquer un comportement sur un autre.

Lorsqu’une application s’abonne aux notifications d’une ressource spécifique (comme les messages dans la boîte de réception de l’utilisateur), elle spécifie une URL de rappel de webhook dans la demande d’abonnement. Dès qu’un événement déclencheur se produit (comme l’arrivée d’un nouveau message dans la boîte aux lettres), le service de notification d’Office 365 envoie une notification par le biais d’un webhook à l’URL de rappel. L’application, à son tour, effectue des actions correspondant à sa logique métier, comme l’obtention du nouveau message et la mise à jour du compte non lu.

Les applications doivent renouveler leurs abonnements avant leur expiration. Elles peuvent également annuler leurs abonnements à tout moment pour ne plus recevoir de notifications.

Comparaison entre diffusion en continu et notification Push

Les applications d’e-mails, d’agendas et de gestion de clientèle utilisent généralement des notifications qui permettent de mettre à jour leur cache local, les vues client correspondantes ou le système dorsal, dès qu’un changement survient. Outlook prend en charge la diffusion en continu et les notifications Push. Actuellement, les notifications Push sont couramment utilisées par les applications mobiles, car les clients n’ont pas besoin de rechercher les modifications, et elles rendent les mises à jour à la disposition des clients presque immédiatement.

En comparaison avec les notifications diffusées en continu, les notifications Push nécessitent que le client fournisse son propre service Web afin d’obtenir des notifications, tandis que les notifications diffusées en continu nécessitent uniquement une connexion directe entre le client et le service de notifications en continu d’Office 365.

Utilisation de l’API REST des notifications Push

Authentification

Pour vous abonner, interroger, renouveler et supprimer des abonnements, spécifiez les étendues appropriées pour les types de ressources pour lesquelles vous souhaitez être notifié.

Étendue minimale requise

L’une des étendues en lecture suivantes correspondant à la ressource ciblée :

Comme pour toutes les autres API REST Outlook, chaque demande à l'API de notifications Push d’Outlook nécessite un jeton d'accès valide. Pour obtenir un jeton d’accès, vous devez avoir inscrit et identifié votre application, et obtenu l’autorisation appropriée.

Vous pouvez en apprendre plus sur certaines options d’inscription et d’autorisation simplifiées pour vous. Gardez cet élément à l'esprit lorsque vous effectuez les opérations spécifiques à l'API de notifications Push.

Version de l’API

Cette API a été promue de la préversion au statut de disponibilité générale (GA). Elle est prise en charge dans les versions v2.0 et bêta de l’API REST d’Outlook.

Utilisateur cible

Les demandes à l’API de notifications Push sont systématiquement effectuées au nom de l’utilisateur actuel.

Voir Utiliser l’API REST Outlook pour plus d’informations communes à tous les sous-ensembles de l’API REST Outlook.

Opérations de notification Push

S’abonner aux modifications dans mes e-mails, mon agenda, mes contacts ou mes tâches

Processus d’abonnement

Le processus d’abonnement se déroule comme suit :

  1. Une application cliente effectue une demande d’abonnement (POST) pour une ressource spécifique. Elle inclut une URL de notification, entre autres propriétés.

  2. Le service de notifications Outlook tente de valider l’URL de notification avec le service d’écoute. Il inclut un jeton de validation dans la demande de validation.

  3. Si le service d’écoute valide l’URL, il renvoie une réponse de succès dans les 5 secondes comme suit :

    • Il définit le type de contenu dans l’en-tête de la réponse sur text\plain.
    • Il inclut le même jeton de validation dans le corps de la réponse.
    • Il renvoie un code de réponse HTTP 200. L’écouteur peut rejeter le jeton de validation par la suite.

  4. En fonction du résultat de la validation de l’URL, le service de notifications Outlook envoie une réponse à l’application cliente :

    • Si la validation de l’URL a abouti, le service crée l’abonnement avec un ID d’abonnement unique et envoie la réponse au client.
    • Si la validation d’URL a échoué, le service envoie une réponse d'erreur avec un code d’erreur et d’autres détails.

  5. Dès réception d’une réponse réussie, l’application client stocke l’ID d’abonnement pour corréler les notifications futures avec cet abonnement.

Demande d’abonnement

Permet de s’abonner à un service d’écoute pour recevoir des notifications lorsque des messages, des événements d’agenda, des contacts ou des tâches changent dans Office 365 ou Outlook.com. Il s'agit de la première étape pour permettre au client de recevoir des notifications à partir d'une ressource (une entité ou une collection d'entités).

POST https://outlook.office.com/api/v2.0/me/subscriptions

Dans le corps de la demande, spécifiez les propriétés suivantes pour une demande d’abonnement Push des notifications. À l’exception de ClientState, toutes les propriétés sont requises. Pour plus d’informations, voir  Entités de notification.

  • odata.type - Inclut "@odata.type":"#Microsoft.OutlookServices.PushSubscription". L’entité PushSubscription définit NotificationURL.
  • ChangeType  - Spécifie les types d’événements à suivre pour cette ressource. Voir ChangeType pour consulter les types pris en charge.
  • ClientState - Propriété facultative qui indique que chaque notification doit être envoyée avec un en-tête par la même valeur ClientState. Cela permet à l’auditeur de vérifier la légitimité de chaque notification.
  • NotificationURL - Spécifie où les notifications doivent être envoyées. Cette URL représente un service Web généralement mis en œuvre par le client.
  • Resource  - Spécifie la ressource à suivre et sur laquelle recevoir des notifications. Vous pouvez utiliser les paramètres de requête facultatifs $filter pour affiner les conditions d’une notification ou $select pour inclure des propriétés spécifiques dans une notification riche.

Voici les ressources prises en charge :

  • Un dossier ordinaire ou un dossier de recherche pour les messages, les événements, les contacts ou les tâches. Exemples :

    https://outlook.office.com/api/v2.0/me/mailfolders('inbox')/messages

    https://outlook.office.com/api/v2.0/me/taskfolders('{folder_id}')/tasks

  • Ou une collection de messages, d’événements, de contacts ou de tâche appartenant à une entité de niveau supérieur telle que :

    https://outlook.office.com/api/v2.0/me/messages

    https://outlook.office.com/api/v2.0/me/events

    https://outlook.office.com/api/v2.0/me/contacts

    https://outlook.office.com/api/v2.0/me/tasks

Exemple de demande

L’exemple suivant montre comment s’abonner à de nouveaux événements.

POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
   "Resource": "https://outlook.office.com/api/v2.0/me/events",
   "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",  
   "ChangeType": "Created",
   "ClientState": "c75831bd-fad3-4191-9a66-280a48528679"
}

Affiner les conditions de notification

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

L’exemple suivant demande une notification pour un Message étant créé dans le dossier Brouillons, contenant une ou plusieurs pièces jointes, et dont l’importance est  High :

POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('Drafts')/messages?$filter=HasAttachments%20eq%20true%20AND%20Importance%20eq%20%27High%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Has attachments and high importance" 
}

L’exemple suivant demande une notification pour la création d’un événement durant toute la journée :

POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/events?$filter=IsAllDay%20eq%20true", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Notifications for events that IsAllDay." 
}

L’exemple suivant demande une notification pour un Contact créé avec la société nommée Contoso :

POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/contacts?$filter=CompanyName%20eq%20%27Contoso%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Contacts in Contoso." 
}

Une application commune de $filter doit obtenir une notification sur une modification dans une propriété spécifique de la ressource spécifiée.

Par exemple, vous pouvez utiliser $filter pour vous abonner à des messages non lus dans un dossier (la propriété IsRead est 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 notification Updated.

Vous pouvez créer un tel abonnement comme suit :

POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages$filter=IsRead%20eq%20false",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Si vous n’utilisez pas $filter lors de la création de l’abonnement (comme ci-dessous) :

  • 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.
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages,
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Demande de validation

La demande de validation tente de valider l’URL de notification spécifiée par une application cliente dans une demande d’abonnement :

POST https://{notificationUrl}?validationToken={token}

Le service Outlook spécifie l’URL de notification dans la demande d’abonnement dans {notificationUrl} et définit une chaîne {token} comme jeton de validation. Le service Outlook inclut également un en-tête ClientState si l’application cliente en inclut un dans la demande d’abonnement.

Réponse à l’abonnement

La réponse d’abonnement inclut les propriétés de la demande et les propriétés supplémentaires suivantes :

  • Id - L’ID d’abonnement unique que l’application cliente doit enregistrer afin de correspondre aux futures notifications.
  • ChangeType - Outre les valeurs spécifiées dans la requête, la réponse inclut le type de notification supplémentaire, Missed.
  • SubscriptionExpirationDateTime - La date et l’heure d’expiration de l’abonnement. Si la demande d’abonnement ne spécifie pas de délai d’expiration ou si la demande spécifie un délai d’expiration supérieur au maximum autorisé, cette propriété sera définie sur la longueur maximale autorisée à compter de l’envoi de la demande. Pour un abonnement qui demande des notifications détaillées de propriétés spécifiques, le maximum autorisé est de 1 jour. Pour les autres abonnements, le maximum est de 7 jours.
  • Autres propriétés liées à OData.

Exemple de données de réponse

Cette réponse indique que le service d’écoute doit s’attendre à recevoir des notifications pour les nouveaux événements et les modifications manquées. S’il y a des changements manqués, le client devra se synchroniser avec le service pour les capturer.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Subscriptions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
    "Id": "Mjk3QNERDQQ==",
    "Resource": "https://outlook.office.com/api/v2.0/me/events",
    "ChangeType": "Created, Missed",
    "ClientState": "c75831bd-fad3-4191-9a66-280a48528679",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
    "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z"
}

Requête à un abonnement

Vous pouvez obtenir des détails sur les abonnements existants de l’utilisateur connecté en spécifiant son ID d’abonnement. Par exemple, pour interroger l’abonnement créé dans le dernier exemple :

GET https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')

En cas de succès, la réponse sera la même que celle du dernier exemple de réponse, à la différence qu’elle exclurait tout ClientState spécifié par l’application client pour éviter tout risque de sécurité potentiel.

Notifications

Chaque notification contient les propriétés suivantes, quel que soit son type :

  • En-tête ClientState - Présent uniquement si le client a spécifié la propriété ClientState dans la demande d’abonnement. Utilisé par l’auditeur pour vérifier la légitimité de la notification.
  • SubscriptionId - Identifie pour l’application cliente l’abonnement auquel cette notification appartient.
  • SubscriptionExpirationDateTime - La date et l’heure d’expiration de l’abonnement.
  • SequenceNumber - Un numéro de séquence pour une notification, pour aider l’application cliente à identifier si elle manque une notification.
  • ChangeType - Les types d’événements sur lesquels l’application cliente souhaite être notifiée (par exemple, un type d’événement Created lorsqu’un courrier est reçu, ou un type d’événement Update lors de la lecture d’un message).
  • Resource - L’URL de l’élément de ressource spécifique surveillé (par exemple, une URL du message ou de l’événement modifié).
  • ResourceData - Une notification liée à une modification de ressource (telle que la réception, la lecture ou la suppression d’un message) a cette propriété supplémentaire qui contient l’ID de ressource de l’élément qui a été modifié. Un client peut utiliser cet ID de ressource pour gérer cet élément en fonction de sa logique métier (par exemple, récupérer cet élément, synchroniser son dossier).

Notes

La propriété Id n’est pas utilisée dans les entités Notification.

Modifier la charge utile de notification

Dans l’exemple suivant, lorsque l’utilisateur reçoit un nouvel événement, le service de notifications envoie une notification avec ChangeType défini sur « Created ». L’en-tête de la notification inclurait le ClientState spécifié dans la demande d’abonnement initiale. La notification d’événement de réception contient une charge utile similaire à celle ci-après :

{
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.Notification",
            "Id": null,
            "SubscriptionId": "Mjk3QNERDQQ==",
            "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z",
            "SequenceNumber": 1,
            "ChangeType": "Created",
            "Resource" : "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
            "ResourceData": {
                "@odata.type": "#Microsoft.OutlookServices.Event",
                "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
                "Id": "AAMkADNkNmAA="
            }
        }
    ]
}

Obtenir les propriétés d’une instance en s’abonnant à des notifications détaillées

Comme illustré dans le dernier exemple de charge utile d’une notification de modification, un abonnement de notification push configuré pour une collection de ressources renvoie uniquement l’ID d’une instance de ressource qui a été modifiée. Vous devez donc obtenir séparément chaque propriété de l’instance.

Vous pouvez enregistrer un appel API GET séparé si vous utilisez un paramètre $select dans la demande d’abonnement et spécifiez les propriétés qui vous intéressent. Voici un exemple qui permet de demander une notification Push incluant la propriété subject lorsqu’un événement a été créé :

POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json

{
    "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
    "Resource": "https://outlook.office.com/api/v2.0/me/events?$select=Subject",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
    "ChangeType": "Created"
}

Exemple de charge utile de notification riche

Une charge utile de notification riche comprend les valeurs des propriétés spécifiées dans la demande d’abonnement. Suivant le dernier exemple, une notification riche inclut la propriété Subject comme suit :

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Notifications",
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "QjQzNzAwBQQ==",
      "SubscriptionExpirationDateTime": "2017-01-18T00:57:28.6134733Z",
      "SequenceNumber": 1,
      "ChangeType": "Created",
      "Resource": "https://outlook.office.com/api/v2.0/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Event",
        "@odata.id": "https://outlook.office.com/api/v2.0/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Renouveler l’abonnement

Renouveler un abonnement jusqu’à la durée maximale à compter de la demande de renouvellement.

PATCH https://outlook.office.com/api/v2.0/me/subscriptions/{subscriptionId}

La durée d’abonnement par défaut est de 7 jours pour les demandes d’abonnement ne nécessitant pas de propriétés d’instance spécifiques dans la réponse et de 1 jour pour les abonnements aux notifications enrichies.

Vous pouvez soumettre la demande de renouvellement sans charge utile et l’abonnement sera prolongé de la période maximale correspondante.

Exemple de demande

PATCH https://outlook.office.com/api/v2.0/me/subscriptions/Mjk3QNERDQQ==

{
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   "SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}

Réponse

Une réponse de réussite est indiquée par un code de réponse HTTP 200.

Supprimer un abonnement

Supprimer un abonnement en spécifiant l’ID d’abonnement.

DELETE https://outlook.office.com/api/v2.0/me/subscriptions('{subscriptionId}')

Exemple de demande

Delete https://outlook.office.com/api/v2.0/me/subscriptions('Mjk3QNERDQQ==')

Réponse

Une réponse de réussite est indiquée par un code de réponse HTTP 204 No Content.

Entités et énumérations de l’API Notification

Abonnement

Représente l'abonnement de base. Il s'agit d'une classe de base abstraite.

Type de base : Entité

Propriété Type Description Accessible en écriture ? Filtrable ?
Resource chaîne Spécifie la ressource pour laquelle les modifications seront suivies. Oui S/O
ChangeType Changetype Indique le type d’événements qui déclenchera une notification. Voir ChangeType pour consulter les types pris en charge. Oui S/O

Notification

Représente une notification envoyée au client. Dans le cas de notifications push, la notification est envoyée au service d’écoute spécifié par le client.

Type de base : Entité

Propriété Type Description Accessible en écriture ? Filtrable ?
SubscriptionId chaîne Identifiant unique de l’abonnement. Non Non
SubscriptionExpirationDateTime Edm.DateTimeOffset Spécifie la date et l’heure d’expiration de l’abonnement à la notification. L’heure est exprimée en UTC. Oui S/O
SequenceNumber int32 Indique la valeur de séquence de la notification de modification. Non S/O
ChangeType ChangeType Indique le type d’événement ayant déclenché la notification. Les valeurs d'énumération sont : Créé = 1, Mis à jour = 2, Supprimé = 4, Manqué = 16. Une notification manquée se produit lorsque le service de notification ne peut pas envoyer la notification demandée. Non S/O
Resource chaîne Spécifie l’élément de ressource dont les modifications sont suivies. Oui S/O
ResourceData Entity Identifie l’entité qui a été modifiée. Ceci est une propriété de navigation. Non S/O

PushSubscription

Représente un abonnement qui utilise le mécanisme de notification push.

Type de base : Abonnement

Propriété Type Description Accessible en écriture ? Filtrable ?
NotificationURL chaîne L’URL de l’application qui recevra les notifications push. Oui S/O
SubscriptionExpirationDateTime Edm.DateTimeOffset Spécifie la date et l’heure d’expiration de l’abonnement à la notification. L’heure est exprimée en UTC. Oui S/O
ClientState chaîne Spécifie la valeur de l’en-tête ClientState envoyé par le service pour chaque notification. La longueur maximale est de 255 caractères. Le client peut vérifier que la notification provient du service en comparant la valeur définie sur la propriété ClientState avec la valeur de l’en-tête ClientState reçu avec chaque notification. Oui Non

ChangeType

Une énumération spécifiant les types d'événements se produisant sur les ressources prises en charge pouvant déclencher une notification.

Valeurs prises en charge :

  • Acknowledgment (accusé de réception)
  • Created
  • Deleted
  • Missed. Une notification Missed se produit lorsque le service de notification ne peut pas envoyer la notification demandée.
  • Updated

Étapes suivantes

Que vous soyez prêt à commencer à créer une application ou que vous souhaitiez simplement en apprendre plus, nous avons ce qu’il vous faut.

Ou, pour en savoir plus sur l’utilisation de la plateforme Office 365 :