Upgrade header
Baseline
Weitgehend verfügbar
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Juli 2015 browserübergreifend verfügbar.
Der HTTP-Upgrade-Request-Header und -Response-Header können verwendet werden, um eine bereits bestehende Verbindung zwischen Client und Server auf ein anderes Protokoll umzustellen (unter Verwendung desselben Transportprotokolls).
Beispielsweise kann ein Client damit eine Verbindung von HTTP/1.1 auf HTTP/2 oder eine HTTP(S)-Verbindung auf eine WebSocket-Verbindung umstellen.
Warnung: HTTP/2 untersagt die Verwendung dieses Mechanismus und dieses Headers ausdrücklich; sie sind spezifisch für HTTP/1.1.
| Header-Typ | Request-Header, Response-Header |
|---|---|
| Verbotener Request-Header | Ja |
Syntax
Upgrade: <protocol>[/<protocol_version>]
Upgrade: <protocol>[/<protocol_version>], …, <protocolN>[/<protocol_versionN>]
Direktiven
<protocol>-
Protokolle werden durch Kommas getrennt und in absteigender Reihenfolge ihrer Präferenz aufgeführt.
<protocol_version>Optional-
Optional kann eine Protokollversion angegeben werden, der ein Schrägstrich
/vorangestellt ist.
Beschreibung
Clients können den Upgrade-Header verwenden, um einen Server aufzufordern, zu einem oder mehreren der aufgeführten Protokolle zu wechseln, geordnet nach absteigender Präferenz.
Beispielsweise könnte der Client eine GET-Anfrage wie gezeigt senden und dabei die bevorzugten Protokolle für den Wechsel angeben (in diesem Fall example/1 und foo/2):
GET /index.html HTTP/1.1
Host: www.example.com
Connection: upgrade
Upgrade: example/1, foo/2
Hinweis:
Der Connection-Header mit dem Wert upgrade muss immer zusammen mit dem Upgrade-Header gesendet werden.
Der Server kann die Anfrage aus beliebigem Grund ignorieren. In diesem Fall sollte er so antworten, als wäre der Upgrade-Header nicht gesendet worden (beispielsweise mit einem 200 OK).
Wenn der Server die Verbindung umstellt, muss er:
-
Einen
101 Switching Protocols-Antwortstatus mit einemUpgrade-Header zurücksenden, der das Protokoll bzw. die Protokolle angibt, zu denen gewechselt wird. Zum Beispiel:httpHTTP/1.1 101 Switching Protocols Upgrade: foo/2 Connection: Upgrade -
Eine Antwort auf die ursprüngliche Anfrage unter Verwendung des neuen Protokolls senden (der Server darf nur zu einem Protokoll wechseln, mit dem er die ursprüngliche Anfrage abschließen kann).
Ein Server kann den Header auch als Teil einer 426-Antwort (Upgrade Required) senden, um anzugeben, dass er die Anfrage mit dem aktuellen Protokoll nicht ausführt, dies nach einem Protokollwechsel aber möglicherweise tun würde. Der Client kann dann mithilfe des oben beschriebenen Verfahrens einen Protokollwechsel anfordern.
Weitere Einzelheiten und Beispiele finden Sie unter Mechanismus zum Protokollwechsel.
Beispiele
Upgrade-Header mit mehreren Protokollen
Die folgende Anfrage führt mehrere Protokolle in absteigender Reihenfolge ihrer Präferenz auf:
Connection: upgrade
Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
Wechsel zu WebSocket
Diese Kombination von Headern wird häufig verwendet, um den Wechsel einer HTTP-Verbindung zu WebSocket einzuleiten. Weitere Informationen finden Sie unter Wechsel zu einer WebSocket-Verbindung.
Connection: Upgrade
Upgrade: websocket
Spezifikationen
| Spezifikation |
|---|
| HTTP Semantics # field.upgrade |
| HTTP Semantics # status.426 |
| HTTP/2 # informational-responses |