En-têtes de demande et de réponse des services de notifications Push (applications Windows Runtime)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Cette rubrique décrit les API Web de service à service et les protocoles nécessaires pour envoyer une notification Push.

Consultez la vue d’ensemble des services de notifications Push Windows (WNS) pour accéder à une description des concepts, des exigences et du fonctionnement des notifications push et de WNS.

Demande et réception d’un jeton d’accès

Cette section décrit les paramètres de demande et réponse impliqués lorsque vous vous authentifiez auprès des services de notifications Push Windows (WNS).

Demande de jeton d’accès

Une requête HTTP est envoyée au service WNS pour authentifier le service cloud et récupérer un jeton d’accès en retour. La requête est émise auprès du nom de domaine complet (FQDN) suivant en utilisant le protocole SSL (Secure Sockets Layer).

https://login.live.com/accesstoken.srf

Paramètres de demande de jeton

Le service cloud transmet les paramètres nécessaires dans le corps de la demande HTTP, en utilisant le format « application/x-www-form-urlencoded ». Veillez à ce que tous les paramètres soient codés URL.

Paramètre	Obligatoire/Facultatif	Description
grant_type	Obligatoire	Doit avoir la valeur « client_credentials ».
client_id	Obligatoire	Identificateur de sécurité du package (SID) pour votre service cloud, tel qu’il a été attribué lors de l’inscription de votre application au Windows Store.
client_secret	Obligatoire	Clé secrète pour votre service cloud telle qu’elle a été attribuée lors de l’inscription de votre application au Windows Store.
scope	Obligatoire	Doit avoir la valeur : Windows : « notify.windows.com » Windows Phone : « notify.windows.com » ou « s.notify.live.net »

Réponse de jeton d’accès

WNS authentifie le service cloud, et s’il réussit, répond avec le message « 200 OK », y compris le jeton d’accès. Sinon, WNS répond avec un code d’erreur HTTP approprié tel que le décrit l’ébauche de protocole OAuth 2.0.

Paramètres de réponse du jeton d’accès

La réponse HTTP retourne un jeton d’accès si le service cloud est authentifié. Ce jeton d’accès peut être utilisé dans des demandes de notification jusqu’à son expiration. La réponse HTTP utilise le type de média « application/json ».

Paramètre	Obligatoire/Facultatif	Description
access_token	Obligatoire	Jeton d’accès utilisé par le service cloud lorsqu’il envoie une notification.
token_type	Facultatif	Toujours retourné en tant que « transmission ».

Code de réponse

Code de réponse HTTP	Description
200 OK	Demande réussie.
400 Requête incorrecte	Échec de l’authentification. Voir l’ébauche OAuth Request for Comments (RFC) pour obtenir les paramètres de réponse.

Exemple

Cet exemple illustre une réponse d’authentification réussie :

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer"
 }

Envoi d’une demande de notification et réception d’une réponse

Cette section décrit les en-têtes impliqués dans une requête HTTP adressée au service WNS pour remettre une notification et ceux impliqués dans la réponse.

Envoyer une demande de notification
Envoyer une réponse de notification
Fonctionnalités HTTP non prises en charge

Envoyer une demande de notification

Lors de l’envoi d’une demande de notification, l’application appelante émet une requête HTTP via SSL, adressée à l’URI (Uniform Resource Identifier) du canal. "Content-Length" est un en-tête HTTP standard qui doit être spécifié dans la requête. Tous les autres en-têtes standards sont facultatifs ou ne sont pas pris en charge.

En outre, les en-têtes de requête personnalisés répertoriés ici peuvent être utilisés dans la demande de notification. Certains en-têtes sont obligatoires alors que d’autres sont facultatifs.

Paramètres des demandes

Nom d’en-tête	Obligatoire/Facultatif	Description
Authorization	Obligatoire	En-tête d’autorisation HTTP standard utilisé pour authentifier votre demande de notification. Votre service cloud fournit son jeton d’accès dans cet en-tête.
Content-Type	Obligatoire	En-tête d’autorisation HTTP standard. Pour les notifications toast, par vignette et par badge, cet en-tête doit être défini sur « text/xml ». Pour les notifications brutes, cet en-tête doit être défini sur « application/octet-stream ».
Content-Length	Obligatoire	En-tête d’autorisation HTPP standard utilisé pour indiquer la taille de la charge utile de la demande.
X-WNS-Type	Obligatoire	Définit le type de notification dans la charge utile : vignette, toast, badge ou brute.
X-WNS-Cache-Policy	Facultatif	Active ou désactive la mise en cache des notifications. Cet en-tête s’applique uniquement aux notifications par vignette et par badge, et aux notifications brutes.
X-WNS-RequestForStatus	Facultatif	Demande l’état du périphérique et de la connexion WNS dans la réponse de notification.
X-WNS-Tag	Facultatif	Chaîne utilisée pour fournir une notification avec une étiquette d’identification, utilisée pour les vignettes prenant en charge la file d’attente de notification. Cet en-tête s’applique uniquement aux notifications par vignette.
X-WNS-TTL	Facultatif	Valeur entière, exprimée en secondes, qui indique la durée de vie.
X-WNS-SuppressPopup	Facultatif	Windows Phone uniquement : remet une notification toast directement au centre de maintenance sans déclencher le toast lui-même.
X-WNS-Group	Facultatif	Windows Phone uniquement : utilisé avec l’en-têteX-WNS-Tag pour regrouper les notifications dans le Centre de maintenance.
X-WNS-Match	Obligatoire en fonction de la situation	Windows Phone uniquement : requis pour identifier la ou les cibles lorsque vous supprimez une notification toast du centre de maintenance via la méthode HTTP DELETE.

Remarques importantes

Content-Length et Content-Type sont les seuls en-têtes HTTP standards inclus dans la notification remise au client, que d’autres en-têtes soient ou non inclus dans la demande.
Tous les autres en-têtes HTTP standard sont ignorés ou retournent une erreur si la fonctionnalité n’est pas prise en charge.

Authorization

L’en-tête d’autorisation est utilisé pour indiquer les informations d’identification de la partie appelante, à la suite de la méthode d’autorisation OAuth 2.0 pour les jetons de transmission.

La syntaxe se compose d’un littéral de chaîne « transmission », suivi par un espace, puis par votre jeton d’accès. Ce jeton d’accès est récupéré en émettant la demande de jeton d’accès décrite ci-avant. Le même jeton d’accès peut être utilisé sur les demandes de notification suivantes jusqu’à son expiration.

Cet en-tête est obligatoire.

Authorization: Bearer <access-token>

X-WNS-Type

Il s’agit des types de notifications pris en charge par WNS. Cet en-tête indique le type de notification et la façon dont WNS doit le gérer. Une fois que la notification a atteint le client, la charge utile réelle est validée par rapport au type spécifié. Cet en-tête est obligatoire.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw

Valeur	Description
wns/badge	Notification pour créer une superposition de badges sur la vignette. L’en-tête Content-Type inclus à la demande de notification doit être défini sur « text/xml ».
wns/tile	Notification pour mettre à jour le contenu de la vignette. L’en-tête Content-Type inclus à la demande de notification doit être défini sur « text/xml ».
wns/toast	Notification pour déclencher un toast sur le client. L’en-tête Content-Type inclus à la demande de notification doit être défini sur « text/xml ».
wns/raw	Notification pouvant contenir une charge utile personnalisée et envoyée directement sur l’application. L’en-tête Content-Type inclus à la demande de notification doit être défini sur « application/octet-stream».

X-WNS-Cache-Policy

Lorsque le périphérique cible de notification est hors ligne, WNS met en cache une notification de badge et une notification par vignette par application. Si une boucle de notification est activée pour l’application, WNS met en cache au maximum cinq notifications par vignette. Par défaut, les notifications brutes ne sont pas mises en cache. Cependant, si la mise en cache des notifications brutes est activée, une notification brute est mise en cache. Les éléments ne sont pas conservés dans le cache indéfiniment et seront supprimés à l’issue d’une période raisonnable. Sinon, le contenu mis en cache est remis lors de la mise en ligne suivante du périphérique.

Cet en-tête est facultatif. Il ne doit être utilisé que dans les cas où le service cloud souhaite remplacer le comportement de mise en cache par défaut.

X-WNS-Cache-Policy: cache | no-cache

Valeur	Description
cache	Par défaut. Les notifications sont mises en cache si l’utilisateur est hors connexion. Il s’agit du paramètre par défaut des notifications par vignette et par badge.
no-cache	La notification n’est pas mise en cache si l’utilisateur est hors connexion. Il s’agit du paramètre par défaut des notifications brutes.

X-WNS-RequestForStatus

Indique si la réponse doit inclure l’état du périphérique et de la connexion WNS. Cet en-tête est facultatif.

X-WNS-RequestForStatus: true | false

Valeur	Description
true	Retourne l’état du périphérique et l’état de la notification dans la réponse.
false	Par défaut. Ne retourne ni l’état du périphérique ni l’état de la notification.

X-WNS-Tag

Affecte une étiquette tag à une notification. Cette balise est utilisée dans la stratégie de remplacement de la vignette dans la file d’attente de notifications lorsque l’application a opté pour la boucle de notifications. S’il existe déjà une notification avec cette balise dans la file d’attente, une nouvelle notification avec la même balise la remplace.

Remarque Cet en-tête est facultatif et n’est utilisé que lors de l’envoi de notifications par vignette.

Remarque Dans les applications du Windows Phone Store, l’en-tête X-WNS-Tag peut être utilisé avec l’en-tête X-WNS-Group pour autoriser l’affichage de plusieurs notifications avec la même balise dans le Centre de maintenance.

X-WNS-Tag: <string value>

Valeur	Description
valeur de chaîne	Chaîne alphanumérique composée au plus de 16 caractères.

X-WNS-TTL

Spécifie la durée de vie (délai d’expiration) d’une notification. Il n’est généralement pas nécessaire, mais peut être utilisé pour veiller à ce que les notifications ne s’affichent pas au-delà d’un certain temps. La durée de vie est indiquée en secondes et par rapport au moment où WNS reçoit la demande. Si une durée de vie est spécifiée, le périphérique n’affiche pas la notification après ce délai. Notez que si la durée de vie est trop courte, il est possible que la notification ne s’affiche jamais. En général, une durée d’expiration est au moins mesurée en minutes.

Cet en-tête est facultatif. Si aucune valeur n’est spécifiée, la notification n’expire pas et elle est remplacée conformément au schéma normal de remplacement des notifications.

X-WNS-TTL: <integer value>

Valeur	Description
valeur entière	Durée de vie de la notification, en secondes, après que WNS a reçu la demande.

X-WNS-SuppressPopup

Remarque Dans les applications Windows Phone, vous pouvez supprimer l’interface utilisateur d’une notification toast et envoyer la notification directement au Centre de maintenance. Votre notification est alors remise sans avertissement. Cette option peut être une bonne alternative pour les notifications moins urgentes. Cet en-tête est facultatif ; il est utilisé uniquement sur les canaux Windows Phone. Si vous incluez cet en-tête sur un canal Windows, votre notification sera supprimée et vous recevrez une réponse indiquant une erreur de la part de WNS.

X-WNS-SuppressPopup: true | false

Valeur	Description
true	Envoyer la notification toast directement au centre de maintenance ; ne pas déclencher l’interface utilisateur toast.
false	Par défaut. Déclencher l’interface utilisateur toast et ajouter la notification au centre de maintenance.

X-WNS-Group

Remarque Le Centre de maintenance des applications du Windows Phone Store peut afficher plusieurs notifications toast ayant la même balise uniquement si elles sont identifiées comme appartenant à des groupes différents. Prenons l’exemple d’une application de livre de cuisine. Chaque recette est identifiée par une balise. Un toast qui contient un commentaire sur une recette particulière portera la balise de cette recette, mais une étiquette de groupe commentaire. Un toast qui contient une notation pour cette même recette portera également la balise de cette recette, mais une étiquette de groupe notation. Ces étiquettes de groupe différentes permettront aux deux notifications toast d’être affichées en même temps dans le Centre de maintenance. Cet en-tête est facultatif.

X-WNS-Group: <string value>

Valeur	Description
valeur de chaîne	Chaîne alphanumérique composée au plus de 16 caractères.

X-WNS-Match

Remarque Utilisé avec la méthode HTTP DELETE pour supprimer un toast spécifique, un ensemble de toasts (par balise ou par groupe) ou tous les toasts du Centre de maintenance des applications du Windows Phone Store. Cet en-tête peut spécifier un groupe, une balise ou les deux. Cet en-tête est obligatoire dans une demande de notification HTTP DELETE. Toute charge utile incluse avec cette demande de notification est ignorée.

X-WNS-Match: type:wns/toast;group=<string value>;tag=<string value> | type:wns/toast;group=<string value> | type:wns/toast;tag=<string value> | type:wns/toast;all

Valeur	Description
type:wns/toast;group=<valeur de chaîne>;tag=<valeur de chaîne>	Supprime une notification unique portant la balise ou l’étiquette de groupe spécifiées.
type:wns/toast;group=<Valeur de chaîne>	Supprime toutes les notifications portant l’étiquette de groupe spécifiée.
type:wns/toast;tag=<valeur de chaîne>	Supprime toutes les notifications portant la balise spécifiée.
type:wns/toast;all	Efface toutes les notifications de votre application du centre de maintenance.

Envoyer une réponse de notification

Après que WNS a traité la demande de notification, il envoie un message HTTP en réponse. Cette section traite des paramètres et des en-têtes pouvant se trouver dans cette réponse.

Paramètres de réponse

Nom d’en-tête	Obligatoire/Facultatif	Description
X-WNS-Debug-Trace	Facultatif	Informations de débogage qui doivent être consignées pour la résolution des problèmes lorsqu’un problème est signalé.
X-WNS-DeviceConnectionStatus	Facultatif	État du périphérique, retourné uniquement s’il est demandé dans la demande de notification via l’en-tête X-WNS-RequestForStatus.
X-WNS-Error-Description	Facultatif	Chaîne d’erreur contrôlable de visu, qui doit être consignée pour aider au débogage.
X-WNS-Msg-ID	Facultatif	Identificateur unique de la notification, utilisé à des fins de débogage. Lorsqu’un problème est détecté, cette information doit être consignée pour aider à la résolution de problèmes.
X-WNS-Status	Facultatif	Indique si WNS a reçu et traité la notification. Lorsqu’un problème est détecté, cette information doit être consignée pour aider à la résolution de problèmes.

X-WNS-Debug-Trace

Cet en-tête retourne des informations de débogage utiles sous forme de chaîne. Il est recommandé de consigner cet en-tête pour aider les développeurs à déboguer les problèmes. Cet en-tête, ainsi que l’en-tête X-WNS-Msg-ID, est obligatoire lors du signalement d’un problème à WNS.

X-WNS-Debug-Trace: <string value>

Valeur	Description
valeur de chaîne	Chaîne alphanumérique.

X-WNS-DeviceConnectionStatus

Cet en-tête retourne l’état du périphérique à l’application appelante, s’il est demandé dans l’en-tête X-WNS-RequestForStatus de la demande de notification.

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

Valeur	Description
connected	Le périphérique est en ligne et connecté à WNS.
disconnected	Le périphérique est hors ligne et n’est pas connecté à WNS.
tempconnected	Le périphérique a temporairement perdu la connexion à WNS, par exemple lorsqu’une connexion 3G est supprimée ou le commutateur sans fil d’un portable est levé. La plateforme du client de notification perçoit cela comme une interruption temporaire et non pas comme une déconnexion intentionnelle.

X-WNS-Error-Description

Cet en-tête fournit une chaîne d’erreur contrôlable de visu, qui doit être consignée pour aider au débogage.

X-WNS-Error-Description: <string value>

Valeur	Description
valeur de chaîne	Chaîne alphanumérique.

X-WNS-Msg-ID

Cet en-tête permet de fournir à l’appelant un identificateur de la notification. Il est recommandé de consigner cet en-tête pour aider au débogage. Cet en-tête, ainsi que l’en-tête X-WNS-Debug-Trace, est obligatoire lors du signalement d’un problème à WNS.

X-WNS-Msg-ID: <string value>

Valeur	Description
valeur de chaîne	Chaîne alphanumérique composée au plus de 16 caractères.

X-WNS-Status

Cet en-tête décrit comment WNS gère la demande de notification. Il peut être utilisé au lieu d’interpréter des codes de réponse en tant que succès ou échec.

X-WNS-Status: received | dropped | channelthrottled

Valeur	Description
received	La notification a été reçue et traitée par WNS. Remarque Cela ne garantit pas que le périphérique a reçu la notification.
dropped	La notification a été supprimée explicitement en raison d’une erreur ou car le client a rejeté explicitement ces notifications. Les notifications toast seront aussi supprimées si le périphérique est hors connexion.
channelthrottled	La notification a été supprimée, car le serveur d’applications a atteint la limitation du débit pour ce canal spécifique.

Codes de réponse

Chaque message HTTP contient un de ces codes de réponse. WNS recommande que les développeurs consignent le code de réponse à utiliser lors du débogage. Lorsque les développeurs signalent un problème à WNS, ils doivent fournir des codes de réponse et des informations d’en-tête.

Code de réponse HTTP	Description	Action recommandée
200 OK	La notification a été acceptée par WNS.	Aucune action nécessaire.
400 Requête incorrecte	Un ou plusieurs en-têtes ne sont pas spécifiés correctement ou sont en conflit avec un autre en-tête.	Consigner les détails de votre demande. Inspecter votre demande et effectuer une comparaison avec cette documentation.
401 Non autorisé	Le service cloud n’a pas présenté un ticket d’authentification valide. Le ticket OAuth n’est peut-être pas valide.	Demander un jeton d’accès valide en authentifiant votre service cloud à l’aide de la demande de jeton d’accès.
403 Interdit	Le service cloud n’est pas autorisé à envoyer une notification à cet URI, même s’il est authentifié.	Le jeton d’accès fourni dans la demande ne correspond pas aux informations d’identification de l’application qui a demandé l’URI de canal. Vérifier que le nom de votre package dans le manifeste de votre application correspond aux informations d’identification du service cloud fournies à votre application dans le Tableau de bord.
404 Introuvable	L’URI de canal n’est pas valide ou n’est pas reconnu par WNS.	Consignez les détails de votre demande. N’envoyez pas d’autres notifications à ce canal ; les notifications envoyées à cette adresse échouent.
405 Méthode non autorisée	Méthode non valide (GET, CREATE) ; seules les méthodes POST (Windows ou Windows Phone) ou DELETE (Windows Phone uniquement) sont autorisées.	Consignez les détails de votre demande. Utilisez HTTP-POST.
406 Non acceptable	Le service cloud a atteint la valeur de limite.	Consignez les détails de votre demande. Réduisez la fréquence à laquelle vous envoyez des notifications.
410 Supprimé	Le canal a expiré.	Consignez les détails de votre demande. N’envoyez pas d’autres notifications à ce canal. Votre application doit demander un nouvel URI de canal.
413 Entité de demande trop grande	La charge utile de notification a atteint la taille limite de 5 000 octets.	Consignez les détails de votre demande. Inspectez la charge utile pour vérifier qu’elle se trouve dans les limitations de taille.
500 Erreur de serveur interne	Une erreur interne a entraîné l’échec de la remise de la notification.	Consigner les détails de votre demande. Signalez ce problème dans les forums de développeurs.
503 Service non disponible	Le serveur n’est pas disponible actuellement.	Consignez les détails de votre demande. Signalez ce problème dans les forums de développeurs.

Pour obtenir des informations de dépannage détaillées concernant des codes de réponse spécifiques, voir Résolution des problèmes de notification pour les vignettes, les toasts et les badges. Voir aussi COM Error Codes (WPN, MBN, P2P, Bluetooth).

Fonctionnalités HTTP non prises en charge

L’interface Web WNS prend en charge HTTP 1.1, mais ne prend pas en charge les fonctionnalités suivantes :

Segmentation
Pipelining (POST n’est pas idempotent)
Bien que l’en-tête Expect-100 soit pris en charge, les développeurs doivent le désactiver, car il introduit une latence lors de l’envoi d’une notification.

Rubriques associées

Démarrage rapide : envoi d’une notification Push

Recommandations et liste de vérification sur les notifications Push

Comment s’authentifier auprès des services de notifications Push Windows (WNS)

Comment demander, créer et enregistrer un canal de notification

Exemple de notifications Push et périodiques

Vue d’ensemble des services WNS