Condividi tramite

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

  • Articolo

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

Per una descrizione concettuale dei concetti, dei requisiti e del funzionamento, vedere la panoramica relativa aiWindows Push Notification Services (WNS).

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.

Access token request (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 inviata all'uso https://login.live.com/accesstoken.srf di Secure Sockets Layer (SSL).

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 Richiesto Descrizione
grant_type TRUE Deve essere impostato su client_credentials.
client_id TRUE ID di sicurezza del pacchetto (SID) per il servizio cloud assegnato al momento della registrazione dell'app in Microsoft Store.
client_secret TRUE Chiave privata per il servizio cloud assegnato al momento della registrazione dell'app in Microsoft Store.
ambito TRUE 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 supporto "application/json".

Parametro Richiesto Descrizione
access_token TRUE Token di accesso che il servizio cloud userà quando invia una notifica.
token_type FALSE Viene restituito sempre come bearer.

Codice della risposta

Codice di risposta HTTP Descrizione
200 OK La richiesta è stata completata.
400 Richiesta non valida L'autenticazione non è riuscita. Per i parametri di risposta, vedere la bozza OAuth Request for Comments (RFC).

Esempio

Il seguente mostra un esempio della 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 recapitare 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 o non supportate.

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

Parametri della richiesta

Nome intestazione Obbligatorio Descrizione
Autorizzazione TRUE Intestazione di autorizzazione HTTP standard usata per autenticare la richiesta di notifica. Il servizio cloud fornisce il token di accesso in questa intestazione.
Content-Type TRUE Intestazione di autorizzazione HTTP standard. Per le notifiche di tipo avviso popup, 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.
Content-Length TRUE Intestazione di autorizzazione HTTP standard per indicare le dimensioni del payload della richiesta.
Tipo X-WNS TRUE Definisce il tipo di notifica nel payload: riquadro, avviso popup, badge o non elaborato.
Criteri di cache X-WNS FALSE Abilita o disabilita la memorizzazione nella cache delle notifiche. Questa intestazione si applica solo a riquadri, notifiche e notifiche non elaborate.
X-WNS-RequestForStatus FALSE Richiede lo stato del dispositivo e lo stato della connessione WNS nella risposta di notifica.
X-WNS-Tag FALSE 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 FALSE Valore intero, espresso in secondi, che specifica la durata (TTL).
MS-CV FALSE 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 usata per specificare le credenziali dell'entità chiamante, seguendo il metodo di autorizzazione OAuth 2.0 per i token di connessione .

La sintassi è costituita da un valore letterale stringa "Bearer", seguito da uno spazio, seguito dal 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>

Tipo X-WNS

Questi sono i tipi di notifica supportato 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 rispetto a questo tipo specificato. Questa intestazione è obbligatoria.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
valore Descrizione
wns/badge Notifica per creare una sovrimpressione badge nel riquadro. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su text/xml.
wns/riquadro Notifica per aggiornare il contenuto del riquadro. L'intestazione Content-Type inclusa nella richiesta di notifica deve essere impostata su text/xml.
wns/toast Notifica per generare 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.

Criteri di cache X-WNS

Quando il dispositivo di destinazione delle notifiche è offline, WNS memorizza nella cache una notifica, un riquadro e una notifica di tipo avviso popup 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 riquadro e badge.
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 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.
false 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, viene eseguita una nuova notifica con lo stesso tag.

Nota

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

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

X-WNS-TTL

Specifica la durata (ora di scadenza) per una notifica. Questo non è in genere necessario, ma può essere usato se vuoi assicurarti che le notifiche non vengano visualizzate in un secondo momento. 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

Nota

Per le app di Windows Telefono Store, hai la possibilità di eliminare l'interfaccia utente di una notifica di tipo avviso popup, invece di inviare la notifica direttamente al centro notifiche. In questo modo la notifica viene recapitata automaticamente, un'opzione potenzialmente superiore per notifiche meno urgenti. Questa intestazione è facoltativa e usata solo nei canali di Windows Telefono. Se includi questa intestazione in un canale Windows, la notifica verrà eliminata e riceverai una risposta di errore da WNS.

X-WNS-SuppressPopup: true | False

valore Descrizione
vero Inviare la notifica di tipo avviso popup direttamente al centro notifiche; non generare l'interfaccia utente di tipo avviso popup.
false Predefinito. Generare l'interfaccia utente di tipo avviso popup e aggiungere la notifica al centro notifiche.

X-WNS-Group

Nota

Il centro notifiche per le app di Windows Telefono Store può visualizzare più notifiche di tipo avviso popup con lo stesso tag solo se sono etichettate come appartenenti a gruppi diversi. Si consideri, ad esempio, un'app libro di ricette. Ogni ricetta viene identificata da un tag. Un avviso popup che contiene un commento su tale ricetta avrebbe il tag della ricetta, ma un'etichetta di gruppo di commenti. Un avviso popup che contiene una classificazione per tale ricetta avrebbe di nuovo il tag della ricetta, ma avrebbe un'etichetta di gruppo di classificazione. Queste etichette di gruppo diverse consentono di visualizzare entrambe le notifiche di tipo avviso popup contemporaneamente nel centro notifiche. Questa intestazione è facoltativa.

X-WNS-Group: <string value>

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

X-WNS-Match

Nota

Usato con il metodo HTTP DELETE per rimuovere un avviso popup specifico, un set di avvisi popup (tramite tag o gruppo) o tutti gli avvisi popup dal centro notifiche per le app di Windows Telefono 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; Tutti

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; Tutti Cancella tutte le tue notifiche 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 illustrati i parametri e le intestazioni disponibili in tale risposta.

Parametri di risposta

Nome intestazione Obbligatorio Descrizione
X-WNS-Debug-Trace FALSE Informazioni di debug che devono essere registrate per risolvere i problemi durante la segnalazione di un problema.
X-WNS-Device Connessione ionStatus FALSE Lo stato del dispositivo, restituito solo se richiesto nella richiesta di notifica tramite l'intestazione X-WNS-RequestForStatus.
Descrizione dell'errore X-WNS FALSE Stringa di errore leggibile che deve essere registrata per facilitare il debug.
X-WNS-Msg-ID FALSE 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 FALSE 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 FALSE 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 debug utili come 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 stringa Una stringa alfanumerica.

X-WNS-Device Connessione ionStatus

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

X-WNS-Device Connessione ionStatus: connesso | disconnesso | tempdisconnected

valore Descrizione
connected Il dispositivo è online e connesso a WNS.
disconnesso Il dispositivo è offline e non è connesso a WNS.
tempconnected (deprecato) Il dispositivo perde temporaneamente la connessione a WNS, ad esempio quando viene eliminata una connessione 3G o viene generata l'opzione wireless su un portatile. La piattaforma client di notifica viene considerata come un'interruzione temporanea anziché una disconnessione intenzionale.

Descrizione dell'errore X-WNS

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 stringa Una stringa alfanumerica.

X-WNS-Msg-ID

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

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

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

X-WNS-Status

Questa intestazione descrive 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 | channelthrottled

valore Descrizione
ricevuti La notifica è stata ricevuta ed elaborata da WNS. Nota: ciò non garantisce che il dispositivo abbia ricevuto la notifica.
dropped La notifica è stata eliminata in modo esplicito a causa di un errore o perché il client ha rifiutato esplicitamente queste notifiche. Le notifiche di tipo avviso popup verranno eliminate anche se il dispositivo è offline.
channelthrottled 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 sta fornendo il proprio CV.

MS-CV: <string value>

valore Descrizione
valore 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 OK La notifica è stata accettata da WNS. Non necessari.
400 Richiesta non valida Una o più intestazioni sono state specificate in modo non corretto o in conflitto con un'altra intestazione. 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 Negato 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. Assicurarsi che il nome del pacchetto nel manifesto dell'app corrisponda alle credenziali del servizio cloud specificate all'app nel dashboard.
404 Not Found 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 Method Not Allowed Metodo non valido (GET, CREATE); è consentito solo POST (Windows o Windows Telefono) o DELETE (solo Windows Telefono). Registrare i dettagli della richiesta. Passare all'uso di HTTP POST.
406 - Non accettabile Il servizio cloud ha superato il limite di limitazione. Inviare la richiesta dopo il valore dell'intestazione Retry-After nella risposta
410 - Non disponibile 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 Entità della richiesta troppo grande Il payload di notifica supera il limite di dimensioni di 5000 byte. Registrare i dettagli della richiesta. Esaminare il payload per assicurarsi che sia entro le limitazioni delle 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 viene osservata l'intestazione Retry-After, 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:

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