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

In diesem Thema werden die zwischen Web-APIs und Protokolle benötigten Dienste beschrieben, um Pushbenachrichtigungen zu senden.

In der Übersicht über die Windows-Pushbenachrichtigungsdienste (Windows Push Notification Services, WNS) werden die Konzepte, die Anforderungen und die Funktionsweise von Pushbenachrichtigungen und WNS erörtert.

Anfordern und Empfangen eines Zugriffstokens

In diesem Abschnitt werden die Anforderungs- und Antwortparameter im Zusammenhang mit der Authentifizierung bei WNS beschrieben.

Access token request (Zugriffstokenanforderung)

Eine HTTP-Anforderung wird an WNS gesendet, um den Clouddienst zu authentifizieren und im Gegenzug ein Zugriffstoken abzurufen. Die Anforderung wird über SSL (Secure Sockets Layer) an https://login.live.com/accesstoken.srf ausgegeben.

Zugriffstoken-Anforderungsparameter

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

Zugriffstokenantwort

WNS authentifiziert den Clouddienst und antwortet bei Erfolg mit „200 – OK“, einschließlich des Zugriffstokens. Andernfalls antwortet WNS mit einem passenden HTTP-Fehlercode, wie im OAuth 2.0-Protokollentwurf beschrieben.

Zugriffstoken-Antwortparameter

Ein Zugriffstoken wird in der HTTP-Antwort 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

Es folgt ein Beispiel für eine erfolgreiche Authentifizierungsantwort:

 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
 }

Senden einer Benachrichtigungsanforderung und Empfangen einer Antwort

In diesem Abschnitt werden die Header beschrieben, die bei einer HTTP-Anforderung an WNS zur Übermittlung einer Benachrichtigung verwendet werden, sowie die in der Antwort vorkommenden Header.

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

Senden einer Benachrichtigungsanforderung

Beim Senden einer Benachrichtigungsanforderung übermittelt die aufrufende App eine HTTP-Anforderung per SSL, die an den Uniform Resource Identifier (URI) des Kanals gerichtet ist. „Content-Length“ ist ein HTTP-Standardheader, der in der Anforderung angegeben werden muss. Alle weiteren Standardheader sind entweder optional oder werden nicht unterstützt.

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

Anforderungsparameter

Wichtige Hinweise

• „Content-Length“ und „Content-Type“ werden als einzige HTTP-Standardheader in die an den Client übermittelte Benachrichtigung aufgenommen. Dies gilt unabhängig davon, ob andere Standardheader in der Anforderung enthalten waren.
• Alle weiteren HTTP-Standardheader werden entweder ignoriert oder geben einen Fehler zurück, wenn die Funktionalität nicht unterstützt wird.
• Ab Februar 2023 speichert WNS nur noch eine Kachelbenachrichtigung zwischen, wenn das Gerät offline ist.

Autorisierung

Der Autorisierungsheader wird verwendet, um die Anmeldeinformationen des Aufrufers gemäß OAuth 2.0-Autorisierungsmethode für Bearertoken anzugeben.

Die Syntax umfasst ein Zeichenfolgenliteral „Bearer“, gefolgt von einem Leerzeichen, gefolgt von Ihrem Zugriffstoken. Dieses Zugriffstoken wird abgerufen, indem die oben beschriebene Zugriffstokenanforderung ausgegeben wird. Dasselbe Zugriffstoken kann so lange 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 Typ der Benachrichtigung an und wie WNS sie verarbeiten soll. Nachdem die Benachrichtigung den Client erreicht hat, werden die tatsächlichen Nutzdaten mit diesem angegebenen Typ abgeglichen. Dieser Header ist erforderlich.

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

X-WNS-Cache-Policy

Wenn das Zielgerät für die Benachrichtigung offline ist, speichert WNS für jeden Kanal-URI eine Badge-, eine Kachel- und eine Popupbenachrichtigung zwischen. Standardmäßig werden unformatierte Benachrichtigungen nicht zwischengespeichert, aber wenn das Zwischenspeichern von unformatierten Benachrichtigungen aktiviert ist, wird eine unformatierte Benachrichtigung zwischengespeichert. Elemente werden nicht unbegrenzt im Cache zwischengespeichert und nach einem angemessenen Zeitraum gelöscht. Andernfalls wird der zwischengespeicherte Inhalt übermittelt, wenn das Gerät das nächste Mal online geht.

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 Tagbezeichnung zu. Das Tag wird in der Ersetzungsrichtlinie für die Kachel in der Benachrichtigungswarteschlange verwendet, wenn für eine App das Durchlaufen von Benachrichtigungen aktiviert wurde. Wenn in der Warteschlange bereits eine Benachrichtigung mit diesem Tag vorhanden ist, nimmt eine neue Benachrichtigung mit dem gleichen Tag ihren Platz ein.

    X-WNS-Tag: <string value>

X-WNS-TTL

Gibt die Ablaufzeit (TTL) für eine Benachrichtigung an. Diese wird normalerweise nicht benötigt, kann aber verwendet werden, wenn Sie sicherstellen möchten, dass Ihre Benachrichtigungen nicht später als zu einem bestimmten Zeitpunkt angezeigt werden. Der TTL-Wert wird in Sekunden angegeben und ist relativ zu dem Zeitpunkt, an dem WNS die Anforderung empfängt. Wenn eine Gültigkeitsdauer (TTL) angegeben ist, zeigt das Gerät die Benachrichtigung nach Ablauf dieses Zeitraums nicht mehr an. Hinweis: Eine zu kurze Gültigkeitsdauer kann dazu führen, dass die Benachrichtigung überhaupt nicht angezeigt wird. Im Allgemeinen beträgt das Messintervall von Ablaufzeiten mindestens eine Minute.

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

X-WNS-TTL: <integer value>

X-WNS-SuppressPopup

X-WNS-SuppressPopup: true | false

X-WNS-Group

X-WNS-Group: <string value>

X-WNS-Match

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 WNS die Benachrichtigungsanforderung verarbeitet hat, wird eine HTTP-Nachricht als Antwort gesendet. In diesem Abschnitt werden die Parameter und Header erläutert, die in dieser Antwort zu finden sind.

Antwortparameter

X-WNS-Debug-Trace

Dieser Header gibt nützliche Debuginformationen als Zeichenfolge zurück. Es wird empfohlen, diesen Header zu protokollieren, um Entwicklern beim Debuggen von Problemen zu helfen. Dieser Header wird zusammen mit dem X-WNS-Msg-ID-Header und MS-CV benötigt, wenn Sie ein Problem an WNS melden.

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 Menschen lesbare Zeichenfolge bereit, die zum leichteren Debuggen protokolliert werden sollte.

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

X-WNS-Msg-ID

Mit diesem Header wird dem Aufrufer ein Bezeichner für die Benachrichtigung mitgeteilt. Es wird empfohlen, diesen Header zu protokollieren, um das Debuggen von Fehlern zu erleichtern. Dieser Header wird zusammen mit X-WNS-Debug-Trace und MS-CV benötigt, wenn Sie ein Problem an WNS melden.

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

X-WNS-Status

Dieser Header beschreibt, wie WNS die Benachrichtigungsanforderung verarbeitet hat. Diese Information kann verwendet werden, anstatt Antwortcodes als Erfolg oder Fehler zu interpretieren.

X-WNS-Status: received | dropped | channelthrottled

MS-CV

Dieser Header enthält einen auf die Anforderung bezogenen Korrelationsvektor, der in erster Linie zum Debuggen verwendet wird. Wenn in der Anforderung ein CV-Wert angegeben wird, verwendet WNS diesen Wert, andernfalls generiert WNS einen CV-Wert und sendet diesen in der Antwort. Dieser Header wird zusammen mit X-WNS-Debug-Trace und dem X-WNS-Msg-ID-Header benötigt, wenn Sie ein Problem an WNS melden.

MS-CV: <string value>

Antwortcodes

Jede HTTP-Nachricht enthält einen dieser Antwortcodes. WNS empfiehlt Entwickler*innen, den Antwortcode zu protokollieren, um ihn beim Debuggen zu verwenden. Wenn Entwickler*innen ein Problem an WNS melden, müssen sie Antwortcodes und Headerinformationen angeben.

Nicht unterstützte HTTP-Features

Die WNS-Webschnittstelle unterstützt HTTP 1.1, aber nicht die folgenden Features:

• Segmentierung
• Pipelining (POST ist nicht idempotent)
• Wenngleich unterstützt, sollten Entwickler*innen „Expect-100“ deaktivieren, da dies zu einer Wartezeit beim Senden einer Benachrichtigung führt.