Partager via

En-têtes de demande et de réponse du service de notification Push (applications Windows Runtime)

Cette rubrique décrit les API et protocoles web de service à service requis pour envoyer une notification Push.

Consultez la vue d’ensemble de Windows Push Notification Services (WNS) pour une discussion conceptuelle sur les concepts, exigences et fonctionnement des notifications Push et des WNS.

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

Cette section décrit les paramètres de demande et de réponse impliqués lorsque vous vous authentifiez auprès du service WNS.

Demande de jeton d’accès

Une requête HTTP est envoyée à WNS pour authentifier le service cloud et récupérer un jeton d’accès en retour. La demande est émise à l’aide https://login.live.com/accesstoken.srf du protocole SSL (Secure Sockets Layer).

Paramètres de demande de jeton d’accès

Le service cloud soumet ces paramètres requis dans le corps de la requête HTTP, à l’aide du format « application/x-www-form-urlencoded ». Vous devez vous assurer que tous les paramètres sont encodés par URL.

Paramètre Obligatoire Descriptif
type d'autorisation VRAI Cette propriété doit être définie sur client_credentials.
client_id VRAI Identificateur de sécurité de package (SID) pour votre service cloud tel qu’il est affecté lorsque vous avez inscrit votre application auprès du Microsoft Store.
secret du client VRAI Clé secrète pour votre service cloud comme attribué lorsque vous avez inscrit votre application auprès du Microsoft Store.
portée VRAI Il doit être défini sur notify.windows.com

Réponse à une demande de jeton d’accès

WNS authentifie le service cloud et, si elle réussit, répond avec un « 200 OK », y compris le jeton d’accès. Sinon, WNS répond avec un code d’erreur HTTP approprié, comme décrit dans le brouillon du protocole OAuth 2.0.

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

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

Paramètre Obligatoire Descriptif
jeton d'accès VRAI Jeton d’accès que le service cloud utilisera lorsqu’il envoie une notification.
type_de_jeton FAUX Toujours retourné en tant que bearer.

Code de réponse

Code de réponse HTTP Descriptif
200 OK La demande a été réalisée avec succès.
400 Demande incorrecte L’authentification a échoué. Consultez le document RFC (Request For Comments) du brouillon OAuth pour connaître les paramètres de réponse.

Exemple :

Voici un exemple de 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",
     "expires_in": 86400
 }

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 à WNS pour remettre une notification et celles impliquées 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 effectue 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 standard sont facultatifs ou non 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, tandis que d’autres sont facultatifs.

Paramètres de la demande

Nom de l’en-tête Obligatoire Descriptif
Autorisation VRAI 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.
Type de contenu VRAI En-tête d’autorisation HTTP standard. Pour les notifications toast, vignette et 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.
Longueur du contenu VRAI En-tête d’autorisation HTTP standard pour indiquer la taille de la charge utile de la requête.
X-WNS-Type VRAI Définit le type de notification dans le contenu : vignette, toast, badge ou brut.
X-WNS -Cache-Policy FAUX Active ou désactive la mise en cache des notifications. Cet en-tête s’applique uniquement aux notifications de vignette, de badge et non traitées.
X-WNS-RequestForStatus FAUX Demande l’état de l’appareil et l’état de connexion WNS dans la réponse de notification.
X-WNS-Tag FAUX Chaîne utilisée pour fournir une notification avec une étiquette d’identification, utilisée pour les vignettes qui prennent en charge la file d’attente des notifications. Cet en-tête s’applique uniquement aux notifications de vignette.
X-WNS-TTL FAUX Valeur entière, exprimée en secondes, qui spécifie la durée de vie (TTL).
MS-CV FAUX valeur du vecteur de corrélation utilisée pour votre requête.

Remarques importantes

  • Content-Length et Content-Type sont les seuls en-têtes HTTP standard inclus dans la notification remise au client, que d’autres en-têtes standard aient été inclus dans la requête.
  • Tous les autres en-têtes HTTP standard sont ignorés ou retournent une erreur si la fonctionnalité n’est pas prise en charge.
  • À compter de février 2023, WNS met en cache une seule notification de vignette lorsque l’appareil est hors connexion.

Autorisation

L’en-tête d’autorisation permet de spécifier les informations d’identification de la partie appelante, en suivant la méthode d’autorisation OAuth 2.0 pour jetons porteurs.

La syntaxe consiste en un littéral de chaîne "Bearer", suivi d'un espace, puis de 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-dessus. 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 notification 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 la notification atteinte au client, la charge utile réelle est validée par rapport à ce type spécifié. Cet en-tête est obligatoire.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
Valeur Descriptif
wns/insigne Notification pour créer une superposition de badges sur la vignette. L’en-tête Content-Type inclus dans la demande de notification doit être défini sur text/xml.
WNS/tuile Notification pour mettre à jour le contenu de la vignette. L’en-tête Content-Type inclus dans 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 dans la demande de notification doit être défini sur text/xml.
wns/brut Notification qui peut contenir une charge utile personnalisée et qui est remise directement à l’application. L’en-tête Content-Type inclus dans la demande de notification doit être défini sur application/octet-stream.

X-WNS -Cache-Policy

Lorsque l’appareil cible de notification est hors connexion, WNS met en cache un badge, une vignette et une notification toast pour chaque URI de canal. Par défaut, les notifications brutes ne sont pas mises en cache, mais 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 indéfiniment dans le cache et seront supprimés après une période raisonnable. Sinon, le contenu mis en cache est remis lors de la prochaine mise en ligne de l’appareil.

X-WNS-Cache-Policy: cache | no-cache
Valeur Descriptif
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 pour les notifications de vignette et de badge.
pas de cache La notification ne sera pas mise en cache si l’utilisateur est hors connexion. Il s’agit du paramètre par défaut pour les notifications brutes.

X-WNS-RequestForStatus

Spécifie si la réponse doit inclure l’état de l’appareil et l’état de connexion WNS. Cet en-tête est facultatif.

    X-WNS-RequestForStatus: true | false
Valeur Descriptif
vrai Renvoyez l’état de l’appareil et l’état des notifications dans la réponse.
faux Par défaut. Ne renvoyez pas l’état de l’appareil et l’état de notification.

X-WNS-Tag

Affecte un tag à une notification. Le tag est utilisé dans la stratégie de remplacement de la vignette dans la file d'attente de notifications lorsque l'application a opté pour la rotation des notifications. Si une notification avec cette balise existe déjà dans la file d’attente, une nouvelle notification avec la même balise a lieu.

Remarque

Cet en-tête est facultatif et utilisé uniquement lors de l’envoi de notifications de vignette.

    X-WNS-Tag: <string value>
Valeur Descriptif
valeur de chaîne Chaîne alphanumérique de ne dépassant pas 16 caractères.

X-WNS-TTL

Spécifie la durée de vie (heure d’expiration) d’une notification. Cela n’est généralement pas nécessaire, mais peut être utilisé si vous souhaitez vous assurer que vos notifications ne sont pas affichées ultérieurement à un certain temps. La durée de vie est spécifiée en secondes et est relative à l’heure à laquelle WNS reçoit la requête. Lorsqu'un TTL est spécifié, l'appareil n'affiche plus la notification après l'expiration de ce délai. Notez que cela peut entraîner que la notification ne soit jamais affichée si la durée de vie est trop courte. En général, un délai d’expiration est mesuré en au moins minutes.

Cet en-tête est facultatif. Si aucune valeur n’est spécifiée, la notification n’expire pas et sera remplacée sous le schéma de remplacement de notification normal.

X-WNS-TTL : <integer value>

Valeur Descriptif
valeur entière Durée de vie de la notification, en secondes, après réception de la demande par WNS.

X-WNS-SuppressPopup

Remarque

Pour les applications du Windows Phone Store, vous avez la possibilité de masquer l’interface utilisateur d'une notification toast pour envoyer la notification directement au centre de notifications. Cela permet à votre notification d’être remise en mode silencieux, une option potentiellement supérieure pour les notifications moins urgentes. Cet en-tête est facultatif et utilisé uniquement sur les canaux Windows Phone. Si vous incluez cet en-tête sur un canal Windows, votre notification est supprimée et vous recevrez une réponse d’erreur de WNS.

X-WNS-SuppressPopup : true | false

Valeur Descriptif
vrai Envoyez la notification toast directement au centre de notifications ; ne déclenchez pas l’interface utilisateur toast.
faux Par défaut. Afficher l'interface utilisateur du toast et ajouter la notification au centre de notifications.

X-WNS-Group

Remarque

Le centre d'action pour les applications Windows Phone Store peut afficher plusieurs notifications toast avec la même balise uniquement si elles sont étiquetées comme appartenant à différents groupes. Par exemple, considérez une application de livre de recettes. Chaque recette serait identifiée par une balise. Un toast qui contient un commentaire sur cette recette aurait la balise de la recette, mais une étiquette de groupe de commentaires. Une notification qui contient une évaluation pour cette recette aurait de nouveau l'étiquette de cette recette, mais porterait aussi une étiquette de groupe d’évaluation. Ces différentes étiquettes de groupe permettent aux deux notifications toast d’être affichées simultanément dans le centre de notifications. Cet en-tête est facultatif.

X-WNS-Group : <string value>

Valeur Descriptif
valeur de chaîne Chaîne alphanumérique de ne dépassant pas 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 groupe) ou tous les toasts du centre de notifications pour les applications du Windows Phone Store. Cet en-tête peut spécifier un groupe, une balise ou les deux. Cet en-tête est requis dans une demande de notification HTTP DELETE. Toute charge utile incluse dans 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 ; tout

Valeur Descriptif
type :wns/toast ; group=<string value>; tag=<string value> Supprimez une notification unique étiquetée avec la balise et le groupe spécifiés.
type :wns/toast ; group=<string value> Supprimez toutes les notifications étiquetées avec le groupe spécifié.
type : wns/toast ; tag =<string value> Supprimez toutes les notifications étiquetées avec la balise spécifiée.
type :wns/toast ; tout Effacez toutes les notifications de votre application à partir du centre de notifications.

Envoyer une réponse de notification

Une fois que WNS traite la demande de notification, il envoie un message HTTP en réponse. Cette section décrit les paramètres et les en-têtes qui peuvent être trouvés dans cette réponse.

Paramètres de réponse

Nom de l’en-tête Obligatoire Descriptif
X-WNS -Debug-Trace FAUX Informations de débogage qui doivent être enregistrées pour vous aider à résoudre les problèmes lors du signalement d’un problème.
X-WNS-DeviceConnectionStatus FAUX L’état de l’appareil ne sera retourné que s’il est demandé dans la requête de notification via l’en-tête X-WNS-RequestForStatus.
X-WNS -Error-Description FAUX Chaîne d’erreur lisible par l’homme qui doit être journalisée pour faciliter le débogage.
X-WNS -Msg-ID FAUX Identificateur unique de la notification, utilisé à des fins de dépannage. Lorsque vous signalez un problème, ces informations doivent être enregistrées pour faciliter la résolution des problèmes.
X-WNS-Status FAUX Indique si WNS a correctement reçu et traité la notification. Lorsque vous signalez un problème, ces informations doivent être enregistrées pour faciliter la résolution des problèmes.
MS-CV FAUX Informations de débogage qui doivent être enregistrées pour vous aider à résoudre les problèmes lors du signalement d’un problème.

X-WNS -Debug-Trace

Cet en-tête retourne des informations de débogage utiles sous forme de chaîne. Nous vous recommandons d'enregistrer 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 et MS-CV, sont requis lors du signalement d’un problème à WNS.

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

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

X-WNS-DeviceConnectionStatus

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

X-WNS-DeviceConnectionStatus : connecté | déconnecté | temporairement déconnecté

Valeur Descriptif
relié L’appareil est en ligne et connecté à WNS.
déconnecté L’appareil est hors connexion et n’est pas connecté à WNS.
tempconnected (déconseillé) L’appareil a temporairement perdu la connexion à WNS, par exemple lorsqu’une connexion 3G est coupée ou que le commutateur sans fil d’un ordinateur portable est désactivé. Elle est considérée par la plateforme cliente de notification comme une interruption temporaire plutôt qu’une déconnexion intentionnelle.

X-WNS -Error-Description

Cet en-tête fournit une chaîne d’erreur lisible par l’homme qui doit être journalisée pour faciliter le débogage.

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

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

X-WNS -Msg-ID

Cet en-tête est utilisé pour fournir à l’appelant un identificateur pour la notification. Nous vous recommandons de journaliser cet en-tête pour aider à résoudre les problèmes de débogage. Cet en-tête, ainsi que le X-WNS-Debug-Trace et le MS-CV, est requis lors du signalement d’un problème auprès de WNS.

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

Valeur Descriptif
valeur de chaîne Chaîne alphanumérique de ne dépassant pas 16 caractères.

X-WNS-Status

Cet en-tête décrit comment WNS a géré la demande de notification. Cela peut être utilisé plutôt que d’interpréter les codes de réponse comme réussite ou échec.

X-WNS-Status : reçu | supprimé | channelthrottled

Valeur Descriptif
reçu La notification a été reçue et traitée par WNS. Remarque : cela ne garantit pas que l’appareil a reçu la notification.
tombé La notification a été supprimée explicitement en raison d’une erreur ou parce que le client a rejeté explicitement ces notifications. Les notifications toast sont également supprimées si l’appareil est hors connexion.
canal limité La notification a été supprimée, car le serveur d’applications a dépassé la limite de débit pour ce canal spécifique.

MS-CV

Cet en-tête fournit un vecteur de corrélation lié à la requête qui est principalement utilisée pour le débogage. Si un CV est fourni dans le cadre de la demande, WNS utilise cette valeur, sinon WNS génère et répond avec un CV. Cet en-tête, ainsi que l’en-tête X-WNS-Debug-Trace et X-WNS-Msg-ID, sont requis lors du signalement d’un problème à WNS.

Important

Générez un nouveau CV pour chaque demande de notification Push si vous fournissez votre propre CV.

MS-CV : <string value>

Valeur Descriptif
valeur de chaîne Suit le standard de vecteur de corrélation

Codes de réponse

Chaque message HTTP contient l’un de ces codes de réponse. WNS recommande aux développeurs de consigner le code de réponse à utiliser dans le 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 Descriptif Action recommandée
200 OK La notification a été acceptée par WNS. Aucune n'est requise.
400 Demande incorrecte Un ou plusieurs en-têtes ont été spécifiés de manière incorrecte ou en conflit avec un autre en-tête. Consignez les détails de votre demande. Inspectez votre demande et comparez-la à cette documentation.
401 Non autorisé Le service cloud n’a pas présent de ticket d’authentification valide. Le ticket OAuth peut ne pas être valide. Demandez 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’ils sont authentifiés. Le jeton d’accès fourni dans la demande ne correspond pas aux informations d’identification de l’application qui a demandé l’URI du canal. Vérifiez 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 du canal n’est pas valide ou n’est pas reconnu par WNS. Consignez les détails de votre demande. N’envoyez pas de notifications supplémentaires à ce canal ; les notifications adressées à cette adresse échouent.
405 Méthode non autorisée Méthode non valide (GET, CREATE) ; seul POST (Windows ou Windows Phone) ou DELETE (Windows Phone uniquement) est autorisé. Consignez les détails de votre demande. Basculez vers l’utilisation de HTTP POST.
406 Inacceptable Le service cloud a dépassé sa limite de limitation. Envoyez votre demande après la valeur d’en-tête Retry-After dans la réponse
410 Disparu Le canal a expiré. Consignez les détails de votre demande. N’envoyez pas de notifications supplémentaires à ce canal. Demandez à votre application un nouvel URI de canal.
410 Domaine bloqué Le domaine d’envoi a été bloqué par WNS. N’envoyez pas de notifications supplémentaires à ce canal. Le domaine d’envoi a été bloqué par WNS pour abus de notifications Push.
413 Entité de requête trop volumineuse La charge utile de notification dépasse la limite de taille de 5 000 octets. Consignez les détails de votre demande. Inspectez la charge utile pour vous assurer qu’elle se trouve dans les limites de taille.
500 Erreur interne du serveur Une défaillance interne a provoqué l’échec de la remise des notifications. Consignez les détails de votre demande. Signalez ce problème via les forums des développeurs.
503 Service indisponible Le serveur n’est actuellement pas disponible. Consignez les détails de votre demande. Signalez ce problème via les forums des développeurs. Si l’en-tête Retry-After est observé, envoyez votre demande après la valeur d’en-tête Retry-After dans la réponse.

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 :

  • Chunking
  • Pipelining (POST n’est pas idempotent)
  • Bien que pris en charge, les développeurs doivent désactiver Expect-100 car cela introduit la latence lors de l’envoi d’une notification.