Notes
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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.
Windows developer