Leküldéses értesítési szolgáltatás kérései és válaszfejlécei (Windows Runtime-alkalmazások)

Ez a témakör a szolgáltatásközi webes API-kat és a leküldéses értesítések küldéséhez szükséges protokollokat ismerteti.

Az Windows Leküldéses Értesítési Szolgáltatások (WNS) áttekintése átfogó képet nyújt a leküldéses értesítésekről, a WNS fogalmairól, követelményeiről és működéséről.

Hozzáférési jogkivonat kérése és fogadása

Ez a szakasz a WNS-sel való hitelesítés során érintett kérés- és válaszparamétereket ismerteti.

Hozzáférési jogkivonat kérése

A rendszer HTTP-kérést küld a WNS-nek a felhőszolgáltatás hitelesítéséhez és egy hozzáférési jogkivonat cserébe történő lekéréséhez. A kérést a Secure Sockets Layer (SSL) használatával bocsátja ki a rendszer https://login.live.com/accesstoken.srf-ra.

Hozzáférési jogkivonat kérési paraméterei

A felhőszolgáltatás ezeket a szükséges paramétereket a HTTP-kérelem törzsében küldi el az "application/x-www-form-urlencoded" formátumban. Győződjön meg arról, hogy az összes paraméter URL-kódolású.

Parameter	Required	Description
grant_type	TRUE	A értéknek client_credentialskell lennie.
client_id	TRUE	Csomagbiztonsági azonosító (SID) a felhőszolgáltatáshoz az alkalmazás Microsoft Store-ban való regisztrálásakor hozzárendelt módon.
client_secret	TRUE	Felhőszolgáltatáshoz használt titkos kulcs, amelyet az alkalmazás Microsoft Store-ban való regisztrálásakor rendeltek hozzá.
hatókör	TRUE	Be kell állítani notify.windows.com-ra

Hozzáférési jogkivonat válasza

A WNS hitelesíti a felhőszolgáltatást, és ha sikeres, egy "200 OK" értékkel válaszol, beleértve a hozzáférési jogkivonatot is. Ellenkező esetben a WNS egy megfelelő HTTP-hibakóddal válaszol az OAuth 2.0 protokolltervezetben leírtak szerint.

Hozzáférési jogkivonat válaszparaméterei

Ha a felhőszolgáltatás sikeresen hitelesítve van, a rendszer egy hozzáférési jogkivonatot ad vissza a HTTP-válaszban. Ez a hozzáférési jogkivonat az értesítési kérelmekben használható, amíg el nem jár. A HTTP-válasz az "application/json" médiatípust használja.

Parameter	Required	Description
access_token	TRUE	A felhőszolgáltatás által az értesítés küldésekor használt hozzáférési jogkivonat.
token_type	FALSE	Mindig visszaadja mint bearer.

Válaszkód

HTTP-válaszkód	Description
200 OK	A kérés sikeres volt.
400 Hibás kérés	A hitelesítés nem sikerült. A válaszparamétereket az OAuth megjegyzéskérelem-tervezetében (RFC) tekintheti meg.

Example

Az alábbi példában egy sikeres hitelesítési válasz látható:

 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
 }

Értesítési kérelem küldése és válasz fogadása

Ez a szakasz a WNS-nek küldött HTTP-kérés fejléceit és a válaszban részt vevőket ismerteti.

• Értesítési kérelem küldése
• Értesítési válasz küldése
• Nem támogatott HTTP-szolgáltatások

Értesítési kérelem küldése

Értesítési kérés küldésekor a hívó alkalmazás SSL-en keresztül http-kérést küld, amelyet a csatorna egységes erőforrás-azonosítójának (URI) címez. A "Content-Length" egy szabványos HTTP-fejléc, amelyet meg kell adni a kérelemben. Az összes többi normál fejléc nem kötelező, vagy nem támogatott.

Emellett az itt felsorolt egyéni kérésfejlécek használhatók az értesítési kérelemben. Egyes fejlécekre szükség van, míg mások nem kötelezőek.

Kérelemparaméterek

Címsor neve	Required	Description
Authorization	TRUE	Az értesítési kérelem hitelesítéséhez használt szabványos HTTP-engedélyezési fejléc. A felhőszolgáltatás ebben a fejlécben biztosítja a hozzáférési jogkivonatát.
Content-Type	TRUE	Szabványos HTTP-engedélyezési fejléc. Toast-, csempe- és jelvényértesítésekhez a fejlécet text/xml-re kell állítani. Nyers értesítések esetén ezt a fejlécet application/octet-streama következőre kell állítani: .
Content-Length	TRUE	Szabványos HTTP-engedélyezési fejléc a kérelem hasznos adatméretének jelöléséhez.
X-WNS-Type	TRUE	Meghatározza az értesítés típusát a terhelésben: "csempe", "toast", "jelvény" vagy "nyers".
X-WNS-Cache-Policy	FALSE	Engedélyezi vagy letiltja az értesítések gyorsítótárazását. Ez a fejléc csak csempékre, jelvényekre és nyers értesítésekre vonatkozik.
X-WNS-RequestForStatus	FALSE	Az értesítési válaszban kéri az eszköz állapotát és a WNS-kapcsolat állapotát.
X-WNS-Tag	FALSE	Értesítési sorokat támogató csempékhez azonosító címkével ellátott karakterlánc. Ez a fejléc csak a csempeértesítésekre vonatkozik.
X-WNS-TTL	FALSE	Másodpercben kifejezett egész szám, amely megadja az élettartamot (TTL).
MS-CV	FALSE	A kérésedhez használt korrelációs vektor értéke.

Fontos megjegyzések

• A Content-Length és a Content-Type az egyetlen szabványos HTTP-fejléc, amely szerepel az ügyfélnek küldött értesítésben, függetlenül attól, hogy a kérés tartalmazott-e más szabványos fejléceket.
• A rendszer figyelmen kívül hagyja az összes többi szabványos HTTP-fejlécet, vagy hibát ad vissza, ha a funkció nem támogatott.
• 2023 februárjától kezdve a WNS csak egy csempeértesítést gyorsítótáraz, ha az eszköz offline állapotban van.

Authorization

Az engedélyezési fejléc a hívó fél hitelesítő adatainak megadására szolgál, a OAuth 2.0 engedélyezési módszert követve a hozzáférési jogkivonatok esetében.

A szintaxis egy "Bearer" sztringből, majd egy szóközből, majd a hozzáférési tokenből áll. Ezt a hozzáférési jogkivonatot a rendszer a fent ismertetett hozzáférési jogkivonat-kérés kiadásával kéri le. Ugyanez a hozzáférési jogkivonat használható a későbbi értesítési kérelmekben, amíg el nem jár.

Erre a fejlécre van szükség.

Authorization: Bearer <access-token>

X-WNS-Type

Ezek a WNS által támogatott értesítéstípusok. Ez a fejléc jelzi az értesítés típusát és azt, hogy a WNS hogyan kezelje azt. Miután az értesítés elérte az ügyfelet, a rendszer a tényleges hasznos adatokat ezzel a megadott típussal ellenőrzi. Erre a fejlécre van szükség.

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

Value	Description
wns/badge	Értesítés a jelvény átfedésének a csempén való létrehozásáról. Az értesítési kérelemben szereplő Tartalomtípus fejlécet be kell állítani text/xml.
wns/tile	Értesítés a csempe tartalmának frissítéséről. Az értesítési kérelemben szereplő Tartalomtípus fejlécet be kell állítani text/xml.
wns/toast	Értesítés a kliens tiszteletére tartott koccintásról. Az értesítési kérelemben szereplő Tartalomtípus fejlécet be kell állítani text/xml.
wns/raw	Az értesítés, amely egyéni adatokat tartalmaz, és közvetlenül az alkalmazáshoz van kézbesítve. Az értesítési kérelemben szereplő Tartalomtípus fejlécet be kell állítani application/octet-stream.

X-WNS-Cache-Policy

Ha az értesítési céleszköz offline állapotban van, a WNS egy jelvényt, egy csempét és egy bejelentési értesítést fog gyorsítótárba helyezni az egyes csatornák URI-jaihoz. Alapértelmezés szerint a nyers értesítések nem gyorsítótárazva vannak, de ha a nyers értesítések gyorsítótárazása engedélyezve van, egy nyers értesítés gyorsítótárazva lesz. Az elemek nem maradnak határozatlan ideig a gyorsítótárban, és ésszerű idő elteltével el lesznek dobva. Ellenkező esetben a gyorsítótárazott tartalom akkor lesz kézbesítve, amikor az eszköz legközelebb online állapotba kerül.

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

Value	Description
gyorsítótár	Default. Az értesítések gyorsítótárazva lesznek, ha a felhasználó offline állapotban van. Ez a csempe- és jelvényértesítések alapértelmezett beállítása.
no-cache	Az értesítés nem lesz gyorsítótárazva, ha a felhasználó offline állapotban van. Ez a nyers értesítések alapértelmezett beállítása.

X-WNS-RequestForStatus

Megadja, hogy a válasznak tartalmaznia kell-e az eszköz állapotát és a WNS kapcsolati állapotát. Ez a fejléc nem kötelező.

    X-WNS-RequestForStatus: true | false

Value	Description
true	Adja vissza az eszköz állapotát és az értesítés állapotát a válaszban.
false	Default. Ne adja vissza az eszköz állapotát és az értesítési állapotot.

X-WNS-Tag

Címkecímkét rendel egy értesítéshez. A címke az értesítési sor csempéjének cserepolitikájában használatos, amikor az alkalmazás értesítési körforgást választott. Ha már létezik ilyen címkével ellátott értesítés az üzenetsorban, egy új, ugyanazzal a címkével ellátott értesítés kerül a helyére.

Note

Ez a fejléc nem kötelező, és csak csempeértesítések küldésekor használható.

    X-WNS-Tag: <string value>

Value	Description
karakterláncérték	Legfeljebb 16 karakter hosszúságú alfanumerikus karakterlánc.

X-WNS-TTL

Az értesítés TTL-jének (lejárati ideje) megadása. Ez általában nem szükséges, de akkor használható, ha meg szeretné győződni arról, hogy az értesítések nem jelennek meg egy adott időpontnál később. A TTL másodpercben van megadva, és ahhoz az időponthoz képest van, amikor a WNS megkapja a kérést. TTL megadása után az eszköz nem jeleníti meg az értesítést. Vegye figyelembe, hogy ez azt eredményezheti, hogy az értesítés egyáltalán nem jelenik meg, ha a TTL túl rövid. A lejárati idő általában legalább perc alatt meg lesz mérve.

Ez a fejléc nem kötelező. Ha nincs megadva érték, az értesítés nem jár le, és a normál értesítés-csere sémában lesz lecserélve.

X-WNS-TTL: <integer value>

Value	Description
egész számérték	Az értesítés élettartama másodpercben, miután a WNS megkapta a kérést.

X-WNS-SuppressPopup

Note

Windows Phone Áruház alkalmazásaiban elnémíthatja a toast értesítés felhasználói felületét, ehelyett az értesítést közvetlenül a műveletközpontba küldheti. Ez lehetővé teszi az értesítés csendes kézbesítését, ami a kevésbé sürgős értesítések potenciálisan kiváló lehetősége. Ez a fejléc nem kötelező, és csak Windows Phone-csatornákon használható. Ha ezt a fejlécet egy Windows-csatornán adja meg, a rendszer elveti az értesítést, és hibaüzenetet kap a WNS-től.

X-WNS-SuppressPopup: true | téves

Value	Description
true	Küldje el a toast értesítést közvetlenül az Értesítési központba; ne jelenítse meg a toast felhasználói felületét.
false	Default. Emelje fel a bejelentés felhasználói felületét, és vegye fel az értesítést a műveletközpontba.

X-WNS-Group

Note

A Windows Phone Áruházbeli alkalmazások műveletközpontja csak akkor jeleníthet meg több bejelentési értesítést ugyanazzal a címkével, ha különböző csoportokhoz tartozóként vannak megjelölve. Vegyük például egy receptkönyv-alkalmazást. Minden receptet egy címke azonosít. Egy pirítós, amely megjegyzést tartalmaz a recepthez, rendelkezne a recept címkéjével, de egy megjegyzéscsoport címkével. Az a pirítós, amely tartalmazza annak a receptnek a minősítését, ismét viselné a recept címkéjét, de lenne rajta egy minősítési csoport címke is. Ezek a különböző csoportfeliratok lehetővé tennék, hogy mindkét toast értesítés egyszerre jelenjen meg a műveletközpontban. Ez a fejléc nem kötelező.

X-WNS-Csoport: <string value>

Value	Description
karakterlánc érték	Legfeljebb 16 karakter hosszúságú alfanumerikus karakterlánc.

X-WNS-Match

Note

HTTP DELETE metódussal eltávolíthat egy adott értesítést, értesítések halmazát (címke vagy csoport alapján), vagy az összes értesítést a Windows Phone Áruház alkalmazásainak műveletközpontjából. Ez a fejléc megadhat egy csoportot, egy címkét vagy mindkettőt. Ez a fejléc egy HTTP DELETE értesítési kérelemben szükséges. Az értesítési kérelemben szereplő hasznos adatok figyelmen kívül lesznek hagyva.

X-WNS-Match: típus:wns/toast;group=<string value>; tag=<string value> | típus:wns/toast;group=<string value> | típus:wns/toast;tag=<string value> | típus:wns/toast;all

Value	Description
típus:wns/toast; group=<string value>; tag=<string value>	Távolítsa el a megadott címkével és csoporttal címkézett egyetlen értesítést.
típus:wns/pirítós; group=<string value>	Távolítsa el a megadott csoporttal címkézett összes értesítést.
típus:wns/pirítós; tag=<string value>	Távolítsa el a megadott címkével jelölt összes értesítést.
type:wns/toast;all	Törölje az alkalmazás összes értesítését a műveletközpontból.

Értesítési válasz küldése

Miután a WNS feldolgozta az értesítési kérelmet, egy HTTP-üzenetet küld válaszként. Ez a szakasz az adott válaszban található paramétereket és fejléceket ismerteti.

Válaszparaméterek

Címsor neve	Required	Description
X-WNS-Debug-Trace	FALSE	Hibakeresési információk, amelyeket naplózni kell a probléma bejelentésekor felmerülő problémák elhárításához.
X-WNS-DeviceConnectionStatus	FALSE	Az eszköz állapota csak akkor kerül visszaadásra, ha a kérést az értesítési kérésben az X-WNS-RequestForStatus fejlécen keresztül kérik.
X-WNS-Error-Description	FALSE	Egy emberi olvasásra alkalmas hibasztring, amelyet naplózni kell a hibakereséshez.
X-WNS-Msg-ID	FALSE	Az értesítés egyedi azonosítója, amelyet hibakeresési célokra használnak. Probléma bejelentésekor ezeket az információkat naplózni kell, hogy segítsenek a hibaelhárításban.
X-WNS-Status	FALSE	Jelzi, hogy a WNS sikeresen megkapta-e és feldolgozta-e az értesítést. Probléma bejelentésekor ezeket az információkat naplózni kell, hogy segítsenek a hibaelhárításban.
MS-CV	FALSE	Hibakeresési információk, amelyeket naplózni kell a probléma bejelentésekor felmerülő problémák elhárításához.

X-WNS-Debug-Trace

Ez a fejléc sztringként hasznos hibakeresési információkat ad vissza. Javasoljuk, hogy ezt a fejlécet naplózza, hogy segítsen a fejlesztőknek a hibák elhárításában. Ez a fejléc az X-WNS-Msg-ID fejlécmel és az MS-CV-vel együtt szükséges, amikor problémát jelent a WNS-nek.

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

Value	Description
karakterlánc érték	Alfanumerikus karakterlánc.

X-WNS-DeviceConnectionStatus

Ez a fejléc visszaadja az eszköz állapotát a hívó alkalmazásnak, ha azt az értesítési kérelem X-WNS-RequestForStatus fejlécében kérték.

X-WNS-DeviceConnectionStatus: csatlakoztatva | leválasztva | ideiglenesen leválasztva

Value	Description
connected	Az eszköz online állapotban van, és csatlakozik a WNS-hez.
disconnected	Az eszköz offline állapotban van, és nem csatlakozik a WNS-hez.
tempconnected (elavult)	Az eszköz átmenetileg megszakadt a kapcsolat a WNS-sel, például 3G-kapcsolat megszakadásakor vagy a laptop vezeték nélküli kapcsolójának eldobásakor. Az értesítési kliensplatform átmeneti megszakításnak tekinti, nem pedig szándékos leválasztásnak.

X-WNS-Error-Description

Ez a fejléc egy emberi olvasásra alkalmas hibasztringet biztosít, amelyet naplózni kell a hibakereséshez.

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

Value	Description
karakterlánc érték	Alfanumerikus karakterlánc.

X-WNS-Msg-ID

Ez a fejléc az értesítés azonosítójának megadására szolgál a hívó számára. Javasoljuk, hogy ezt a fejlécet naplózza a hibakereséshez. Ez a fejléc az X-WNS-Debug-Trace és az MS-CV-vel együtt szükséges, amikor problémát jelent a WNS-nek.

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

Value	Description
sztringérték	Legfeljebb 16 karakter hosszúságú alfanumerikus karakterlánc.

X-WNS-Status

Ez a fejléc azt ismerteti, hogy a WNS hogyan kezelte az értesítési kérelmet. Ez a válaszkódok sikeres vagy sikertelen értelmezése helyett használható.

X-WNS-Status: megkapva | elvetve | csatorna korlátozva

Value	Description
received	Az értesítést a WNS kapta és feldolgozta. Megjegyzés: Ez nem garantálja, hogy az eszköz megkapta az értesítést.
dropped	Az értesítés kifejezetten elvetve lett egy hiba miatt, vagy mert az ügyfél kifejezetten elutasította ezeket az értesítéseket. A toast értesítések akkor is elmaradnak, ha az eszköz offline állapotban van.
channelthrottled	Az értesítés elvetve, mert az alkalmazáskiszolgáló túllépte az adott csatorna sebességkorlátját.

MS-CV

Ez a fejléc a kérelemhez kapcsolódó korrelációs vektort biztosít, amelyet elsősorban hibakeresésre használnak. Ha a kérelem részeként cv-t ad meg, akkor a WNS ezt az értéket fogja használni, különben a WNS létrehoz és válaszol egy cv-vel. Ez a fejléc az X-WNS-Debug-Trace és az X-WNS-Msg-ID fejléccel együtt szükséges, amikor problémát jelent a WNS-hez.

Important

Ha saját cv-t ad meg, minden leküldéses értesítési kérelemhez hozzon létre egy új cv-t.

MS-CV: <string value>

Value	Description
karakterlánc érték	A korrelációs vektor szabványt követi

Válaszkódok

Minden HTTP-üzenet ezen válaszkódok egyikét tartalmazza. A WNS azt javasolja, hogy a fejlesztők a hibakereséshez használva naplózják a válaszkódot. Amikor a fejlesztők hibát jelentenek a WNS-nek, válaszkódokat és fejlécadatokat kell megadniuk.

HTTP-válaszkód	Description	Javasolt művelet
200 OK	Az értesítést a WNS elfogadta.	Nincs szükség.
400 Hibás kérés	Egy vagy több fejléc helytelenül lett megadva, vagy ütközik egy másik fejlécmel.	Naplózza a kérés részleteit. Vizsgálja meg a kérelmet, és hasonlítsa össze ezt a dokumentációt.
401 Nem engedélyezett	A felhőszolgáltatás nem adott meg érvényes hitelesítési jegyet. Az OAuth-jegy érvénytelen lehet.	Kérjen érvényes hozzáférési jogkivonatot a felhőszolgáltatás hitelesítése által, a hozzáférési jogkivonat kérvényezésével.
403 – Hozzáférés megtagadva	A felhőszolgáltatás nem jogosult arra, hogy értesítést küldjön ennek az URI-nak annak ellenére, hogy hitelesítették őket.	A kérelemben megadott hozzáférési jogkivonat nem egyezik meg a csatorna URI-t kérő alkalmazás hitelesítő adataival. Győződjön meg arról, hogy az alkalmazás jegyzékfájljában szereplő csomagnév megegyezik az alkalmazásnak az irányítópulton megadott felhőszolgáltatás hitelesítő adataival.
404 Nem található	A csatorna URI-ja érvénytelen, vagy a WNS nem ismeri fel.	Naplózza a kérés részleteit. Ne küldjön további értesítéseket erre a csatornára; az erre a címre történő értesítések sikertelenek lesznek.
A 405-ös metódus nem engedélyezett	Érvénytelen metódus (GET, CREATE); csak a POST (Windows vagy Windows Phone) vagy a DELETE (csak Windows Phone) engedélyezett.	Naplózza a kérés részleteit. Váltson a HTTP POST használatára.
406 Nem elfogadható	A felhőszolgáltatás túllépte a szabályozási korlátot.	Küldje el a kérést a válaszban szereplő Retry-After fejlécérték után
410 Eltűnt	A csatorna lejárt.	Naplózza a kérés részleteit. Ne küldjön további értesítéseket erre a csatornára. Kérje meg az alkalmazást, hogy kérjen új csatorna URI-t.
410 Tartomány blokkolva	A küldő tartományt a WNS letiltotta.	Ne küldjön további értesítéseket erre a csatornára. A küldő tartományt a WNS letiltotta a leküldéses értesítések használata miatt.
413 Kérelem entitás túl nagy	Az értesítés terjedelme túllépi az 5000 bájtos méretkorlátot.	Naplózza a kérés részleteit. Ellenőrizze a teher méretét, hogy az a méretkorlátozásokon belül legyen.
500 belső kiszolgálóhiba	Egy belső hiba miatt az értesítés kézbesítése meghiúsult.	Naplózza a kérés részleteit. A probléma bejelentése a fejlesztői fórumokon keresztül.
503 A szolgáltatás nem érhető el	A kiszolgáló jelenleg nem érhető el.	Naplózza a kérés részleteit. A probléma bejelentése a fejlesztői fórumokon keresztül. Ha észlelték a Retry-After fejlécet, akkor kérjük, küldje el a kérését a válasz Retry-After fejlécértéke után.

Nem támogatott HTTP-szolgáltatások

A WNS webes felület támogatja a HTTP 1.1-et, de nem támogatja a következő funkciókat:

• Chunking
• Csőhálózat (a POST nem idempotens)
• Bár támogatott, a fejlesztőknek le kell tiltani a Expect-100-et, mivel ez késést eredményez az értesítések küldésekor.