Langage: HTML | XAML

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

Applies to Windows and Windows Phone

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ètreObligatoire/FacultatifDescription
grant_typeObligatoireDoit avoir la valeur « client_credentials ».
client_idObligatoireIdentificateur de sécurité du package (SID) pour votre service cloud, tel qu’il a été attribué lors de l’inscription de votre application auprès de Windows Store.
client_secretObligatoireClé secrète pour votre service cloud telle qu’elle a été attribuée lors de l’inscription de votre application auprès de Windows Store.
scopeObligatoireDoit 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ètreObligatoire/FacultatifDescription
access_tokenObligatoireJeton d’accès utilisé par le service cloud lorsqu’il envoie une notification.
token_typeFacultatifToujours retourné en tant que « transmission ».

 

Code de réponse

Code de réponse HTTPDescription
200 OKDemande 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

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êteObligatoire/FacultatifDescription
AuthorizationObligatoireEn-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-TypeObligatoireEn-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-LengthObligatoireEn-tête d’autorisation HTPP standard utilisé pour indiquer la taille de la charge utile de la demande.
X-WNS-TypeObligatoireDéfinit le type de notification dans la charge utile : vignette, toast, badge ou brute.
X-WNS-Cache-PolicyFacultatifActive 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-RequestForStatusFacultatifDemande l’état du périphérique et de la connexion WNS dans la réponse de notification.
X-WNS-TagFacultatifChaî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-TTLFacultatifValeur entière, exprimée en secondes, qui indique la durée de vie.
X-WNS-SuppressPopupFacultatifWindows Phone uniquement : remet une notification toast directement au centre de maintenance sans déclencher le toast lui-même.
X-WNS-GroupFacultatifWindows Phone uniquement : utilisé avec l’en-tête X-WNS-Tag pour regrouper les notifications dans le Centre de maintenance.
X-WNS-MatchObligatoire en fonction de la situationWindows 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
ValeurDescription
wns/badgeNotification 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/tileNotification 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/toastNotification 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/rawNotification 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
ValeurDescription
cachePar 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-cacheLa 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
ValeurDescription
trueRetourne l’état du périphérique et l’état de la notification dans la réponse.
falsePar 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.

  • Applies to Windows Phone

Sur Windows Phone, 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>
ValeurDescription
valeur de chaîneChaî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>
ValeurDescription
valeur entièreDurée de vie de la notification, en secondes, après que WNS a reçu la demande.

 

X-WNS-SuppressPopup

  • Applies to Windows Phone

Permet de supprimer l’interface utilisateur d’une notification toast et d’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 et 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 d’erreur de la part de WNS.

X-WNS-SuppressPopup: true | false
ValeurDescription
trueEnvoyer la notification toast directement au centre de maintenance ; ne pas déclencher l’interface utilisateur toast.
falsePar défaut. Déclencher l’interface utilisateur toast et ajouter la notification au centre de maintenance.

 

X-WNS-Group

  • Applies to Windows Phone

Le Centre de maintenance sur Windows Phone 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 la recette, mais un étiquette de groupe commentaire. Un toast qui contient une note pour cette même recette portera la balise de cette recette, mais un é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>
ValeurDescription
valeur de chaîneChaîne alphanumérique composée au plus de 16 caractères.

 

X-WNS-Match

  • Applies to Windows Phone

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 d’un Windows Phone. 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
ValeurDescription
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;allEfface 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êteObligatoire/FacultatifDescription
X-WNS-Debug-TraceFacultatifInformations de débogage qui doivent être consignées pour la résolution des problèmes lorsqu’un problème est signalé.
X-WNS-DeviceConnectionStatusFacultatifÉ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-DescriptionFacultatifChaîne d’erreur contrôlable de visu, qui doit être consignée pour aider au débogage.
X-WNS-Msg-IDFacultatifIdentificateur 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-StatusFacultatifIndique 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>
ValeurDescription
valeur de chaîneChaî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
ValeurDescription
connectedLe périphérique est en ligne et connecté à WNS.
disconnectedLe périphérique est hors ligne et n’est pas connecté à WNS.
tempconnectedLe 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>
ValeurDescription
valeur de chaîneChaîne alphanumérique.

 

X-WNS-Msg-ID

Il 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>
ValeurDescription
valeur de chaîneChaî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
ValeurDescription
receivedLa 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.

droppedLa 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.
channelthrottledLa 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 HTTPDescriptionAction recommandée
200 OKLa notification a été acceptée par WNS.Aucune action nécessaire.
400 Requête incorrecteUn 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 InterditLe 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 IntrouvableL’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éeMé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 acceptableLe 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 grandeLa 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 interneUne 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 disponibleLe 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

 

 

Afficher:
© 2014 Microsoft