Hlavičky požadavků a odpovědí služby pro push oznámení (aplikace Windows Runtime)

Toto téma popisuje webová rozhraní API mezi službami a protokoly potřebné k odeslání push oznámení.

V přehledu služby WNS (Windows Push Notification Services) najdete koncepční diskuzi o konceptech nabízených oznámení a konceptech služby WNS, požadavcích a provozu.

Vyžádání a přijetí přístupového tokenu

Tato část popisuje parametry požadavku a odpovědi, které se používají při ověřování s WNS.

Žádost o přístupový token

Do služby WNS se odešle požadavek HTTP, který ověří cloudovou službu a načte přístupový token. Požadavek je odesílán na https://login.live.com/accesstoken.srf pomocí protokolu SSL (Secure Sockets Layer).

Parametry žádosti o přístupový token

Cloudová služba odešle tyto požadované parametry v textu požadavku HTTP pomocí formátu application/x-www-form-urlencoded. Musíte zajistit, aby všechny parametry byly zakódovány na adrese URL.

Parameter	Required	Description
grant_type	TRUE	Musí být nastavena na client_credentials.
client_id	TRUE	Identifikátor zabezpečení balíčku (SID) cloudové služby, který je přiřazený při registraci aplikace v Microsoft Storu.
client_secret	TRUE	Tajný klíč cloudové služby, který je přiřazený při registraci aplikace v Microsoft Storu.
obor	TRUE	Musí být nastaveno na notify.windows.com

Odpověď přístupového tokenu

Služba WNS ověří cloudovou službu a v případě úspěchu odpoví "200 OK", včetně přístupového tokenu. V opačném případě služba WNS odpoví odpovídajícím kódem chyby HTTP, jak je popsáno v konceptu protokolu OAuth 2.0.

Parametry odpovědi přístupového tokenu

Přístupový token se vrátí v odpovědi HTTP, pokud se cloudová služba úspěšně ověřila. Tento přístupový token lze použít v žádostech o oznámení, dokud nevyprší jeho platnost. Odpověď HTTP používá typ média application/json.

Parameter	Required	Description
access_token	TRUE	Přístupový token, který bude cloudová služba používat při odesílání oznámení.
token_type	FALSE	Vždy vráceno jako bearer.

Kód odpovědi

Kód odpovědi protokolu HTTP	Description
200 OK	Požadavek byl úspěšně zpracován.
400 – Chybný požadavek	Ověření se nezdařilo. Parametry odpovědi najdete v návrhu OAuth Request for Comments (RFC).

Example

Následuje příklad úspěšné odpovědi na ověření:

 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
 }

Odeslání žádosti o oznámení a přijetí odpovědi

Tato část popisuje hlavičky zahrnuté v požadavku HTTP na WNS, aby se zobrazilo oznámení a ty, které jsou součástí odpovědi.

• Odeslat žádost o oznámení
• Odeslat odpověď na oznámení
• Nepodporované funkce HTTP

Odeslat žádost o oznámení

Při odesílání žádosti o oznámení vytvoří volající aplikace požadavek HTTP přes PROTOKOL SSL adresovaný identifikátoru URI (Uniform Resource Identifier). Content-Length je standardní hlavička HTTP, která musí být zadána v požadavku. Všechny ostatní standardní hlavičky jsou volitelné nebo nejsou podporované.

Kromě toho se v žádosti o oznámení dají použít vlastní hlavičky požadavků uvedené tady. Některé hlavičky jsou povinné, zatímco jiné jsou volitelné.

Parametry požadavku

Název záhlaví	Required	Description
Authorization	TRUE	Standardní hlavička autorizace HTTP použitá k ověření žádosti o oznámení. Vaše cloudová služba poskytuje v této hlavičce přístupový token.
Content-Type	TRUE	Standardní autorizační hlavička HTTP. U informačních zpráv, dlaždic a oznámení odznáček musí být tato hlavička nastavená na text/xml. U nezpracovaných oznámení musí být tato hlavička nastavena na application/octet-stream.
Content-Length	TRUE	Standardní autorizační hlavička HTTP, která označuje velikost datové části požadavku.
X-WNS-Type	TRUE	Definuje typ oznámení v datové části: dlaždice, informační zpráva, odznáček nebo nezpracovaný.
X-WNS-Cache-Policy	FALSE	Povolí nebo zakáže ukládání oznámení do mezipaměti. Tato hlavička se vztahuje jenom na dlaždice, indikátory a surová oznámení.
X-WNS-RequestForStatus	FALSE	Vyžádá si stav zařízení a stav připojení WNS v odpovědi na oznámení.
X-WNS-Tag	FALSE	Řetězec použitý k zadání oznámení s identifikačním popiskem, používaný pro dlaždice, které podporují frontu oznámení. Tato hlavička se vztahuje pouze na upozornění panelu.
X-WNS-TTL	FALSE	Celočíselná hodnota vyjádřená v sekundách, která určuje hodnotu TTL (Time to Live).
MS-CV	FALSE	Hodnota vektoru korelace použitá pro váš požadavek.

Důležité poznámky

• Content-Length a Content-Type jsou jediné standardní hlavičky HTTP, které jsou zahrnuté v oznámení doručené klientovi bez ohledu na to, jestli byly do požadavku zahrnuty další standardní hlavičky.
• Všechny ostatní standardní hlavičky HTTP se buď ignorují, nebo vrací chybu, pokud funkce není podporovaná.
• Od února 2023 bude služba WNS ukládat do mezipaměti pouze jedno oznámení týkající se dlaždice, když je zařízení offline.

Authorization

Autorizační hlavička slouží k zadání přihlašovacích údajů volající strany podle metody autorizace OAuth 2.0 pro bearer tokeny.

Syntaxe se skládá z řetězcového literálu "Bearer", následovaného mezerou a poté přístupovým tokenem. Přístupový token se získá prostřednictvím žádosti o přístupový token, jak je uvedeno výše. Stejný přístupový token lze použít pro následné žádosti o oznámení, dokud nevyprší platnost.

Tato hlavička je povinná.

Authorization: Bearer <access-token>

X-WNS-Type

Toto jsou typy oznámení podporované službou WNS. Tato hlavička označuje typ oznámení a způsob, jakým by ho služba WNS měla zpracovat. Jakmile oznámení dorazí ke klientovi, skutečný obsah je ověřován podle zadaného typu. Tato hlavička je povinná.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw

Value	Description
wns/badge	Oznámení pro vytvoření překrytí odznáček na dlaždici Hlavička Content-Type obsažená v požadavku na oznámení musí být nastavena na text/xml.
wns/tile	Upozornění na aktualizaci obsahu dlaždice Hlavička Content-Type obsažená v požadavku na oznámení musí být nastavena na text/xml.
wns/toast	Oznámení o přípitku na klientovi. Hlavička Content-Type obsažená v požadavku na oznámení musí být nastavena na text/xml.
wns/raw	Oznámení, které může obsahovat vlastní datovou část a které se doručí přímo do aplikace. Hlavička Content-Type obsažená v požadavku na oznámení musí být nastavena na application/octet-stream.

X-WNS-Cache-Policy

Když je cílové zařízení oznámení offline, služba WNS uloží do mezipaměti jeden odznáček, jednu dlaždici a jedno informační oznámení pro každý identifikátor URI kanálu. Ve výchozím nastavení se nezpracovaná oznámení neukládají do mezipaměti, ale pokud je povolené ukládání nezpracovaných oznámení do mezipaměti, jedno nezpracované oznámení se ukládá do mezipaměti. Položky se neukládají do mezipaměti po neomezenou dobu a po přiměřené době se vyřadí. Jinak se obsah uložený v mezipaměti doručí, až se zařízení příště připojí do online režimu.

X-WNS-Cache-Policy: cache | no-cache

Value	Description
cache	Default. Pokud je uživatel offline, budou se oznámení ukládat do mezipaměti. Toto je výchozí nastavení pro oznámení o dlaždici a odznaku.
no-cache	Pokud je uživatel offline, oznámení se neupamětí. Toto je výchozí nastavení pro nezpracovaná oznámení.

X-WNS-RequestForStatus

Určuje, jestli má odpověď obsahovat stav zařízení a stav připojení WNS. Tato hlavička je volitelná.

    X-WNS-RequestForStatus: true | false

Value	Description
true	V odpovědi vraťte stav zařízení a stav oznámení.
false	Default. Nevracejte stav zařízení a stav oznámení.

X-WNS-Tag

Přiřadí k oznámení značku popisek. Značka se používá v zásadě nahrazování dlaždice ve frontě oznámení, když aplikace zvolila cyklování oznámení. Pokud již ve frontě existuje oznámení s touto značkou, nové oznámení se stejnou značkou ho nahradí.

Note

Tato hlavička je volitelná a používá se jenom při zasílání hlášení dlaždic.

    X-WNS-Tag: <string value>

Value	Description
řetězcová hodnota	Alfanumerický řetězec maximálně 16 znaků.

X-WNS-TTL

Určuje hodnotu TTL (time expiration) pro oznámení. To obvykle není potřeba, ale můžete ho použít, pokud chcete zajistit, aby se vaše oznámení nezobrazovat později než určitou dobu. Hodnota TTL se zadává v sekundách a je relativní vzhledem k času, kdy služba WNS obdrží požadavek. Po zadání hodnoty TTL se po uplynutí této doby nezobrazí oznámení. Všimněte si, že pokud je hodnota TTL příliš krátká, oznámení se nemusí vůbec zobrazit. Obecně platí, že doba vypršení platnosti se měří alespoň v minutách.

Tato hlavička je volitelná. Pokud není zadána žádná hodnota, oznámení nevyprší a bude nahrazeno v rámci normálního schématu nahrazení oznámení.

X-WNS-TTL: <integer value>

Value	Description
celočíselná hodnota	Doba trvání oznámení v sekundách po obdržení žádosti službou WNS.

X-WNS-SuppressPopup

Note

U aplikací pro Windows Phone Store máte možnost potlačit zobrazení informační zprávy (toast), a místo toho posílat oznámení přímo do centra akcí. Díky tomu můžete oznámení doručovat tiše, což je potenciálně vynikající možnost pro méně naléhavé oznámení. Tato hlavička je volitelná a používá se jenom v kanálech Windows Phone. Pokud tuto hlavičku zahrnete do kanálu Windows, oznámení se zahodí a zobrazí se chybová odpověď ze služby WNS.

X-WNS-SuppressPopup: true | false

Value	Description
true	Odeslání informačního oznámení přímo do centra akcí; nevyvolávejte informační rozhraní.
false	Default. Zvedněte uživatelské rozhraní informační zprávy a přidejte oznámení do centra akcí.

X-WNS-Group

Note

Centrum akcí pro aplikace pro Windows Phone Store může zobrazovat více informačních oznámení se stejnou značkou jenom v případě, že jsou označeny jako patřící do různých skupin. Představte si třeba aplikaci knihy receptu. Každý recept by byl identifikován značkou. Oznámení, které obsahuje komentář k danému receptu, by mělo značku receptu, ale označení skupiny komentářů. Informační zpráva, která obsahuje hodnocení pro tento recept, by znovu měla značku receptu, ale měla by popisek skupiny hodnocení. Tyto různé popisky skupin by umožňovaly, aby se v centru akcí zobrazovala oznámení najednou. Tato hlavička je volitelná.

X-WNS-Group: <string value>

Value	Description
řetězcová hodnota	Alfanumerický řetězec maximálně 16 znaků.

X-WNS-Match

Note

Používá se s metodou HTTP DELETE k odebrání konkrétního oznámení, sady oznámení (podle značky nebo skupiny) nebo všech oznámení z centra akcí pro aplikace pro Windows Phone Store. Toto záhlaví může určovat skupinu, značku nebo obojí. Tato hlavička se vyžaduje v požadavku na oznámení HTTP DELETE. Veškerá datová část, která je součástí této žádosti o oznámení, se ignoruje.

X-WNS-Match: type:wns/toast; group=<string value>; tag=<string value> | type:wns/informační zpráva; group=<string value> | type:wns/informační zpráva; tag=<string value> | type:wns/informační zpráva; všichni

Value	Description
type:wns/informační zpráva; group=<string value>; tag=<string value>	Odeberte jedno oznámení označené zadanou značkou a skupinou.
type:wns/toast; group=<string value>	Odeberte všechna oznámení označená zadanou skupinou.
type:wns/toast; tag=<string value>	Odeberte všechna oznámení označená zadanou značkou.
type:wns/toast;all	Vymažte všechna oznámení vaší aplikace z centra akcí.

Odeslat odpověď na oznámení

Jakmile WNS zpracuje požadavek na oznámení, odešle v odpovědi zprávu HTTP. Tato část popisuje parametry a hlavičky, které najdete v této odpovědi.

Parametry odpovědi

Název záhlaví	Required	Description
X-WNS-Debug-Trace	FALSE	Informace o ladění, které by se měly protokolovat, aby se pomohly vyřešit problémy při hlášení problému.
X-WNS-DeviceConnectionStatus	FALSE	Stav zařízení je vrácen pouze v případě, že je požadován v žádosti o oznámení prostřednictvím hlavičky X-WNS-RequestForStatus.
X-WNS-Error-Description	FALSE	Řetězec chyby čitelný člověkem, který by se měl protokolovat, aby vám pomohl s laděním.
X-WNS-Msg-ID	FALSE	Jedinečný identifikátor oznámení, který se používá pro účely ladění. Při hlášení problému by se tyto informace měly protokolovat, aby vám pomohly při řešení potíží.
X-WNS-Status	FALSE	Určuje, jestli služba WNS úspěšně přijala a zpracovala oznámení. Při hlášení problému by se tyto informace měly protokolovat, aby vám pomohly při řešení potíží.
MS-CV	FALSE	Informace o ladění, které by se měly protokolovat, aby se pomohly vyřešit problémy při hlášení problému.

X-WNS-Debug-Trace

Tato hlavička vrací užitečné ladicí informace ve formě řetězce. Doporučujeme, aby se tato hlavička protokolovala, aby vývojáři mohli ladit problémy. Tato hlavička spolu s hlavičkouMsg-ID X-WNS a MS-CV jsou vyžadována při hlášení problému do služby WNS.

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

Value	Description
řetězcová hodnota	Alfanumerický řetězec.

X-WNS-DeviceConnectionStatus

Tato hlavička vrátí stav zařízení aplikaci volající, pokud je o to požádáno v hlavičce X-WNS-RequestForStatus žádosti o oznámení.

X-WNS-DeviceConnectionStatus: připojeno | odpojeno | tempdisconnected

Value	Description
connected	Zařízení je online a připojené ke službě WNS.
disconnected	Zařízení je offline a není připojené ke službě WNS.
připojeno dočasně (zastaralé)	Zařízení dočasně ztratilo připojení ke službě WNS, například když dojde k ukončení připojení 3G nebo dojde k vyvolání bezdrátového přepínače na přenosném počítači. Platforma klienta oznámení ji vidí jako dočasné přerušení místo úmyslného odpojení.

X-WNS-Error-Description

Tento nadpis poskytuje řetězec chyby čitelný pro člověka, který by se měl uložit do protokolu, aby pomohl při ladění.

X-WNS-Error-Description: <string value>

Value	Description
řetězcová hodnota	Alfanumerický řetězec.

X-WNS-Msg-ID

Tato hlavička slouží k poskytnutí identifikátoru oznámení volajícímu. Doporučujeme, aby se tato hlavička protokolovala, aby vám pomohla s laděním problémů. Tato hlavička spolu s X-WNS-Debug-Trace a MS-CV jsou vyžadovány při hlášení problému do služby WNS.

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

Value	Description
řetězcová hodnota	Alfanumerický řetězec maximálně 16 znaků.

X-WNS-Status

Tato hlavička popisuje, jak služba WNS zpracovávala žádost o oznámení. Můžete ho použít místo interpretace kódů odpovědí jako úspěchu nebo selhání.

X-WNS-Status: přijato | vyřazeno | channelthrottled

Value	Description
received	Oznámení přijal a zpracoval WNS. Poznámka: To nezaručuje, že zařízení obdrželo oznámení.
dropped	Oznámení bylo explicitně ukončeno z důvodu chyby nebo kvůli tomu, že klient tato oznámení explicitně odmítl. Toastové notifikace budou také zrušeny, pokud je zařízení offline.
channelthrottled	Oznámení se zahodilo, protože aplikační server překročil limit rychlosti pro tento konkrétní kanál.

MS-CV

Tato hlavička poskytuje vektor korelace související s požadavkem, který se primárně používá k ladění. Pokud je v rámci požadavku k dispozici CV, WNS tuto hodnotu použije, jinak WNS vygeneruje a vrátí odpověď pomocí CV. Tato hlavička spolu s hlavičkami X-WNS-Debug-Trace a X-WNS-Msg-ID jsou vyžadovány při hlášení problému na WNS.

Important

Pokud poskytujete vlastní CV, vygenerujte prosím nové CV pro každou žádost o nabízené oznámení.

MS-CV: <string value>

Value	Description
řetězcová hodnota	Řídí se standardem vektorů korelace

Kódy odpovědí

Každá zpráva HTTP obsahuje jeden z těchto kódů odpovědí. WNS doporučuje vývojářům protokolovat kód odpovědi pro použití při ladění. Když vývojáři nahlásí problém se službou WNS, musí poskytnout kódy odpovědí a hlavičkové informace.

Kód odpovědi protokolu HTTP	Description	Doporučená akce
200 OK	Oznámení přijal WNS.	Žádné se nevyžadují.
400 – Chybný požadavek	Nejméně jedna hlavička byla zadána nesprávně nebo byla v konfliktu s jinou hlavičkou.	Zapíše podrobnosti o vaší žádosti. Zkontrolujte svou žádost a porovnejte ji s touto dokumentací.
401 Neautorizováno	Cloudová služba nepředložila platný autentizační doklad. Lístek OAuth může být neplatný.	Požádejte o platný přístupový token ověřením cloudové služby pomocí žádosti o přístupový token.
403 Zakázáno	Cloudová služba nemá oprávnění odesílat oznámení na tento identifikátor URI, i když je ověřena.	Přístupový token zadaný v požadavku neodpovídá přihlašovacím údajům aplikace, která požadovala identifikátor URI kanálu. Ujistěte se, že název balíčku v manifestu vaší aplikace odpovídá přihlašovacím údajům cloudové služby zadaným vaší aplikaci na řídicím panelu.
404 Nenalezena	Identifikátor URI kanálu není platný nebo není rozpoznán službou WNS.	Zapíše podrobnosti o vaší žádosti. Neodesílejte do tohoto kanálu další oznámení; oznámení na tuto adresu selžou.
405 Nepovolená metoda	Neplatná metoda (GET, CREATE); Je povolená pouze funkce POST (Windows nebo Windows Phone) nebo DELETE (jenom Windows Phone).	Zapíše podrobnosti o vaší žádosti. Přepněte na příkaz HTTP POST.
406 Není přijatelné	Cloudová služba překročila limit omezení.	Odešlete svůj požadavek poté, co najdete hodnotu hlavičky Retry-After v odpovědi.
410 Zmizelo	Vypršela platnost kanálu.	Zapíše podrobnosti o vaší žádosti. Neposílejte do tohoto kanálu další oznámení. Požádejte aplikaci o nový identifikátor URI kanálu.
Blokovaná doména 410	Služba WNS zablokovala odesílající doménu.	Neposílejte do tohoto kanálu další oznámení. Doména odesílání byla službou WNS zablokována pro zneužívání push oznámení.
413 Entita požadavku je příliš velká	Datová část oznámení překračuje limit velikosti 5 000 bajtů.	Zapíše podrobnosti o vaší žádosti. Zkontrolujte náklad a ujistěte se, že je v rámci omezení velikosti.
500 – Vnitřní chyba serveru	Vnitřní chyba způsobila selhání doručení oznámení.	Zapíše podrobnosti o vaší žádosti. Ohlaste tento problém prostřednictvím vývojářských fór.
503 Služba není k dispozici	Server je momentálně nedostupný.	Zapíše podrobnosti o vaší žádosti. Ohlaste tento problém prostřednictvím vývojářských fór. Pokud je hlavička Retry-After pozorována, odešlete svůj požadavek po hodnotě hlavičky Retry-After v odpovědi.

Nepodporované funkce HTTP

Webové rozhraní WNS podporuje http 1.1, ale nepodporuje následující funkce:

• Chunking
• Pipelining (POST není idempotentní)
• I když je tato podpora podporovaná, vývojáři by měli při odesílání oznámení zakázat funkci Expect-100, protože přináší latenci.