Freigeben über

CloudEvents-Erweiterung für Azure Web PubSub-Ereignishandler mit HTTP-Protokoll

Der Web PubSub-Dienst stellt Clientereignisse mithilfe der CloudEvents-HTTP-Protokollbindung an den upstream-Webhook bereit.

Die vom Web PubSub-Dienst an den Server gesendeten Daten befinden sich immer im CloudEvents-Format binary .

Webhook-Überprüfung

Die Webhook-Überprüfung folgt CloudEvents. Die Anforderung enthält WebHook-Request-Origin: xxx.webpubsub.azure.com immer den Header.

Wenn und nur, wenn das Übermittlungsziel die Übermittlung der Ereignisse zulässt, muss sie auf die Anforderung antworten, indem sie beispielsweise den Header einbezieht WebHook-Allowed-Origin :

WebHook-Allowed-Origin: *

Oder:

WebHook-Allowed-Origin: xxx.webpubsub.azure.com

Derzeit werden WebHook-Request-Rate und WebHook-Request-Callback nicht unterstützt.

Web PubSub CloudEvents-Attributerweiterung

Außerdem wurde festgestellt, dass die HTTP-Spezifikation nun einem ähnlichen Muster folgt, indem nicht mehr vorgeschlagen wird, dass Erweiterungs-HTTP-Header mit X-Präfix versehen werden.

Diese Erweiterung definiert Attribute, die von Web PubSub für jedes erzeugte Ereignis verwendet werden.

Attribute

Name Typ Beschreibung Beispiel
userId string Der Benutzer, der die Verbindung authentifiziert hat
hub string Der Hub, zu dem die Verbindung gehört
connectionId string Die connectionId ist für die Clientverbindung eindeutig.
eventName string Der Name des Ereignisses ohne Präfix
subprotocol string Der Unterprotocol, den der Client verwendet, falls vorhanden
connectionState string Definiert den Status für die Verbindung. Sie können denselben Antwortheader verwenden, um den Wert des Zustands zurückzusetzen. Mehrere connectionState Kopfzeilen sind nicht zulässig. Codieren Sie den Zeichenfolgenwert, wenn er komplexe Zeichen enthält, base64(jsonString) z. B. um komplexe Objekte mithilfe dieses Attributs zu übergeben.
signature string Die Signatur für den upstream-Webhook, um zu überprüfen, ob die eingehende Anforderung vom erwarteten Ursprung stammt. Der Dienst berechnet den Wert mit primärer Zugriffstaste und sekundärer Zugriffstaste als HMAC Schlüssel: Hex_encoded(HMAC_SHA256(accessKey, connectionId)). Der Upstream sollte überprüfen, ob die Anforderung vor der Verarbeitung gültig ist.

Ereignisse

Es gibt zwei Arten von Ereignissen. Eines ist das Blockieren von Ereignissen, die der Dienst auf die Antwort des Ereignisses wartet, um fortzufahren. Eines ist das Aufheben der Blockierung von Ereignissen, die der Dienst nicht auf die Antwort eines solchen Ereignisses wartet, bevor die nächste Nachricht verarbeitet wird.

Systemereignis connect

  • ce-type: azure.webpubsub.sys.connect
  • Content-Type: application/json

Anforderungsformat:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connect
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connect

{
    "claims": {},
    "query": {},
    "headers": {},
    "subprotocols": [],
    "clientCertificates": [
        {
            "thumbprint": "<certificate SHA-1 thumbprint>",
            "content": "-----BEGIN CERTIFICATE-----\r\n...\r\n-----END CERTIFICATE-----"
        }
    ]
}

Erfolgsantwortformat:

  • Kopfzeile ce-connectionState: Wenn dieser Header vorhanden ist, wird der Verbindungsstatus dieser Verbindung auf den Wert des Headers aktualisiert. Nur blockierende Ereignisse können den Verbindungsstatus aktualisieren. Im folgenden Beispiel wird die base64-codierte JSON-Zeichenfolge verwendet, um den komplexen Zustand für die Verbindung zu speichern.

  • Statuscode:

    • 204: Erfolg ohne Inhalt.
    • 200: Erfolg, der Inhalt SOLLTE ein JSON-Format sein, wobei die folgenden Eigenschaften zulässig sind:

      • subprotocols

        Das connect Ereignis leitet die Unterprotocol- und Authentifizierungsinformationen vom Client an upstream weiter. Der Web PubSub-Dienst verwendet den Statuscode, um zu ermitteln, ob die Anforderung auf das WebSocket-Protokoll aktualisiert wird.

        Wenn die Anforderung die subprotocols Eigenschaft enthält, sollte der Server einen unterstützten Unterprotocol zurückgeben. Wenn der Server keine Unterprotocols verwenden möchte, sollte die subprotocol Eigenschaft nicht als Antwort gesendet werden. Das Senden einer leeren Kopfzeile ist ungültig.

      • userId: {auth-ed user ID}

        Da der Dienst anonyme Verbindungen zulässt, liegt es in der connect Verantwortung des Ereignisses, dem Dienst die Benutzer-ID der Clientverbindung mitzuteilen. Der Dienst liest die Benutzer-ID aus der Antwortnutzlast userId , sofern vorhanden. Die Verbindung wird gelöscht, wenn die Benutzer-ID nicht aus den Anforderungsansprüchen oder der Antwortnutzlast des connect Ereignisses gelesen werden kann.

      • groups: {groups to join}

        Die Eigenschaft bietet eine bequeme Möglichkeit zum Hinzufügen dieser Verbindung zu einer oder mehreren Gruppen. Auf diese Weise muss keine weitere Verbindung zu einer Gruppe hinzugefügt werden.

      • roles: {roles the client has}

        Die Eigenschaft bietet eine Möglichkeit für den upstream-Webhook, den Client zu autorisieren. Es gibt verschiedene Rollen zum Erteilen von anfänglichen Berechtigungen für PubSub WebSocket-Clients. Details zu den Berechtigungen werden in Clientberechtigungen beschrieben.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "groups": [],
    "userId": "",
    "roles": [],
    "subprotocol": ""
}

Fehlerantwortformat:

  • 4xx: Fehler, die Antwort von Upstream wird als Antwort für die Clientanforderung zurückgegeben.
HTTP/1.1 401 Unauthorized

Systemereignis connected

Der Dienst ruft den Upstream auf, wenn der Client den WebSocket-Handshake abgeschlossen und erfolgreich verbunden ist.

  • ce-type: azure.webpubsub.sys.connected
  • Content-Type: application/json
  • ce-connectionState: eyJrZXkiOiJhIn0=

Der Anforderungstext ist leeres JSON.

Anforderungsformat:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connected
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{}

Antwortformat:

2xx: Erfolgsantwort.

connected ist ein asynchrones Ereignis, wenn der Antwortstatuscode nicht erfolgreich ist, protokolliert der Dienst einen Fehler.

HTTP/1.1 200 OK

Systemereignis disconnected

disconnected das Ereignis wird immer ausgelöst, wenn die Clientanforderung abgeschlossen wird, wenn das Connect-Ereignis Statuscode zurückgibt 2xx .

  • ce-type: azure.webpubsub.sys.disconnected
  • Content-Type: application/json

Anforderungsformat:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.disconnected
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: disconnected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "reason": "{Reason}"
}

  • reason

    Dies reason beschreibt den Grund, warum der Client die Verbindung trennt.

Antwortformat:

2xx: Erfolgsantwort.

disconnected ist ein asynchrones Ereignis, wenn der Antwortstatuscode nicht erfolgreich ist, protokolliert der Dienst einen Fehler.

HTTP/1.1 200 OK

Benutzerereignis message für die einfachen WebSocket-Clients

Der Dienst ruft den Ereignishandler für jeden WebSocket-Nachrichtenframe auf.

  • ce-type: azure.webpubsub.user.message
  • Content-Type: application/octet-stream für binären Rahmen; text/plain für Textrahmen;

UserPayload sendet den Kunden.

Anforderungsformat:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.message
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: message
ce-connectionState: eyJrZXkiOiJhIn0=

UserPayload

Erfolgsantwortformat

  • Statuscode
    • 204: Erfolg ohne Inhalt.
    • 200: Erfolg, das Format der UserResponsePayload Antwort hängt von Content-Type der Antwort ab.
  • Content-Type: application/octet-stream für binären Rahmen; text/plain für Textrahmen;
  • Kopfzeile Content-Type: application/octet-stream für binären Rahmen; text/plain für Textrahmen;
  • Kopfzeile ce-connectionState: Wenn dieser Header vorhanden ist, wird der Verbindungsstatus dieser Verbindung auf den Wert des Headers aktualisiert. Nur blockierende Ereignisse können den Verbindungsstatus aktualisieren. Im folgenden Beispiel wird die base64-codierte JSON-Zeichenfolge verwendet, um den komplexen Zustand für die Verbindung zu speichern.

Wenn dies Content-Type der Name ist application/octet-stream, sendet UserResponsePayload der Dienst mithilfe des WebSocket-Frames an den Client binary . Wenn dies Content-Type der Name ist text/plain, sendet UserResponsePayload der Dienst mithilfe des WebSocket-Frames an den Client text .

HTTP/1.1 200 OK
Content-Type: application/octet-stream (for binary frame) or text/plain (for text frame)
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=

UserResponsePayload

Fehlerantwortformat

Wenn der Statuscode nicht erfolgreich ist, wird er als Fehlerantwort betrachtet. Die Verbindung würde gelöscht , wenn der message Antwortstatuscode nicht erfolgreich ist.

Benutzerdefiniertes Benutzerereignis {custom_event} für PubSub WebSocket-Clients

Der Dienst ruft den Ereignishandler-Webhook für jede gültige benutzerdefinierte Ereignisnachricht auf.

Fall 1: Senden eines Ereignisses mit Textdaten:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "text",
    "data": "text data"
}

Was der upstream-Ereignishandler wie unten empfängt, ist text/plain die Content-Type Http-Anforderung für CloudEvents fürdataType=text

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

text data

Fall 2: Senden eines Ereignisses mit JSON-Daten:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    },
}

Was der upstream-Ereignishandler wie unten empfängt, ist application/json die Content-Type Http-Anforderung für CloudEvents fürdataType=json

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "hello": "world"
}

Fall 3: Senden eines Ereignisses mit Binärdaten:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

Was der upstream-Ereignishandler wie unten empfängt, ist application/octet-stream die Content-Type Http-Anforderung für CloudEvents fürdataType=binary

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1

<binary data>

Erfolgsantwortformat

HTTP/1.1 200 OK
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn

UserResponsePayload
  • Statuscode
    • 204: Erfolg ohne Inhalt.
    • 200: Erfolg, Daten, die an den PubSub WebSocket-Client gesendet werden, hängen vom Content-Type;
  • Kopfzeile ce-connectionState: Wenn dieser Header vorhanden ist, wird der Verbindungsstatus dieser Verbindung auf den Wert des Headers aktualisiert. Nur blockierende Ereignisse können den Verbindungsstatus aktualisieren. Im folgenden Beispiel wird die base64-codierte JSON-Zeichenfolge verwendet, um den komplexen Zustand für die Verbindung zu speichern.
  • Wenn Header Content-Type lautet application/octet-stream, sendet UserResponsePayload der Dienst wie bei base64-codierter Nutzlast an den Client dataTypebinary zurück. Beispielantwort: 
    {
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
  • Wenn dies Content-Type der Wert ist text/plain, sendet UserResponsePayload der Dienst mit der Nutzlastzeichenfolge an den Client dataTypetext .
  • Wenn dies Content-Type der Wert istapplication/json, sendet UserResponsePayload der Dienst mit Werttoken als Antwortnutzlasttext an den Client datadataType=json.

Fehlerantwortformat

Wenn der Statuscode nicht erfolgreich ist, wird er als Fehlerantwort betrachtet. Die Verbindung würde gelöscht , wenn der {custom_event} Antwortstatuscode nicht erfolgreich ist.

Nächste Schritte

Erstellen Sie mithilfe dieser Ressourcen Ihre eigene Anwendung:

Tutorial: Veröffentlichen und Abonnieren von Nachrichten in Azure Web PubSub

Tutorial: Erstellen eines einfachen Chatrooms mit Azure Web PubSub

Tutorial: Verwenden eines vom Dienst unterstützten Unterprotokolls für Clientstreaming

Tutorial: Erstellen eines serverlosen Chats mit Azure Functions und Web PubSub

Tutorial: Konfigurieren eines Ereignislisteners

Spielen mit Livedemos

Weitere Beispiele für Azure Web PubSub

  • Last updated on