Condividi tramite

Intestazioni di richiesta e risposta del servizio di notifica push (app di Windows Runtime)

Questo argomento descrive le API Web da servizio a servizio e i protocolli necessari per inviare una notifica push.

Per una discussione concettuale sui concetti, requisiti e funzionamento delle notifiche push e di Windows Push Notification Services (WNS), vedere la panoramica .

Richiesta e ricezione di un token di accesso

Questa sezione descrive i parametri di richiesta e risposta coinvolti quando si esegue l'autenticazione con WNS.

Richiesta di token di accesso

Una richiesta HTTP viene inviata a WNS per autenticare il servizio cloud e recuperare un token di accesso in cambio. La richiesta viene effettuata tramite Secure Sockets Layer (SSL) a https://login.live.com/accesstoken.srf.

Parametri della richiesta del token di accesso

Il servizio cloud invia questi parametri obbligatori nel corpo della richiesta HTTP, usando il formato "application/x-www-form-urlencoded". È necessario assicurarsi che tutti i parametri siano codificati in URL.

Parametro Obbligatorio Descrizione
tipo_di_concessione Vero Deve essere impostato su client_credentials.
ID cliente Vero ID di sicurezza del pacchetto (SID) per il servizio cloud assegnato al momento della registrazione dell'app in Microsoft Store.
segreto_cliente Vero Chiave privata per il servizio cloud assegnato al momento della registrazione dell'app in Microsoft Store.
scopo Vero Deve essere impostato su notify.windows.com

Risposta del token di accesso

WNS autentica il servizio cloud e, se ha esito positivo, risponde con "200 OK", incluso il token di accesso. In caso contrario, WNS risponde con un codice di errore HTTP appropriato, come descritto nella bozza di protocollo OAuth 2.0.

Parametri di risposta del token di accesso

Se il servizio cloud è stato autenticato correttamente, viene restituito un token di accesso nella risposta HTTP. Questo token di accesso può essere usato nelle richieste di notifica fino alla scadenza. La risposta HTTP usa il tipo di media "application/json".

Parametro Obbligatorio Descrizione
token di accesso Vero Token di accesso che il servizio cloud userà quando invia una notifica.
tipo di token Falso Restituito sempre come il numero bearer.

Codice della risposta

Codice di risposta HTTP Descrizione
200 Va bene La richiesta è riuscita.
400 Richiesta non valida Autenticazione non riuscita. Per i parametri di risposta, vedere la bozza di richiesta OAuth per i commenti (RFC).

Esempio

Di seguito è riportato un esempio di risposta di autenticazione riuscita:

 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
 }

Invio di una richiesta di notifica e ricezione di una risposta

Questa sezione descrive le intestazioni coinvolte in una richiesta HTTP a WNS per inviare una notifica e quelle coinvolte nella risposta.

  • Inviare una richiesta di notifica
  • Inviare una risposta di notifica
  • Funzionalità HTTP non supportate

Inviare una richiesta di notifica

Quando si invia una richiesta di notifica, l'app chiamante effettua una richiesta HTTP tramite SSL, indirizzata all'URI (Uniform Resource Identifier) del canale. "Content-Length" è un'intestazione HTTP standard che deve essere specificata nella richiesta. Tutte le altre intestazioni standard sono facoltative oppure non sono supportate.

Inoltre, le intestazioni di richiesta personalizzate elencate qui si possono utilizzare nella richiesta di notifica. Alcune intestazioni sono obbligatorie, mentre altre sono facoltative.

Parametri della richiesta

Nome dell'intestazione Obbligatorio Descrizione
Autorizzazione Vero Intestazione di autorizzazione HTTP standard usata per autenticare la richiesta di notifica. Il servizio cloud fornisce il token di accesso in questa intestazione.
Tipo di Contenuto Vero Intestazione di autorizzazione HTTP standard. Per le notifiche di tipo toast, riquadro e badge, questa intestazione deve essere impostata su text/xml. Per le notifiche non elaborate, questa intestazione deve essere impostata su application/octet-stream.
La lunghezza del contenuto Vero Intestazione di autorizzazione HTTP standard per indicare le dimensioni del payload della richiesta.
X-WNS-Type Vero Definisce il tipo di notifica nel payload: riquadro, avviso popup, badge o non elaborato.
X-WNS-Cache-Policy Falso Abilita o disabilita la memorizzazione nella cache delle notifiche. Questa intestazione si applica solo a tile, badge e notifiche raw.
X-WNS-RequestForStatus Falso Richiede lo stato del dispositivo e lo stato della connessione WNS nella risposta di notifica.
X-WNS-Tag Falso Stringa usata per fornire una notifica con un'etichetta di identificazione, usata per i riquadri che supportano la coda di notifica. Questa intestazione si applica solo alle notifiche dei riquadri.
X-WNS-TTL Falso Valore intero, espresso in secondi, che specifica il tempo di vita (TTL).
MS-CV Falso Valore del vettore di correlazione usato per la richiesta.

Note importanti

  • Content-Length e Content-Type sono le uniche intestazioni HTTP standard incluse nella notifica recapitata al client, indipendentemente dal fatto che nella richiesta siano state incluse altre intestazioni standard.
  • Tutte le altre intestazioni HTTP standard vengono ignorate o restituiscono un errore se la funzionalità non è supportata.
  • A partire da febbraio 2023, WNS memorizza nella cache una sola notifica di riquadro quando il dispositivo è offline.

Autorizzazione

L'intestazione di autorizzazione viene utilizzata per specificare le credenziali dell'entità chiamante, seguendo il metodo di autorizzazione OAuth 2.0 per i token bearer.

La sintassi è costituita da una stringa letterale "Bearer", seguita da uno spazio, seguito dal tuo token di accesso. Questo token di accesso viene recuperato eseguendo la richiesta di token di accesso descritta in precedenza. Lo stesso token di accesso può essere usato nelle richieste di notifica successive fino alla scadenza.

Questa intestazione è obbligatoria.

Authorization: Bearer <access-token>

X-WNS-Type

Questi sono i tipi di notifica supportati da WNS. Questa intestazione indica il tipo di notifica e il modo in cui WNS deve gestirla. Dopo che la notifica raggiunge il client, il payload effettivo viene convalidato in riferimento al tipo specificato. Questa intestazione è obbligatoria.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
Valore Descrizione
wns/distintivo Una notifica per creare un overlay badge sul riquadro. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su text/xml.
wns/piastrella Notifica di aggiornamento del contenuto del riquadro. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su text/xml.
wns/toast Notifica per inviare un messaggio di congratulazioni nel client. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su text/xml.
"wns/raw" Notifica che può contenere un payload personalizzato e viene recapitata direttamente all'app. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su application/octet-stream.

X-WNS-Cache-Policy

Quando il dispositivo di destinazione delle notifiche è offline, WNS memorizza nella cache un badge, un riquadro e una notifica toast per ogni URI del canale. Per impostazione predefinita, le notifiche non elaborate non vengono memorizzate nella cache, ma se la memorizzazione nella cache delle notifiche non elaborate è abilitata, viene memorizzata nella cache una notifica non elaborata. Gli elementi non vengono mantenuti nella cache per un periodo illimitato e verranno eliminati dopo un periodo di tempo ragionevole. In caso contrario, il contenuto memorizzato nella cache viene recapitato quando il dispositivo diventa online.

X-WNS-Cache-Policy: cache | no-cache
Valore Descrizione
cache Predefinito Le notifiche verranno memorizzate nella cache se l'utente è offline. Questa è l'impostazione predefinita per le notifiche di tipo tile e badge.
nessuna memorizzazione nella cache La notifica non verrà memorizzata nella cache se l'utente è offline. Questa è l'impostazione predefinita per le notifiche non elaborate.

X-WNS-RequestForStatus

Specifica se la risposta deve includere lo stato del dispositivo e lo stato della connessione WNS. Questa intestazione è facoltativa.

    X-WNS-RequestForStatus: true | false
Valore Descrizione
vero Restituisce lo stato del dispositivo e lo stato della notifica nella risposta.
falso Predefinito Non restituire lo stato del dispositivo e lo stato della notifica.

X-WNS-Tag

Assegna un'etichetta di tag a una notifica. Il tag viene usato nei criteri di sostituzione del riquadro nella coda di notifica quando l'app ha optato per il ciclo delle notifiche. Se nella coda esiste già una notifica con questo tag, una nuova notifica con lo stesso tag prende il suo posto.

Annotazioni

Questa intestazione è facoltativa e utilizzata solo quando si inviano notifiche di riquadri.

    X-WNS-Tag: <string value>
Valore Descrizione
valore di stringa Stringa alfanumerica di non più di 16 caratteri.

X-WNS-TTL

Specifica il TTL (tempo di vita) per una notifica. Questo generalmente non è necessario, ma può essere usato se vuoi assicurarti che le notifiche non vengano visualizzate oltre un determinato orario. La durata (TTL) viene specificata in secondi ed è relativa al tempo in cui WNS riceve la richiesta. Quando viene specificato un TTL, il dispositivo non visualizzerà la notifica dopo tale ora. Si noti che ciò potrebbe comportare che la notifica non venga mai visualizzata se la durata (TTL) è troppo breve. In generale, un'ora di scadenza verrà misurata in almeno minuti.

Questa intestazione è facoltativa. Se non viene specificato alcun valore, la notifica non scade e verrà sostituita nello schema di sostituzione delle notifiche normale.

X-WNS-TTL: <integer value>

Valore Descrizione
valore intero Durata della notifica, in secondi, dopo che WNS riceve la richiesta.

X-WNS-SuppressPopup

Annotazioni

Per le app di Windows Phone Store, puoi sopprimere l'interfaccia utente di una notifica di tipo toast, inviando la notifica direttamente al centro notifiche. In questo modo la notifica viene recapitata silenziosamente, un'opzione potenzialmente superiore per notifiche meno urgenti. L'intestazione è facoltativa e viene usata solo nei canali di Windows Phone. Se includi questa intestazione in un canale Windows, la tua notifica verrà eliminata e otterrai una risposta di errore da WNS.

X-WNS-SuppressPopup: vero | falso

Valore Descrizione
vero Invia la notifica toast direttamente al centro notifiche; non mostrare l'interfaccia toast.
falso Predefinito Attivare l'interfaccia utente del toast e aggiungere la notifica al centro azioni.

X-WNS-Group

Annotazioni

Il centro notifiche per le app di Windows Phone Store può visualizzare più notifiche toast con lo stesso tag solo se sono classificate come appartenere a gruppi diversi. Si consideri, ad esempio, un'app libro di ricette. Ogni ricetta viene identificata da un tag. Una notifica che contiene un commento su quella ricetta avrebbe il tag della ricetta, ma un'etichetta di gruppo commenti. Una notifica che contiene una valutazione per quella ricetta avrebbe ancora il tag della ricetta, ma avrebbe un'etichetta di valutazione di gruppo. Queste diverse etichette di gruppo consentono di visualizzare contemporaneamente entrambe le notifiche toast nel centro notifiche. Questa intestazione è facoltativa.

Gruppo X-WNS: <string value>

Valore Descrizione
valore di stringa Stringa alfanumerica di non più di 16 caratteri.

X-WNS-Match

Annotazioni

Usato con il metodo HTTP DELETE per rimuovere un toast specifico, un set di toast (tramite tag o gruppo) o tutti i toast dal centro notifiche per le app di Windows Phone Store. Questa intestazione può specificare un gruppo, un tag o entrambi. Questa intestazione è necessaria in una richiesta di notifica HTTP DELETE. Qualsiasi payload incluso in questa richiesta di notifica viene ignorato.

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; tutto

Valore Descrizione
type:wns/toast; group=<string value>; tag=<string value> Rimuovere una singola notifica etichettata con il tag e il gruppo specificati.
type:wns/toast; group=<string value> Rimuovere tutte le notifiche etichettate con il gruppo specificato.
type:wns/toast; tag=<string value> Rimuovere tutte le notifiche etichettate con il tag specificato.
type:wns/toast; tutto Cancellare tutte le notifiche dell'app dal centro notifiche.

Inviare una risposta di notifica

Dopo che WNS elabora la richiesta di notifica, invia un messaggio HTTP in risposta. In questa sezione vengono discussi i parametri e le intestazioni disponibili in tale risposta.

Parametri di risposta

Nome dell'intestazione Obbligatorio Descrizione
X-WNS-Debug-Trace Falso Informazioni di debug che devono essere registrate per risolvere i problemi durante la segnalazione di un problema.
X-WNS-DeviceConnectionStatus Falso Lo stato del dispositivo, restituito solo se richiesto nella richiesta di notifica tramite l'intestazione X-WNS-RequestForStatus.
X-WNS-Error-Description Falso Una stringa di errore facilmente comprensibile che dovrebbe essere registrata per facilitare il debug.
X-WNS-Msg-ID Falso Identificatore univoco per la notifica, utilizzato a scopo di debug. Quando si segnala un problema, queste informazioni devono essere registrate per facilitare la risoluzione dei problemi.
X-WNS-Status Falso Indica se WNS ha ricevuto ed elaborato correttamente la notifica. Quando si segnala un problema, queste informazioni devono essere registrate per facilitare la risoluzione dei problemi.
MS-CV Falso Informazioni di debug che devono essere registrate per risolvere i problemi durante la segnalazione di un problema.

X-WNS-Debug-Trace

Questa intestazione restituisce informazioni di diagnostica utili sotto forma di stringa. È consigliabile registrare questa intestazione per aiutare gli sviluppatori a eseguire il debug dei problemi. Questa intestazione, insieme all'intestazione X-WNS-Msg-ID e a MS-CV, è necessaria quando si segnala un problema a WNS.

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

Valore Descrizione
valore di stringa Stringa alfanumerica.

X-WNS-DeviceConnectionStatus

Questa intestazione restituisce lo stato del dispositivo all'applicazione chiamante, se richiesta nell'intestazione X-WNS-RequestForStatus della richiesta di notifica.

X-WNS-DeviceConnectionStatus: connesso | disconnesso | tempdisconnesso

Valore Descrizione
connesso Il dispositivo è online e connesso a WNS.
disconnesso Il dispositivo è offline e non è connesso a WNS.
tempconnected (deprecato) Il dispositivo ha perso temporaneamente la connessione a WNS, ad esempio quando si interrompe una connessione 3G o l'interruttore wireless su un portatile viene attivato. La piattaforma Client Notifiche lo considera come un'interruzione temporanea anziché una disconnessione intenzionale.

X-WNS-Error-Description

Questa intestazione fornisce una stringa di errore leggibile che deve essere registrata per facilitare il debug.

Descrizione dell'errore X-WNS: <string value>

Valore Descrizione
valore di stringa Stringa alfanumerica.

X-WNS-Msg-ID

Questa intestazione viene usata per fornire a chi riceve la chiamata un identificatore per la notifica. È consigliabile registrare questa intestazione per facilitare il debug dei problemi. Questa intestazione, insieme agli X-WNS-Debug-Trace e MS-CV, è necessaria quando si segnala un problema a WNS.

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

Valore Descrizione
valore di stringa Stringa alfanumerica di non più di 16 caratteri.

X-WNS-Status

Questa intestazione spiega come WNS ha gestito la richiesta di notifica. Questa operazione può essere usata invece di interpretare i codici di risposta come esito positivo o negativo.

X-WNS-Status: ricevuto | eliminato | limitato dal canale

Valore Descrizione
ricevuto La notifica è stata ricevuta ed elaborata da WNS. Nota: ciò non garantisce che il dispositivo abbia ricevuto la notifica.
Caduto La notifica è stata eliminata in modo esplicito a causa di un errore o perché il client ha rifiutato esplicitamente queste notifiche. Anche le notifiche toast verranno eliminate se il dispositivo è offline.
canale-limitato La notifica è stata eliminata perché il server app ha superato il limite di frequenza per questo canale specifico.

MS-CV

Questa intestazione fornisce un vettore di correlazione correlato alla richiesta usata principalmente per il debug. Se un CV viene fornito come parte della richiesta, WNS userà questo valore, altrimenti WNS genererà e risponderà con un CV. Questa intestazione, insieme all'intestazione X-WNS-Debug-Trace e X-WNS-Msg-ID , è necessaria quando si segnala un problema a WNS.

Importante

Si prega di generare un nuovo CV per ogni richiesta di notifica push se si fornisce il proprio CV.

MS-CV: <string value>

Valore Descrizione
valore di stringa Segue lo standard del vettore di correlazione

Codici di risposta

Ogni messaggio HTTP contiene uno di questi codici di risposta. WNS consiglia agli sviluppatori di registrare il codice di risposta da usare nel debug. Quando gli sviluppatori segnalano un problema a WNS, devono fornire codici di risposta e informazioni sull'intestazione.

Codice di risposta HTTP Descrizione Azione consigliata
200 Va bene La notifica è stata accettata da WNS. Non necessari.
400 Richiesta non valida Una o più intestazioni sono state specificate non correttamente o sono in conflitto con altre intestazioni. Registrare i dettagli della richiesta. Esaminare la richiesta e confrontare la documentazione.
401 - Non autorizzato Il servizio cloud non ha presentato un ticket di autenticazione valido. Il ticket OAuth potrebbe non essere valido. Richiedere un token di accesso valido autenticando il servizio cloud usando la richiesta del token di accesso.
403 Vietato Il servizio cloud non è autorizzato a inviare una notifica a questo URI anche se sono autenticati. Il token di accesso fornito nella richiesta non corrisponde alle credenziali dell'app che ha richiesto l'URI del canale. Assicurati che il nome del pacchetto nel file manifest della tua app corrisponda alle credenziali del servizio cloud specificate alla tua app nel Dashboard.
404 Non trovato L'URI del canale non è valido o non è riconosciuto da WNS. Registrare i dettagli della richiesta. Non inviare ulteriori notifiche a questo canale; le notifiche a questo indirizzo avranno esito negativo.
405 Metodo non consentito Metodo non valido (GET, CREATE); è consentito solo POST (Windows o Windows Phone) o DELETE (solo Windows Phone). Registrare i dettagli della richiesta. Passare all'uso di HTTP POST.
406 Non accettabile Il servizio cloud ha superato il limite di capacità. Invia la richiesta dopo il valore dell'intestazione Retry-After nella risposta.
410 Scomparso Il canale è scaduto. Registrare i dettagli della richiesta. Non inviare ulteriori notifiche a questo canale. Chiedere all'app un nuovo URI del canale.
410 Dominio bloccato Il dominio di invio è stato bloccato da WNS. Non inviare ulteriori notifiche a questo canale. Il dominio di invio è stato bloccato da WNS per l'abuso di notifiche push.
413 Richiesta HTTP - Entità troppo grande Il payload di notifica supera il limite di dimensione di 5000 byte. Registrare i dettagli della richiesta. Esaminare il payload per verificare che rientri nei limiti di dimensioni.
500 Errore interno del server Un errore interno ha causato l'esito negativo del recapito delle notifiche. Registrare i dettagli della richiesta. Segnalare questo problema tramite i forum per sviluppatori.
503 Servizio non disponibile Il server non è attualmente disponibile. Registrare i dettagli della richiesta. Segnalare questo problema tramite i forum per sviluppatori. Se si osserva l'intestazione Retry-After, si prega di inviare la richiesta dopo il valore dell'intestazione Retry-After nella risposta.

Funzionalità HTTP non supportate

L'interfaccia Web WNS supporta HTTP 1.1, ma non supporta le funzionalità seguenti:

  • Chunking
  • Pipelining (POST non è idempotente)
  • Anche se supportato, gli sviluppatori devono disabilitare Expect-100 perché introduce la latenza durante l'invio di una notifica.