Esporta (0) Stampa
Espandi tutto
Informazioni
L'argomento richiesto è visualizzato di seguito, ma non è incluso in questa libreria.

Intestazioni delle richieste e delle risposte per il servizio di notifica Push (app di Windows Runtime)

Applies to Windows and Windows Phone

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.

ParametroObbligatorio/FacoltativoDescrizione
grant_typeObbligatorioDeve essere impostato su "client_credentials".
client_idObbligatorioID di sicurezza (SID) del pacchetto per il servizio cloud assegnato durante la registrazione dell'app in Windows Store.
client_secretObbligatorioChiave privata del servizio cloud assegnata durante la registrazione dell'app in Windows Store.
scopeObbligatorioDeve essere impostato su:
  • Windows: "notify.windows.com"
  • Windows Phone: "notify.windows.com" o "s.notify.live.net"

 

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".

ParametroObbligatorio/FacoltativoDescrizione
access_tokenObbligatorioToken di accesso che verrà usato dal servizio cloud per l'invio di una notifica.
token_typeFacoltativoÈ sempre impostato su "bearer".

 

Codice di risposta

Codice della risposta HTTPDescrizione
200 OKLa richiesta ha avuto esito positivo.
400 Richiesta non validaL'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

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'intestazioneObbligatorio/FacoltativoDescrizione
AuthorizationObbligatorioIntestazione di autorizzazione HTTP standard usata per autenticare la richiesta di notifica. Il servizio cloud specifica il token di accesso in questa intestazione.
Content-TypeObbligatorioIntestazione 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-LengthObbligatorioIntestazione di autorizzazione HTTP standard che indica la dimensione del payload della richiesta.
X-WNS-TypeObbligatorioDefinisce il tipo di notifica nel payload: relativa ai riquadri, di tipo avviso popup o non elaborata.
X-WNS-Cache-PolicyFacoltativoAbilita 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-RequestForStatusFacoltativoRichiede lo stato del dispositivo e della connessione a WNS nella risposta di notifica.
X-WNS-TagFacoltativoStringa 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-TTLFacoltativoValore intero, espresso in secondi, che specifica la durata (TTL).
X-WNS-SuppressPopupFacoltativoSolo Windows Phone: invia una notifica di tipo avviso popup direttamente al centro operativo senza generare l'avviso popup stesso.
X-WNS-GroupFacoltativoSolo Windows Phone: usata con l'intestazione X-WNS-Tag per raggruppare le notifiche nel centro operativo.
X-WNS-MatchObbligatorio in base alla situazioneSolo 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
ValoreDescrizione
wns/badgeNotifica per la creazione di una sovrapposizione nel riquadro. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su "text/xml".
wns/tileNotifica per l'aggiornamento del contenuto del riquadro. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su "text/xml".
wns/toastNotifica 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/rawNotifica 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
ValoreDescrizione
cacheImpostazione 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-cacheLa 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
ValoreDescrizione
trueRestituisce lo stato del dispositivo e della notifica nella risposta.
falseImpostazione 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.

  • Applies to Windows Phone

In Windows Phone 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>
ValoreDescrizione
valore stringaStringa 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>
ValoreDescrizione
valore interoDurata della notifica, espressa in secondi, a partire dal momento in cui WNS riceve la richiesta.

 

X-WNS-SuppressPopup

  • Applies to Windows Phone

Consente 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
ValoreDescrizione
trueInvia la notifica di tipo avviso popup direttamente al centro operativo. Non genera l'interfaccia utente dell'avviso popup.
falseImpostazione predefinita. Genera l'interfaccia utente dell'avviso popup e aggiunge la notifica al centro operativo.

 

X-WNS-Group

  • Applies to Windows Phone

Il centro operativo di Windows Phone 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>
ValoreDescrizione
valore stringaStringa alfanumerica contenente al massimo 16 caratteri.

 

X-WNS-Match

  • Applies to Windows Phone

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 di Windows Phone. 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
ValoreDescrizione
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;allCancella 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'intestazioneObbligatorio/FacoltativoDescrizione
X-WNS-Debug-TraceFacoltativoInformazioni di debug da registrare per facilitare la risoluzione dei problemi.
X-WNS-DeviceConnectionStatusFacoltativoStato del dispositivo, restituito solo se previsto nella richiesta di notifica mediante l'intestazione X-WNS-RequestForStatus.
X-WNS-Error-DescriptionFacoltativoStringa di errore leggibile da registrare per facilitare il debug.
X-WNS-Msg-IDFacoltativoIdentificatore 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-StatusFacoltativoIndica 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>
ValoreDescrizione
valore stringaStringa 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
ValoreDescrizione
connectedIl dispositivo è online e connesso a WNS.
disconnectedIl dispositivo è offline e non connesso a WNS.
tempconnectedIl 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>
ValoreDescrizione
valore stringaStringa 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>
ValoreDescrizione
valore stringaStringa 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
ValoreDescrizione
receivedLa notifica è stata ricevuta ed elaborata da WNS.

Nota  Questo valore non garantisce che la notifica sia stata ricevuta dal dispositivo.

droppedLa 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.
channelthrottledLa 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 HTTPDescrizioneAzione consigliata
200 OKLa notifica è stata accettata da WNS.Nessuna.
400 Richiesta non validaUna 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 negataIl 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 negatoIl 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 trovataL'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 concessoMetodo 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 validaIl servizio cloud ha superato il limite di velocità.Registra i dettagli della richiesta. Riduci la velocità di invio delle notifiche.
410 Non più disponibileIl 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 grandeIl 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 serverIl 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 disponibileIl 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
Esempio di notifiche push e periodiche
Panoramica di WNS

 

 

Mostra:
© 2014 Microsoft