Intestazioni delle richieste e delle risposte per il servizio di notifica Push (app di Windows Runtime)
[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]
Questo argomento descrive i protocolli e le API Web necessari tra i servizi per inviare una notifica push.
Per informazioni relative ai concetti, ai requisiti e al funzionamento delle notifiche push e di WNS, vedi Panoramica di Servizi notifica Push Windows.
Richiesta e ricezione di un token di accesso
Questa sezione descrive i parametri della richiesta e della risposta necessari per l'autenticazione con WNS.
Richiesta del token di accesso
Per autenticare il servizio cloud e recuperare in cambio un token di accesso, viene inviata una richiesta HTTP a WNS. La richiesta viene inviata al nome di dominio completo (FQDN) seguente mediante Secure Sockets Layer (SSL).
https://login.live.com/accesstoken.srf
Parametri della richiesta del token di accesso
Il servizio cloud invia i parametri obbligatori nel corpo della richiesta HTTP usando il formato "application/x-www-form-urlencoded". Devi verificare che tutti i parametri usino la codifica URL.
| Parametro | Obbligatorio/Facoltativo | Descrizione |
|---|---|---|
| grant_type | Obbligatorio | Deve essere impostato su "client_credentials". |
| client_id | Obbligatorio | ID di sicurezza (SID) del pacchetto per il servizio cloud assegnato durante la registrazione dell'app in Windows Store. |
| client_secret | Obbligatorio | Chiave privata del servizio cloud assegnata durante la registrazione dell'app in Windows Store. |
| scope | Obbligatorio | Deve essere impostato su:
|
Risposta con il token di accesso
WNS autentica il servizio cloud e, in caso di esito positivo, invia la risposta "200 OK" che include il token di accesso. In caso contrario, WNS invia un codice di errore HTTP appropriato in conformità alla bozza del protocollo OAuth 2.0.
Parametri della risposta con il token di accesso
Se il servizio cloud viene autenticato, la risposta HTTP contiene un token di accesso. Questo token di accesso può essere usato nelle richieste di notifica fino a quando non scade. La risposta HTTP usa il tipo di contenuto multimediale "application/json".
| Parametro | Obbligatorio/Facoltativo | Descrizione |
|---|---|---|
| access_token | Obbligatorio | Token di accesso che verrà usato dal servizio cloud per l'invio di una notifica. |
| token_type | Facoltativo | È sempre impostato su "bearer". |
Codice di risposta
| Codice della risposta HTTP | Descrizione |
|---|---|
| 200 OK | La richiesta ha avuto esito positivo. |
| 400 Richiesta non valida | L'autenticazione non è riuscita. Per i parametri della risposta, vedi la specifica RFC (Request for Comments) della bozza di OAuth. |
Esempio
Di seguito è riportato un esempio di una risposta di autenticazione positiva:
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Length: 422
Content-Type: application/json
{
"access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=",
"token_type":"bearer"
}
Invio di una richiesta di notifica e ricezione di una risposta
Questa sezione descrive le intestazioni usate sia in una richiesta HTTP inviata a WNS per il recapito di una notifica che nella risposta.
- Invio della richiesta di notifica
- Invio della risposta di notifica
- Funzionalità HTTP non supportate
Invio della richiesta di notifica
Durante l'invio di una richiesta di notifica, l'app chiamante invia una richiesta HTTP attraverso SSL all'URI (Uniform Resource Identifier) del canale. Nella richiesta deve essere specificata l'intestazione HTTP standard "Content-Length". Tutte le altre intestazioni standard sono facoltative o non supportate.
Nella richiesta di notifica è inoltre possibile usare le intestazioni personalizzate elencate di seguito. Alcune intestazioni sono obbligatorie, mentre altre sono facoltative.
Parametri della richiesta
| Nome dell'intestazione | Obbligatorio/Facoltativo | Descrizione |
|---|---|---|
| Authorization | Obbligatorio | Intestazione di autorizzazione HTTP standard usata per autenticare la richiesta di notifica. Il servizio cloud specifica il token di accesso in questa intestazione. |
| Content-Type | Obbligatorio | Intestazione di autorizzazione HTTP standard. Per le notifiche di tipo avviso popup, riquadro e notifica, questa intestazione deve essere impostata su "text/xml". Per le notifiche non elaboratore, questa intestazione deve essere impostata su "application/octet-stream". |
| Content-Length | Obbligatorio | Intestazione di autorizzazione HTTP standard che indica la dimensione del payload della richiesta. |
| X-WNS-Type | Obbligatorio | Definisce il tipo di notifica nel payload: relativa ai riquadri, di tipo avviso popup o non elaborata. |
| X-WNS-Cache-Policy | Facoltativo | Abilita o disabilita la memorizzazione nella cache delle notifiche. Questa intestazione si applica solo alle notifiche di tipo riquadro e notifica e alle notifiche non elaborate. |
| X-WNS-RequestForStatus | Facoltativo | Richiede lo stato del dispositivo e della connessione a WNS nella risposta di notifica. |
| X-WNS-Tag | Facoltativo | Stringa usata per fornire una notifica con un'etichetta identificativa per riquadri che supportano la coda notifiche. Questa intestazione si applica solo alle notifiche di riquadro. |
| X-WNS-TTL | Facoltativo | Valore intero, espresso in secondi, che specifica la durata (TTL). |
| X-WNS-SuppressPopup | Facoltativo | Solo Windows Phone: invia una notifica di tipo avviso popup direttamente al centro operativo senza generare l'avviso popup stesso. |
| X-WNS-Group | Facoltativo | Solo Windows Phone: usata con l'intestazione X-WNS-Tag per raggruppare le notifiche nel centro operativo. |
| X-WNS-Match | Obbligatorio in base alla situazione | Solo Windows Phone: necessario per identificare la destinazione o le destinazioni quando si rimuove una notifica di tipo avviso popup dal centro operativo tramite il metodo HTTP DELETE. |
Note importanti
- Content-Length e Content-Type sono le uniche intestazioni HTTP standard incluse nella notifica recapitata al client, indipendentemente dalla presenza di altre intestazioni standard nella richiesta.
- Tutte le altre intestazioni HTTP standard vengono ignorate o restituiscono un errore se la funzionalità non è supportata.
Authorization
L'intestazione di autorizzazione viene usata per specificare le credenziali della parte chiamante, in base al metodo di autorizzazione OAuth 2.0 per i token bearer.
La sintassi è costituita da un valore letterale stringa "Bearer", seguito da uno spazio e quindi dal token di accesso. Il token di accesso viene recuperato mediante l'invio di un'apposita richiesta come descritto sopra. Questo stesso token di accesso può essere usato nelle richieste di notifica successive fino a quando non scade.
Questa intestazione è obbligatoria.
Authorization: Bearer <access-token>
X-WNS-Type
Tipi di notifica supportati da WNS. Questa intestazione indica il tipo di notifica e come deve essere gestito da WNS. Dopo il recapito della notifica al client, il payload effettivo viene convalidato rispetto al tipo specificato. Questa intestazione è obbligatoria.
X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
| Valore | Descrizione |
|---|---|
| wns/badge | Notifica per la creazione di una sovrapposizione nel riquadro. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su "text/xml". |
| wns/tile | Notifica per l'aggiornamento del contenuto del riquadro. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su "text/xml". |
| wns/toast | Notifica per la generazione di un avviso popup 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
Se il dispositivo di destinazione della notifica è offline, WNS memorizzerà nella cache una notifica relativa ai riquadri per ogni app. Se per l'app è abilitato il ciclo delle notifiche, WNS memorizzerà nella cache fino a cinque notifiche di riquadro. Per impostazione predefinita, le notifiche non elaborate non vengono memorizzate nella cache, ma se la memorizzazione nella cache di tali notifiche è abilitata, una sola notifica non elaborata viene memorizzata nella cache. Gli elementi non rimangono memorizzati nella cache all'infinito e vengono eliminati dopo un periodo di tempo ragionevole. In caso contrario, il contenuto memorizzato nella cache verrà recapitato quando il dispositivo sarà di nuovo online.
Questa intestazione è facoltativa e deve essere usata solo se il servizio cloud richiede l'override del comportamento predefinito di memorizzazione nella cache.
X-WNS-Cache-Policy: cache | no-cache
| Valore | Descrizione |
|---|---|
| cache | Impostazione predefinita. Le notifiche non verranno memorizzate nella cache se l'utente è offline. Questa è l'impostazione predefinita per le notifiche di tipo riquadro e notifica. |
| no-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 della connessione a WNS. Questa intestazione è facoltativa.
X-WNS-RequestForStatus: true | false
| Valore | Descrizione |
|---|---|
| true | Restituisce lo stato del dispositivo e della notifica nella risposta. |
| false | Impostazione predefinita. Non restituisce lo stato del dispositivo e della notifica. |
X-WNS-Tag
Assegna un'etichetta tag a una notifica. Il tag viene usato nei criteri di sostituzione del riquadro all'interno della coda notifiche quando per l'app è abilitato il ciclo delle notifiche. Se nella coda è già presente una notifica con questo tag, verrà sostituita da una nuova notifica con lo stesso tag.
Nota Questa intestazione è facoltativa e viene usata solo per l'invio di notifiche di tipo riquadro.
Nota Per le app di Windows Phone Store, l'intestazione X-WNS-Tag può essere usata con l'intestazione X-WNS-Group per consentire la visualizzazione di più notifiche con lo stesso tag nel centro operativo.
X-WNS-Tag: <string value>
| Valore | Descrizione |
|---|---|
| valore stringa | Stringa alfanumerica contenente al massimo 16 caratteri. |
X-WNS-TTL
Specifica il valore TTL (scadenza) per una notifica. In genere non è necessaria, ma può essere usata se vuoi essere certo che le notifiche non vengano visualizzate dopo un determinato periodo di tempo. Il valore TTL viene espresso in secondi a partire dal momento in cui WNS riceve la richiesta. Se è specificato un valore TTL, il dispositivo non visualizzerà la notifica dopo questo termine. Nota che se il valore TTL è troppo basso, la notifica potrebbe non essere mai visualizzata. In generale, la scadenza di una notifica deve essere almeno di qualche minuto.
Questa intestazione è facoltativa. Se non è specificato alcun valore, la notifica non avrà scadenza e verrà sostituita in base allo schema di sostituzione normale.
X-WNS-TTL: <integer value>
| Valore | Descrizione |
|---|---|
| valore intero | Durata della notifica, espressa in secondi, a partire dal momento in cui WNS riceve la richiesta. |
X-WNS-SuppressPopup
Nota Per le app di Windows Phone Store, hai la possibilità di eliminare l'interfaccia utente di una notifica di tipo avviso popup anziché inviare la notifica direttamente al centro operativo. In questo modo le notifiche possono essere inviate automaticamente. È consigliabile usare questa opzione per le notifiche meno urgenti. Questa intestazione è facoltativa e viene usata solo nei canali di Windows Phone. Se includi questa intestazione in un canale di Windows, la notifica verrà rimossa e riceverai una risposta di errore da WNS.
X-WNS-SuppressPopup: true | false
| Valore | Descrizione |
|---|---|
| true | Invia la notifica di tipo avviso popup direttamente al centro operativo. Non genera l'interfaccia utente dell'avviso popup. |
| false | Impostazione predefinita. Genera l'interfaccia utente dell'avviso popup e aggiunge la notifica al centro operativo. |
X-WNS-Group
Nota Il centro operativo per le app di Windows Phone Store può visualizzare più notifiche di tipo avviso popup con lo stesso tag solo se sono etichettate come appartenenti a gruppi diversi. Ad esempio, considera l'app di un libro di ricette. Ogni ricetta viene identificata da un tag. Un avviso popup che contiene un commento su una ricetta avrà il tag della ricetta ma l'etichetta di un gruppo di commenti. Un avviso popup che contiene una classificazione di tale ricetta avrà il tag della ricetta ma l'etichetta di un gruppo di classificazione. Le etichette di gruppi diversi consentono ad entrambe le notifiche di tipo avviso popup di essere visualizzate contemporaneamente nel centro operativo. Questa intestazione è facoltativa.
X-WNS-Group: <string value>
| Valore | Descrizione |
|---|---|
| valore stringa | Stringa alfanumerica contenente al massimo 16 caratteri. |
X-WNS-Match
Nota Usata con il metodo HTTP DELETE per rimuovere un avviso popup specifico, un set di avvisi popup (per tag o per gruppo) o tutti gli avvisi popup dal centro operativo per le app di Windows Phone Store. Questa intestazione può specificare un gruppo, un tag o entrambi ed è obbligatoria in una richiesta di notifica HTTP DELETE. Tutti i payload inclusi in questa richiesta di notifica vengono ignorati.
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
| Valore | Descrizione |
|---|---|
| type:wns/toast;group=<valore stringa>;tag=<valore stringa> | Rimuove una notifica singola etichettata con il tag e il gruppo specificati. |
| type:wns/toast;group=<valore stringa> | Rimuove tutte le notifiche etichettate con il gruppo specifico. |
| type:wns/toast;tag=<valore stringa> | Rimuove tutte le notifiche etichettate con il tag specifico. |
| type:wns/toast;all | Cancella tutte le notifiche dell'app dal centro operativo. |
Invio della risposta di notifica
Dopo l'elaborazione della richiesta di notifica, WNS invia un messaggio HTTP di risposta. Questa sezione illustra i parametri e le intestazioni che possono essere presenti nella risposta.
Parametri della risposta
| Nome dell'intestazione | Obbligatorio/Facoltativo | Descrizione |
|---|---|---|
| X-WNS-Debug-Trace | Facoltativo | Informazioni di debug da registrare per facilitare la risoluzione dei problemi. |
| X-WNS-DeviceConnectionStatus | Facoltativo | Stato del dispositivo, restituito solo se previsto nella richiesta di notifica mediante l'intestazione X-WNS-RequestForStatus. |
| X-WNS-Error-Description | Facoltativo | Stringa di errore leggibile da registrare per facilitare il debug. |
| X-WNS-Msg-ID | Facoltativo | Identificatore univoco della notifica, usato a scopo di debug. Queste informazioni devono essere registrate durante la segnalazione di un problema per facilitare la risoluzione. |
| X-WNS-Status | Facoltativo | Indica se WNS ha ricevuto ed elaborato la notifica. Queste informazioni devono essere registrate durante la segnalazione di un problema per facilitare la risoluzione. |
X-WNS-Debug-Trace
Questa intestazione restituisce informazioni di debug utili sotto forma di stringa. È consigliabile registrare questa intestazione per facilitare il debug da parte degli sviluppatori. Questa intestazione è necessaria, insieme a X-WNS-Msg-ID, per la segnalazione di un problema a WNS.
X-WNS-Debug-Trace: <string value>
| Valore | Descrizione |
|---|---|
| valore stringa | Stringa alfanumerica. |
X-WNS-DeviceConnectionStatus
Questa intestazione restituisce lo stato del dispositivo all'applicazione chiamante, se previsto nell'intestazione X-WNS-RequestForStatus della richiesta di notifica.
X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected
| Valore | Descrizione |
|---|---|
| connected | Il dispositivo è online e connesso a WNS. |
| disconnected | Il dispositivo è offline e non connesso a WNS. |
| tempconnected | Il dispositivo ha perso temporaneamente la connessione a WNS, ad esempio in caso di interruzione di una connessione 3G o spegnimento del commutatore wireless in un laptop. Questo valore viene interpretato dalla piattaforma del client di notifica come un'interruzione temporanea anziché una disconnessione intenzionale. |
X-WNS-Error-Description
Questa intestazione fornisce una stringa di errore leggibile da registrare per facilitare il debug.
X-WNS-Error-Description: <string value>
| Valore | Descrizione |
|---|---|
| valore stringa | Stringa alfanumerica. |
X-WNS-Msg-ID
Questa intestazione viene usata per fornire al chiamante un identificatore della notifica. È consigliabile registrare questa intestazione per facilitare il debug. Questa intestazione è necessaria, insieme a X-WNS-Debug-Trace, per la segnalazione di un problema a WNS.
X-WNS-Msg-ID: <string value>
| Valore | Descrizione |
|---|---|
| valore stringa | Stringa alfanumerica contenente al massimo 16 caratteri. |
X-WNS-Status
Questa intestazione descrive come WNS ha gestito la richiesta di notifica. Può essere usata per evitare di interpretare l'esito positivo o negativo in base ai codici di risposta.
X-WNS-Status: received | dropped | channelthrottled
| Valore | Descrizione |
|---|---|
| received | La notifica è stata ricevuta ed elaborata da WNS. Nota Questo valore non garantisce che la notifica sia stata ricevuta dal dispositivo.
|
| dropped | La notifica è stata rimossa in modo esplicito a causa di un errore oppure perché il client ha rifiutato in modo esplicito questo tipo di notifiche. Le notifiche di tipo avviso popup vengono rimosse anche quando il dispositivo è offline. |
| channelthrottled | La notifica è stata rimossa perché il server applicazioni ha superato il limite di velocità di questo canale. |
Codici di risposta
Ogni messaggio HTTP contiene uno di questi codici di risposta. WNS consiglia agli sviluppatori di registrare il codice di risposta per il debug. Quando gli sviluppatori segnalano un problema a WNS, devono specificare i codici di risposta e le informazioni delle intestazioni.
| Codice della risposta HTTP | Descrizione | Azione consigliata |
|---|---|---|
| 200 OK | La notifica è stata accettata da WNS. | Nessuna. |
| 400 Richiesta non valida | Una o più intestazioni sono state specificate in modo errato o sono in conflitto tra loro. | Registra i dettagli della richiesta. Esamina la richiesta basandoti su questo documento. |
| 401 Autorizzazione negata | Il servizio cloud non ha presentato un ticket di autenticazione valido. Il ticket OAuth potrebbe non essere valido. | Richiedi un token di accesso valido eseguendo l'autenticazione del servizio cloud mediante la richiesta del token di accesso. |
| 403 Accesso negato | Il servizio cloud non è autorizzato a inviare una notifica a questo URI, nonostante sia autenticato. | Il token di accesso specificato nella richiesta non corrisponde alle credenziali dell'app che ha richiesto l'URI del canale. Verifica che il nome del pacchetto nel manifesto dell'app corrisponda alle credenziali del servizio cloud fornite all'app nel dashboard. |
| 404 Pagina non trovata | L'URI del canale non è valido o non viene riconosciuto da WNS. | Registra i dettagli della richiesta. Non inviare altre notifiche a questo canale. Le notifiche inviate a questo indirizzo non verranno recapitate. |
| 405 Metodo non concesso | Metodo non valido (GET, CREATE). Sono consentiti solo POST (Windows o Windows Phone) o DELETE (solo Windows Phone). | Registra i dettagli della richiesta. Usa il metodo HTTP POST. |
| 406 Pagina non valida | Il servizio cloud ha superato il limite di velocità. | Registra i dettagli della richiesta. Riduci la velocità di invio delle notifiche. |
| 410 Non più disponibile | Il canale è scaduto. | Registra i dettagli della richiesta. Non inviare altre notifiche a questo canale. Imposta l'app in modo da richiedere un nuovo URI di canale. |
| 413 Entità della richiesta troppo grande | Il payload della notifica supera la dimensione massima di 5000 byte. | Registra i dettagli della richiesta. Esamina il payload per verificare che rispetti i limiti previsti. |
| 500 Errore interno del server | Il recapito della notifica non è riuscito a causa di un errore interno. | Registra i dettagli della richiesta. Segnala questo problema nei forum per sviluppatori |
| 503 Servizio non disponibile | Il server non è attualmente disponibile. | Registra i dettagli della richiesta. Segnala questo problema nei forum per sviluppatori |
Per informazioni dettagliate sulla risoluzione di problemi riguardanti codici di risposta specifici, vedi Risoluzione dei problemi relativi a notifiche di tipo riquadro, di tipo avviso popup e badge. Vedi anche COM Error Codes (WPN, MBN, P2P, Bluetooth).
Funzionalità HTTP non supportate
L'interfaccia Web di WNS supporta HTTP 1.1, ma non le funzionalità seguenti:
- Suddivisione in blocchi
- Canalizzazione (POST non è idempotente)
- La funzionalità Expect-100, anche se supportata, deve essere disabilitata perché introduce una latenza durante l'invio di una notifica.
Argomenti correlati
Guida introduttiva: Invio di una notifica push
Linee guida ed elenco di controllo per le notifiche push
Come eseguire l'autenticazione con Servizi notifica Push Windows (WNS)
Come richiedere, creare e salvare un canale di notifica