Partager via

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

  • Article

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

Consultez la vue d’ensemble des services de notifications Push Windows (WNS) pour accéder à une discussion conceptuelle des notifications Push et découvrir les concepts, exigences et opérations liés à 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 dans l’authentification auprès du service WNS.

Demande de jeton d’accès.

Une demande 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 à https://login.live.com/accesstoken.srf à l’aide du protocole SSL (Secure Sockets Layer).

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

Le service cloud envoie ces paramètres requis dans le corps de la demande HTTP au format « application/x-www-form-urlencoded ». Vous devez vous assurer que tous les paramètres sont encodés dans l’URL.

Paramètre Obligatoire Description
grant_type VRAI Cette propriété doit être définie sur client_credentials.
client_id VRAI Identificateur de sécurité (SID) de package pour votre service cloud, attribué lorsque vous avez inscrit votre application auprès du Microsoft Store.
client_secret VRAI Clé secrète pour votre service cloud, attribuée lorsque vous avez inscrit votre application auprès du Microsoft Store.
scope 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, en cas de réussite, répond avec un code « 200 OK » comprenant 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 la réponse à une demande de jeton d’accès

Un jeton d’accès est retourné dans la réponse HTTP si le service cloud s’est 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 Description
access_token VRAI Jeton d’accès utilisé par le service cloud quand il envoie une notification.
token_type FAUX Toujours retourné en tant que bearer.

Response code

Code de réponse HTTP Description
200 OK La demande a abouti.
400 Requête 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 demande HTTP adressée à WNS pour remettre une notification et les en-têtes impliqués dans la réponse.

  • Envoyer une demande de notification
  • Envoyer une réponse à une demande 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 envoie une demande HTTP via SSL à l’URI (Uniform Resource Identifier) du canal. « Content-Length » est un en-tête HTTP standard qui doit être spécifié dans la demande. Tous les autres en-têtes standard sont facultatifs ou non pris en charge.

De plus, les en-têtes de demande personnalisés listé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 Requis Description
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 de type 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-contenu VRAI En-tête d’autorisation HTTP standard pour indiquer la taille de la charge utile de la demande.
X-WNS-Type VRAI Définit le type de notification dans la charge utile : vignette, toast, badge ou brute.
X-WNS-Cache-Policy FAUX Active ou désactive la mise en cache des notifications. Cet en-tête s’applique uniquement aux notifications brutes ou de type vignette ou badge.
X-WNS-RequestForStatus FAUX Demande l’état de l’appareil et l’état de la connexion WNS dans la réponse à la demande 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 de notifications. Cet en-tête s’applique uniquement aux notifications de type 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 Correlation Vector utilisée pour votre demande.

Remarques importantes

  • Content-Length et Content-Type sont les seuls en-têtes HTTP standard qui sont inclus dans la notification remise au client, que d’autres en-têtes standard aient été inclus ou non 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.
  • Depuis février 2023, WNS ne met en cache qu’une seule notification de type vignette lorsque l’appareil est hors connexion.

Autorisation

L’en-tête d’autorisation est utilisé pour spécifier les informations d’identification de la partie appelante, conformément à la méthode d’autorisation OAuth 2.0 pour les jetons bearer.

La syntaxe se compose d’un littéral de chaîne « Bearer », suivi d’un espace et 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 ultérieures 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 la notification et la façon dont WNS s’en charger. Quand la notification atteint le 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 Description
wns/badge Notification pour créer une superposition de badge sur la vignette. L’en-tête Content-Type inclus dans 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 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/raw 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

Quand l’appareil cible de la 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. Toutefois, si leur mise en cache est activée, une notification brute est mise en cache. Les éléments ne sont pas conservés indéfiniment dans le cache et sont supprimés après une période raisonnable. Sinon, le contenu mis en cache est remis la prochaine fois que l’appareil est mis en ligne.

X-WNS-Cache-Policy: cache | no-cache
Valeur Description
cache Par défaut. Les notifications sont mises en cache si l’utilisateur est hors ligne. Il s’agit du paramètre par défaut pour les notifications de type vignette et badge.
no-cache La notification n’est pas mise en cache si l’utilisateur est hors ligne. 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 le statut de connexion WNS. Cet en-tête est facultatif.

    X-WNS-RequestForStatus: true | false
Valeur Description
true Retourne l’état de l’appareil et le statut de connexion dans la réponse.
false Par défaut. Ne retourne pas l’état de l’appareil et le statut de connexion.

X-WNS-Tag

Affecte une étiquette tag à une notification. La balise est utilisée dans la stratégie de remplacement de la vignette dans la file d’attente de notification quand l’application a opté pour le cycle de notification. Si une notification avec cette balise existe déjà dans la file d’attente, une nouvelle notification avec la même balise prend sa place.

Remarque

Cet en-tête est facultatif et n’est utilisé qu’au moment de l’envoi de notifications de type vignette.

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

X-WNS-TTL

Spécifie la durée de vie (délai d’expiration) d’une notification. Cet élément n’est pas généralement requis, mais vous pouvez l’utiliser pour vous assurer que vos notifications ne sont pas affichées après un certain temps. La durée de vie est spécifiée en secondes et est relative à l’heure à laquelle WNS reçoit la demande. Quand une durée de vie est spécifiée, l’appareil n’affiche pas la notification après cette durée. Notez qu’une durée de vie trop courte peut empêcher tout affichage de la notification. En général, un délai d’expiration est mesuré au minimum en minutes.

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

X-WNS-TTL: <integer value>

Valeur Description
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 pouvez supprimer l’interface utilisateur d’une notification toast, envoyant ainsi la notification directement au centre de notifications. Cela permet de remettre votre notification en mode silencieux, une option potentiellement avantageuse 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 sera supprimée et vous recevrez une réponse d’erreur de la part de WNS.

X-WNS-SuppressPopup: true | false

Valeur Description
true Envoie la notification toast directement au centre de notifications ; ne déclenche pas l’interface utilisateur toast.
false Par défaut. Déclenche l’interface utilisateur toast et ajoute la notification au centre de notifications.

X-WNS-Group

Remarque

Le centre de notifications pour les applications du Windows Phone Store peut afficher plusieurs notifications toast avec la même balise uniquement si elles sont étiquetées comme appartenant à des groupes différents. Par exemple, prenons une application de recettes de cuisine. Chaque recette est identifiée par une balise. Un toast contenant un commentaire sur cette recette aurait la balise de la recette, mais une étiquette de groupe de commentaires. Un toast contenant une évaluation pour cette recette aurait à nouveau la balise de cette recette, mais une étiquette de groupe d’évaluation. Ces différentes étiquettes de groupe permettraient 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 Description
valeur chaîne Chaîne alphanumérique 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 par 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 obligatoire 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;all

Valeur Description
type:wns/toast;group=<string value>;tag=<string value> Supprime une notification unique étiquetée avec la balise et le groupe spécifiés.
type:wns/toast;group=<string value> Supprime toutes les notifications étiquetées avec le groupe spécifié.
type:wns/toast;tag=<string value> Supprime toutes les notifications étiquetées avec la balise spécifiée.
type:wns/toast;all Efface toutes les notifications de votre application du centre de notifications.

Envoyer une réponse à une demande de notification

Après avoir traité la demande de notification, WNS envoie un message HTTP en réponse. Cette section décrit les paramètres et les en-têtes qui se trouvent dans cette réponse.

Paramètres de réponse

Nom de l’en-tête Requis Description
X-WNS-Debug-Trace FAUX Informations de débogage à journaliser pour faciliter le dépannage lors du signalement d’un problème.
X-WNS-DeviceConnectionStatus FAUX État de l’appareil, uniquement retourné s’il est demandé dans la demande de notification via l’en-tête X-WNS-RequestForStatus.
X-WNS-Error-Description FAUX Chaîne d’erreur explicite 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ébogage. Lors du signalement d’un problème, il est recommandé de journaliser ces informations pour faciliter le dépannage.
X-WNS-Status FAUX Indique si WNS a correctement reçu et traité la notification. Lors du signalement d’un problème, il est recommandé de journaliser ces informations pour faciliter le dépannage.
MS-CV FAUX Informations de débogage à journaliser pour faciliter le dépannage 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 de journaliser cet en-tête pour aider les développeurs à déboguer les problèmes. Cet en-tête, ainsi que les en-têtes X-WNS-Msg-ID et MS-CV, sont requis lors du signalement d’un problème à WNS.

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

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

X-WNS-DeviceConnectionStatus

Cet en-tête retourne à l’application appelante l’état de l’appareil 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 L’appareil est en ligne et connecté à WNS.
déconnecté L’appareil est hors connexion et n’est pas connecté à WNS.
tempconnected (obsolète) L’appareil a temporairement perdu la connexion à WNS, ce qui peut arriver lorsqu’une connexion 3G est interrompue ou que le commutateur de connexion sans fil d’un ordinateur portable est désactivé. La plateforme cliente de notification considère ceci 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 explicite qui doit être journalisée pour faciliter le débogage.

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

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

X-WNS-Msg-ID

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

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

Valeur Description
valeur chaîne Chaîne alphanumérique 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. Vous pouvez utiliser cette information au lieu d’interpréter les codes de réponse comme une réussite ou un échec.

X-WNS-Status: received | dropped | channelthrottled

Valeur Description
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.
supprimé La notification a été explicitement supprimée en raison d’une erreur ou parce que le client a explicitement rejeté ces notifications. Les notifications toast sont également supprimées si l’appareil est hors connexion.
channelthrottled 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 (CV, Correlation Vector) lié à la requête qui est principalement utilisé pour le débogage. Si un CV est fourni dans le cadre de la demande, WNS utilise cette valeur. Sinon, WNS génère un CV et répond avec celui-ci. Cet en-tête, ainsi que les en-têtes 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 Description
valeur chaîne Respecte la norme Correlation Vector.

Codes de réponse

Chaque message HTTP contient l’un de ces codes de réponse. WNS recommande aux développeurs de journaliser le code de réponse en vue du débogage. Quand 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 requise.
400 Requête incorrecte Un ou plusieurs en-têtes ont été spécifiés de manière incorrecte ou sont en conflit avec un autre en-tête. Journalisez 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’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 du canal. Assurez-vous que le nom de votre package dans le manifeste de l’application correspond aux informations d’identification du service cloud fournies à votre application dans le tableau de bord.
404 Not Found L’URI de canal n’est pas valide ou n’est pas reconnu par WNS. Journalisez les détails de votre demande. N’envoyez pas d’autres notifications à ce canal ; les notifications à cette adresse échoueront.
405 Method Not Allowed Méthode non valide (GET, CREATE). Seule la méthode POST (Windows ou Windows Phone) ou DELETE (Windows Phone uniquement) est autorisée. Journalisez les détails de votre demande. Passez à HTTP POST.
406 Non acceptable 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 Supprimé Le canal a expiré. Journalisez les détails de votre demande. N’envoyez pas d’autres notifications à ce canal. Demandez à votre application de demander un nouvel URI de canal.
410 Domaine bloqué Le domaine d’envoi a été bloqué par WNS. N’envoyez pas d’autres notifications à ce canal. Le domaine d’envoi a été bloqué par WNS pour abus de notifications Push.
413 Entité de demande trop grande La charge utile de notification dépasse la limite de taille de 5 000 octets. Journalisez les détails de votre demande. Inspectez la charge utile pour vous assurer qu’elle ne dépasse pas les limites de taille.
500 Erreur interne du serveur Une défaillance interne a provoqué l’échec de la remise des notifications. Journalisez les détails de votre demande. Signalez ce problème par le biais des forums de développeurs.
503 Service indisponible Le serveur est actuellement indisponible. Journalisez les détails de votre demande. Signalez ce problème sur les forums de développeurs. Si vous observez l’en-tête Retry-After, 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 elle ne prend pas en charge les fonctionnalités suivantes :

  • Segmentation
  • Pipelining (POST n’est pas idempotent)
  • Les développeurs doivent désactiver Expect-100, bien qu’il soit pris en charge, en raison de la latence introduite lors de l’envoi d’une notification.