Anforderungs- und Antwortheader des Pushbenachrichtigungsdiensts (Windows-Runtime-Apps)

[ Dieser Artikel richtet sich an Windows 8.x- und Windows Phone 8.x-Entwickler, die Windows-Runtime-Apps schreiben. Wenn Sie für Windows 10 entwickeln, finden Sie weitere Informationen unter neueste Dokumentation]

In diesem Thema werden die Dienst-zu-Dienst-Web-APIs und -Protokolle beschrieben, die zum Senden einer Pushbenachrichtigung erforderlich sind.

Informationen zum Konzept von Pushbenachrichtigungen sowie zu Konzepten, Anforderungen und zur Verwendung von WNS finden Sie unter Übersicht über den Windows-Pushbenachrichtigungsdienst (Windows Push Notification Service, WNS).

Anfordern und Erhalten eines Zugriffstokens

In diesem Abschnitt werden die Anforderungs- und Antwortparameter für die Authentifizierung bei WNS beschrieben.

Zugriffstokenanforderung

Es wird eine HTTP-Anforderung an WNS gesendet, um den Clouddienst zu authentifizieren und im Gegenzug ein Zugriffstoken abzurufen. Die Anforderung wird mithilfe von SSL (Secure Sockets Layer) für den folgenden vollqualifizierten Domänennamen (Fully Qualified Domain Name, FQDN) ausgestellt.

https://login.live.com/accesstoken.srf

Parameter für die Zugriffstokenanforderung

Der Clouddienst übermittelt diese erforderlichen Parameter mithilfe des Formats "application/x-www-form-urlencoded" im HTTP-Anforderungstext. Sie müssen sicherstellen, dass alle Parameter URL-codiert sind.

Zugriffstokenantwort

Der Clouddienst wird von WNS authentifiziert, und wenn dies erfolgreich war, wird mit "200 OK", einschließlich des Zugriffstokens, geantwortet. Andernfalls wird von WNS wie im OAuth 2.0-Protokollentwurf beschrieben mit einem HTTP-Fehlercode geantwortet.

Parameter für die Zugriffstokenantwort

In der HTTP-Antwort wird ein Zugriffstoken zurückgegeben, wenn der Clouddienst erfolgreich authentifiziert wurde. Dieses Zugriffstoken kann in Benachrichtigungsanforderungen verwendet werden, bis es abläuft. Die HTTP-Antwort verwendet den Medientyp "application/json".

Antwortcode

Beispiel

Nachfolgend ist ein Beispiel einer erfolgreichen Authentifizierungsantwort dargestellt:

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer"
 }

Senden einer Benachrichtigungsanforderung und Erhalten einer Antwort

In diesem Abschnitt werden die an einer HTTP-Anforderung an WNS zum Bereitstellen einer Benachrichtigung und die an der Antwort beteiligten Header beschrieben.

• Senden einer Benachrichtigungsanforderung
• Senden einer Benachrichtigungsantwort
• Nicht unterstützte HTTP-Features

Senden einer Benachrichtigungsanforderung

Beim Senden einer Benachrichtigungsanforderung nimmt die aufrufende App eine HTTP-Anforderung über SSL vor, die an den URI (Uniform Resource Identifier) gerichtet wird. "Content-Length" ist ein HTTP-Standardheader, der in der Anforderung angegeben werden muss. Alle anderen Standardheader sind optional oder werden nicht unterstützt.

Außerdem können die hier aufgeführten benutzerdefinierten Anforderungsheader in der Benachrichtigungsanforderung verwendet werden. Einige Header sind erforderlich, während andere optional sind.

Anforderungsparameter

Wichtige Hinweise

• "Content-Length" und "Content-Type" sind die einzigen HTTP-Standardheader, die in der dem Client bereitgestellten Benachrichtigung enthalten sind. Dabei spielt es keine Rolle, ob andere Standardheader in die Anforderung eingefügt wurden.
• Alle anderen HTTP-Standardheader werden ignoriert oder geben einen Fehler zurück, wenn die Funktionalität nicht unterstützt wird.

Authorization

Der Autorisierungsheader wird gemäß der OAuth 2.0-Autorisierungsmethode für bearer-Token zum Angeben der Anmeldeinformationen der aufrufenden Partei verwendet.

Die Syntax besteht aus einem Zeichenfolgenliteral "Bearer", gefolgt von einem Leerzeichen, auf das Ihr Zugriffstoken folgt. Dieses Zugriffstoken wird durch Ausgeben der oben beschriebenen Zugriffstokenanforderung abgerufen. Dasselbe Zugriffstoken kann für nachfolgende Benachrichtigungsanforderungen verwendet werden, bis es abläuft.

Dieser Header ist erforderlich.

Authorization: Bearer <access-token>

X-WNS-Type

Dies sind die von WNS unterstützten Benachrichtigungstypen. Dieser Header gibt den Benachrichtigungstyp und die Art an, wie dieser von WNS verarbeitet werden soll. Nachdem die Benachrichtigung den Client erreicht hat, wird die tatsächliche Nutzlast anhand des angegebenen Typs überprüft. Dieser Header ist erforderlich.

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

X-WNS-Cache-Policy

Wenn das Benachrichtigungszielgerät offline ist, werden von WNS eine Signal- und eine Kachelbenachrichtigung pro App zwischengespeichert. Wenn der Benachrichtigungszyklus für die App aktiviert ist, werden von WNS bis zu fünf Kachelbenachrichtigungen zwischengespeichert. Standardmäßig werden unformatierte Benachrichtigungen nicht zwischengespeichert. Wenn jedoch die Zwischenspeicherung unformatierter Benachrichtigungen aktiviert ist, wird eine unformatierte Benachrichtigung zwischengespeichert. Elemente werden nicht dauerhaft im Cache beibehalten, sondern nach einem angemessenen Zeitraum gelöscht. Andernfalls wird der zwischengespeicherte Inhalt bereitgestellt, wenn das Gerät das nächste Mal online ist.

Dieser Header ist optional und sollte nur in Fällen verwendet werden, in denen der Clouddienst das standardmäßige Verhalten beim Zwischenspeichern außer Kraft setzen möchte.

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

X-WNS-RequestForStatus

Gibt an, ob die Antwort den Gerätestatus und den WNS-Verbindungsstatus enthalten soll. Dieser Header ist optional.

X-WNS-RequestForStatus: true | false

X-WNS-Tag

Weist einer Benachrichtigung eine tag-Bezeichnung zu. Das Tag wird in der Ersetzungsrichtlinie der Kachel in der Benachrichtigungswarteschlange verwendet, wenn für die App der Benachrichtigungszyklus ausgewählt wurde. Wenn in der Warteschlange bereits eine Benachrichtigung mit diesem Tag vorhanden ist, nimmt eine neue Benachrichtigung mit demselben Tag ihren Platz ein.

Hinweis  Dieser Header ist optional und wird nur beim Senden von Kachelbenachrichtigungen verwendet.

Hinweis  Für Windows Phone Store-Apps kann der X-WNS-Tag-Header mit dem X-WNS-Group-Header verwendet werden, damit im Info-Center mehrere Benachrichtigungen mit dem gleichen Tag angezeigt werden können.

X-WNS-Tag: <string value>

X-WNS-TTL

Gibt die TTL (Ablaufzeit) für eine Benachrichtigung an. Dies ist in der Regel nicht erforderlich, kann aber verwendet werden, wenn Sie sicherstellen möchten, dass Ihre Benachrichtigungen nach einem bestimmten Zeitpunkt nicht mehr angezeigt werden. Die Gültigkeitsdauer wird in Sekunden angegeben und ist relativ zur Zeit, in der WNS die Anforderung erhält. Wenn eine Gültigkeitsdauer angegeben ist, wird die Benachrichtigung vom Gerät nur für den bestimmten Zeitraum angezeigt. Beachten Sie, dass die Benachrichtigung möglicherweise nie angezeigt wird, wenn die Gültigkeitsdauer zu kurz ist. Im Allgemeinen wird eine Ablaufzeit mindestens in Minuten gemessen.

Dieser Header ist optional. Wenn kein Wert angegeben ist, läuft die Benachrichtigung nicht ab und wird gemäß dem normalen Ersetzungsschema für Benachrichtigungen ersetzt.

X-WNS-TTL: <integer value>

X-WNS-SuppressPopup

Hinweis  Für Windows Phone Store-Apps können Sie die UI einer Popupbenachrichtigung unterdrücken, anstatt die Benachrichtigung direkt an das Info-Center zu senden. Auf diese Weise kann die Benachrichtigung stillschweigend übermittelt werden, was bei weniger dringenden Benachrichtigungen möglicherweise die bessere Wahl ist. Dieser Header ist optional und wird nur für Windows Phone-Kanäle verwendet. Wenn Sie diesen Header für einen Windows-Kanal angeben, wird die Benachrichtigung verworfen, und Sie erhalten eine Fehlerantwort von WNS.

X-WNS-SuppressPopup: true | false

X-WNS-Group

Hinweis  Das Info-Center für Windows Phone Store-Apps kann nur dann mehrere Popupbenachrichtigungen mit dem gleichen Tag anzeigen, wenn aus ihren Bezeichnungen hervorgeht, dass sie zu verschiedenen Gruppen gehören. Stellen Sie sich z. B. eine Kochbuch-App vor. Jedes Rezept wird durch ein Tag identifiziert. Ein Popup mit einem Kommentar zu einem Rezept ist zwar mit dem Tag des Rezepts, aber mit einer Gruppenbezeichnung für Kommentare versehen. Ein Popup mit einer Bewertung des Rezepts wäre ebenfalls mit dem Tag des Rezepts, aber mit einer Gruppenbezeichnung für Bewertungen versehen. Aufgrund dieser unterschiedlichen Gruppenbezeichnungen können beide Popupbenachrichtigungen gleichzeitig im Info-Center angezeigt werden. Dieser Header ist optional.

X-WNS-Group: <string value>

X-WNS-Match

Hinweis  Wird mit der HTTP DELETE-Methode verwendet, um ein bestimmtes Popup, eine Reihe von Popups (anhand des Tags oder der Gruppe) oder alle Popups aus dem Info-Center für Windows Phone Store-Apps zu entfernen. Dieser Header kann eine Gruppe und/oder ein Tag angeben. Dieser Header ist in einer HTTP DELETE-Benachrichtigungsanforderung erforderlich. In dieser Benachrichtigungsanforderung enthaltene Nutzlasten werden ignoriert.

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

Senden einer Benachrichtigungsantwort

Nachdem die Benachrichtigungsanforderung von WNS verarbeitet wurde, wird eine HTTP-Nachricht als Antwort gesendet. In diesem Abschnitt werden die Parameter und Header erläutert, die in dieser Antwort enthalten sein können.

Antwortparameter

X-WNS-Debug-Trace

Dieser Header gibt hilfreiche Debuginformationen als Zeichenfolge zurück. Wir empfehlen, diesen Header zu protokollieren, um Entwicklern beim Debuggen von Problemen zu helfen. Dieser Header ist zusammen mit dem Header "X-WNS-Msg-ID" erforderlich, wenn WNS ein Problem gemeldet wird.

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

X-WNS-DeviceConnectionStatus

Dieser Header gibt den Gerätestatus an die aufrufende Anwendung zurück, wenn dies im X-WNS-RequestForStatus-Header der Benachrichtigungsanforderung angefordert wird.

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

X-WNS-Error-Description

Dieser Header stellt eine für den Benutzer lesbare Fehlerzeichenfolge bereit, die für das Debuggen protokolliert werden sollte.

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

X-WNS-Msg-ID

Mit diesem Header wird dem Aufrufer eine ID für die Benachrichtigung bereitgestellt. Wir empfehlen, diesen Header zu protokollieren, um beim Debuggen von Problemen zu helfen. Dieser Header ist zusammen mit dem Header "X-WNS-Debug-Trace" erforderlich, wenn WNS ein Problem gemeldet wird.

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

X-WNS-Status

Dieser Header beschreibt, wie die Benachrichtigungsanforderung von WNS verarbeitet wurde. Er kann anstatt des Interpretierens von Antwortcodes als Erfolg oder Fehler verwendet werden.

X-WNS-Status: received | dropped | channelthrottled

Antwortcodes

Jede HTTP-Nachricht enthält einen dieser Antwortcodes. WNS empfiehlt, dass Entwickler den Antwortcode zur Verwendung beim Debuggen protokollieren Wenn Entwickler WNS ein Problem melden, müssen sie Antwortcodes und Headerinformationen angeben.

Ausführliche Problembehandlungsinformationen zu bestimmten Antwortcodes finden Sie unter Problembehandlung für Kachel-, Popup- und Signalbenachrichtigungen. Weitere Informationen finden Sie zudem unter COM Error Codes (WPN, MBN, P2P, Bluetooth).

Nicht unterstützte HTTP-Features

Die WNS-Weboberfläche unterstützt HTTP 1.1, jedoch nicht die folgenden Features:

• Blockerstellung
• Pipelining (POST ist nicht idempotent)
• Obwohl es unterstützt wird, sollten Entwickler "Expect-100" deaktivieren, da dies beim Senden einer Benachrichtigung zu Wartezeiten führen kann.

Verwandte Themen

Schnellstart: Senden einer Pushbenachrichtigung

Richtlinien und Prüfliste für Pushbenachrichtigungen

So wird's gemacht: Authentifizieren mit dem Windows-Pushbenachrichtigungsdienst (Windows Push Notification Service, WNS)

So wird's gemacht: Anfordern, Erstellen und Speichern eines Benachrichtigungskanals

Beispiel für Pushbenachrichtigungen und regelmäßige Benachrichtigungen

Übersicht über WNS