Référence de l'API REST de notifications Outlook diffusées en continu (préversion)

  • Article

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

Notes

Cette version de la documentation traite de l'API de notifications en diffusion continue. Celle-ci est en préversion. Les fonctionnalités de la préversion sont sujettes à modifications avant leur finalisation. Elles peuvent donc entraîner des erreurs de code. C'est pourquoi il est fortement conseillé de n'utiliser que les versions de production d'une API dans votre code en production. La version v2.0 est actuellement privilégiée lorsqu'elle est disponible.

L'API REST de notifications Outlook diffusées en continu envoie des notifications à travers une connexion directe, et permet aux applications du client de connaître les 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.

Vue d'ensemble

Le service de notifications diffusées en continu d'Office 365 établit une connexion directe avec un client et fournit des notifications concernant les données demandées par une application cliente.

Lorsqu'une application s'abonne aux notifications pour un type d'événement sur une ressource spécifique (comme par exemple des message dans la boîte aux lettres de l'utilisateur), une connexion à long terme est établie entre le serveur Office 365 et le client. Dès qu'un événement déclencheur se produit (comme par exemple l'arrivée d'un nouveau message dans la boîte aux lettres), le service Office 365 diffuse une notification vers le client. Le client analyse la notification et effectue des actions correspondant à sa logique métier : obtenir le nouveau message et mettre à jour le nombre de message non lus, par exemple.

Comparaison entre diffusion en continu et notification Push

Les applications courrier, calendrier et applications CRM utilisent généralement des notifications pour mettre à jour leur cache local, les vues client correspondantes ou le système principal après des modifications. Outlook prend en charge à la fois la diffusion en continu et les notifications push. notifications. Les notifications push exigent que le client fournisse un service écouteur web pour obtenir des notifications à partir du serveur Office 365, tandis que les notifications de diffusion en continu exigent uniquement une connexion directe entre le client et le serveur Office 365. Une fois qu’une connexion avec le serveur est établie, elle reste ouverte pour une période spécifiée. Pendant cette période, le client publie une seule fois une requête GetNotifications à longue durée de vie ; chaque fois qu’un événement déclencheur se produit, le serveur peut simplement envoyer une notification dans le cadre du flux de réponse. Cela se poursuit jusqu'à ce que la connexion arrive à expiration, que le client supprime la connexion ou qu'un problème se produise dans le réseau.

Utiliser l'API REST de notifications diffusées en continu

Authentification

Pour vous abonner, obtenir et fermer des notifications, spécifiez les étendues nécessaire à tous les types de ressources pour lesquels vous désirez recevoir des notifications.

É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 Outlook diffusées en continu nécessite un jeton d'accès valide. Pour obtenir un jeton d'accès, vous devez avoir enregistré et identifié votre application et obtenu l'autorisation appropriée.

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

Version de l'API

L'API est actuellement en état de préversion, et n'est disponible que sur le point de terminaison d'API REST bêta :

https://outlook.office.com/api/beta/

Utilisateur cible

Les demandes à l'API de notifications diffusées en continu sont systématiquement effectuées au nom de l'utilisateur actuel.

Opérations de notification diffusées en continu

S'abonner à des modifications dans mes e-mails, mon agenda, mes contacts ou mes tâches

Permet de s'abonner aux notification diffusées en continu lorsque les e-mails, les événements de l'agenda, les contacts ou les tâches changent dans une boîte aux lettres 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/beta/me/subscriptions

Dans le corps de la demande, spécifiez les propriétés suivantes. Elles sont obligatoires pour une demande d'abonnement à une diffusion continue de notifications. Pour plus d'informations, voir  Entités de notification.

  • odata.type - Inclut "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription".

  • ChangeType  - Spécifie les types d'événements à suivre pour cette ressource. Voir ChangeType pour consulter les types pris en charge.

  • Resource  - Spécifie la ressource à suivre et sur laquelle recevoir des notifications. Vous pouvez utiliser les paramètres de requête facultatifs $filter ou $select pour affiner les conditions d'une notification ou 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/beta/me/mailfolders('inbox')/messages

      https://outlook.office.com/api/beta/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/beta/me/messages

      https://outlook.office.com/api/beta/me/events

      https://outlook.office.com/api/beta/me/contacts

      https://outlook.office.com/api/beta/me/tasks

Si la demande d'abonnement aboutit, un identifiant d'abonnement est renvoyé. Par défaut, cet ID d'abonnement expire en 90 minutes, sauf si le client commence à écouter les notifications sur une connexion. L'abonnement est alors automatiquement renouvelé tant que la connexion reste ouverte.

Exemple de demande d'abonnement

La requête suivante crée un abonnement à une diffusion en continu des changements de création, de mise à jour et de suppression dans la boîte de réception de l'utilisateur.

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

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
   ChangeType: "Created,Updated,Deleted"
}

Exemple de réponse à l'abonnement

Une réponse positive inclut HTTP 201 et l'ID d'abonnement. Voici un exemple de réponse :

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('RUM4OEJFNUIQUQ4MQ==')",
    "Id":"RUM4OEJFNUIQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Affiner les conditions de notification

Vous pouvez limiter les notifications à un sous-ensemble d'éléments en utilisant une clause $filter. La demande d'abonnement suivante crée par exemple un abonnement qui ne déclenche de notification que lorsque des modifications sont apportées aux messages dont le champ d'objet est « Supplément ».

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

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
   ChangeType: "Created,Updated,Deleted"
}

Une réponse positive ressemble à cela :

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('MjcwOUQ2MjEtQUQ4MQ==')",
    "Id":"MjcwOUQ2MjEtQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

S'abonner aux notifications riches à diffusion continue

Un abonnement qui a été configuré pour une simple collection de ressources renvoie l'ID de l'instance de ressource qui a été modifiée. Vous devez donc obtenir séparément chaque propriété de l'instance. La première demande d'abonnement présentée plus haut constitue un bon exemple de ce type d'abonnements. La transmission de notifications en continu présentée dans la section suivante montre que seul l'ID de ressources est renvoyé dans la notification.

Vous pouvez également utiliser un paramètre $select dans la demande d'abonnement et spécifier les propriétés qui vous intéressent pour que les valeurs de ces propriétés vous soient également renvoyées au sein de la transmission de notifications en continu.

Voici un exemple qui permet de demander des notifications en diffusion continue incluant la propriété « objet » (Subject) lorsqu'un événement a été créé :

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

{
    @odata.type:"#Microsoft.OutlookServices.StreamingSubscription",
    Resource: "https://outlook.office.com/api/beta/me/events?$select=Subject",
    ChangeType: "Created"
}

Après vous êtes abonné à des notifications riches en diffusion continue, écoutez les notifications pour obtenir la propriété Subject dans la charge utile de la notification riche.

Écouter les notifications

Le client créé une connexion POST à long terme pour les abonnements spécifiés, afin de demander au serveur de démarrer la diffusion continue de notifications.

POST https://outlook.office.com/api/beta/Me/GetNotifications

Cette demande POST ne se termine que lorsque le ConnectionTimeoutinMinutes spécifié est atteint et que le serveur met fin au blob JSON de la réponse, ou lorsqu'un problème survient et que le client ou le serveur ferme la connexion.

Tant que la connexion reste ouverte, tous les abonnements utilisant la connexion sont automatiquement renouvelés. Si la connexion prend fin, ces abonnements expireront en 90 minutes, à moins que le client ne configure une nouvelle connexion pour ces abonnements.

Assurez vous que les éléments de votre code qui effectuent la demande POST gèrent bien le code d'état HTTP 404 Not found qui sera renvoyé si un abonnement spécifique a expiré. Si cela arrive, demandez un nouvel abonnement avant d'écouter à nouveau ses notifications.

Paramètre de corps requis Type Description
ConnectionTimeoutInMinutes int32 Le nombre de minutes pendant laquelle la connexion doit rester active.
KeepAliveNotificationIntervalInSeconds int32 L'intervalle utilisée par le serveur pour envoyer des notifications de persistance qui préviennent le client que la connexion reste ouverte.
SubscriptionIds Collection(String) Identifiants des abonnements pour lesquels des notifications seront envoyées sur cette connexion.

Exemples de demande d'écoute

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg=="
   ]
}

Vous pouvez utiliser la même connexion à long terme pour écouter les notifications de plusieurs abonnements. Il vous suffit pour cela d'inclure plusieurs ID d'abonnement dans la demande POST.

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg==",
       "Dc4NS04MTg2LUYwRjFFNUVFNTNDRgN0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtN=="
   ]
}

Exemple de diffusion continue de notifications

Une fois le service installé, le client reçoit le début du blob JSON de notifications.

{
    {"@odata.context":"https://outlook.office.com/api/beta/metadata#Notifications", 
    "value": [

Le serveur envoie une notification de persistance à intervalles fixes afin que la connexion reste ouverte et active. Cet intervalle est défini par le client dans la propriété KeepAliveNotificationIntervalInSeconds. Le format de la notification de persistance est le suivant :

{
    "@odata.type": "#Microsoft.OutlookServices.KeepAliveNotification",
    "Status": "OK"
}

Lorsque l'un des changements suivis se produit sur le serveur, celui-ci utilise la connexion pour envoyer une notification au client. Pour chaque notification, le serveur définit la propriété SubscriptionExpirationDateTime et la renouvelle en permanence, tant que la notification précédente réussit.

{ 
    "@odata.type": "#Microsoft.OutlookServices.Notification",
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    "SubscriptionExpirationDateTime": "2016-09-09T18:36:42.3454926Z",
    "SequenceNumber": 9, 
    "ChangeType": "Created", 
    "Resource": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
    "ResourceData": { 
        "@odata.type": "#Microsoft.OutlookServices.Message", 
        "@odata.id": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
        "@odata.etag": "W/\"CQAAABYAAAB+0z/4Ly/1ToDr5FGl5k99AAABl5Do\"", 
        "Id": "AAMkADdlAA=" 
    } 
}

Lorsque votre application est à l'écoute de plusieurs notifications sur la même connexion à long terme, vous pouvez utiliser le champ SubscriptionId pour déterminer l'abonnement qui a envoyé la notification.

Notes

À partir de la deuxième notification envoyée par le serveur et pour toutes les suivantes, une virgule est présente avant le crochet ouvrant pour assurer la validité du JSON.

,{
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    ...
}

Exemple de charge utile de notification riche

Si votre demande d'abonnement spécifie certaines propriétés à renvoyer, les charges utiles des notifications incluront les valeurs de ces propriétés. Dans la continuité de l'exemple d'abonnement à des notifications riches présenté plus haut, la charge utile d'une notification incluant la propriété Subject peut ressembler à cela :

{
  "@odata.context": "https://outlook.office.com/api/beta/$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/beta/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/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Fermer la connexion

Lorsque le délai d'expiration spécifié dans la propriété ConnectionTimeoutInMinutes est atteint, le serveur ferme la connexion et envoie la fin du blob JSON, comme suit :

    ]
}

La connexion peut être abandonnée dans d'autres circonstances, comme par exemple en cas de problèmes de réseau ou de modifications apportées au serveur (redémarrage, etc.). Le client peut utiliser les notifications de persistance pour déterminer si la connexion est toujours active ou si elle a été abandonnée. Dans ce dernier cas, le client tente de se reconnecter en utilisant l'ID d'abonnement existant. Si l'ID d'abonnement a expiré, une nouvelle demande d'abonnement doit être effectuée pour ré-établir la connexion.

Si le client ne veut plus écouter un abonnement, il doit annuler la demande POST et abandonner la connexion. La prochaine fois que le serveur tentera d'envoyer une notification, il recevra un erreur, détectera que la connexion a été abandonnée, arrêtera l'envoi de notifications de persistance et fermera la connexion.

Entités de notification et énumérations

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 des événements qui déclencheront une notification. Voir ChangeType pour consulter les types pris en charge. Oui S/O

Notification

Représente une notification envoyée au client.

Type de base : Entité

Propriété Type Description Accessible en écriture ? Filtrable
SubscriptionId chaîne Identifiant unique de l’abonnement. Non S/O
SequenceNumber int32 Indique la valeur de séquence de la notification de modification. Non S/O
ChangeType chaîne Indique le type d'événement ayant déclenché la notification. Voir ChangeType pour consulter les types pris en charge. Non S/O
Ressource chaîne Spécifie l'élément de ressource dont les modifications sont suivies Non S/O
ResourceData Entity Identifie l'entité qui a été modifiée. Il s'agit d'une propriété de navigation Non S/O

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
  • Supprimé
  • Absent. 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 :