CloudEvents-bővítmény az Azure Web PubSub eseménykezelőhöz HTTP-protokollal

  • Cikk

A Web PubSub szolgáltatás a CloudEvents HTTP protokollkötésével kézbesíti az ügyféleseményeket a felsőbb rétegbeli webhooknak.

A Web PubSub szolgáltatásból a kiszolgálóra küldött adatok mindig CloudEvents formátumúak binary .

Webhook ellenőrzése

A Webhook érvényesítése a CloudEventst követi. A kérés mindig tartalmazza WebHook-Request-Origin: xxx.webpubsub.azure.com a fejlécet.

Ha és csak akkor, ha a kézbesítési cél engedélyezi az események kézbesítését, akkor a kérésre a fejlécet is beleértve WebHook-Allowed-Origin kell válaszolnia, például:

WebHook-Allowed-Origin: *

Vagy:

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

A WebHook-Request-Rate és a WebHook-Request-Callback egyelőre nem támogatott.

Web PubSub CloudEvents attribútumbővítmény

Azt is megjegyezték, hogy a HTTP-specifikáció most már hasonló mintát követ, mivel már nem utal arra, hogy a bővítmény HTTP-fejlécei X-előtaggal legyenek elnevezve.

Ez a bővítmény a Web PubSub által használt attribútumokat határozza meg minden általa létrehozott eseményhez.

Attribútumok

Név Típus Leírás Példa
userId string A kapcsolat hitelesítésével rendelkező felhasználó
hub string Az a központ, amelyhez a kapcsolat tartozik
connectionId string A connectionId egyedi az ügyfélkapcsolathoz
eventName string Az esemény neve előtag nélkül
subprotocol string Az ügyfél által használt alprotocol, ha van ilyen
connectionState string Meghatározza a kapcsolat állapotát. Ugyanezzel a válaszfejléccel alaphelyzetbe állíthatja az állapot értékét. Több connectionState fejléc nem engedélyezett. A base64 kódolja a sztringértéket, ha összetett karaktereket tartalmaz, például base64(jsonString) összetett objektumot szeretne átadni ezzel az attribútummal.
signature string A felsőbb rétegbeli webhook aláírása annak ellenőrzéséhez, hogy a bejövő kérés a várt forrásból származik-e. A szolgáltatás az elsődleges hozzáférési és a másodlagos hozzáférési kulcs használatával is kiszámítja az értéket kulcsként HMAC : Hex_encoded(HMAC_SHA256(accessKey, connectionId)). A felsőbb rétegnek ellenőriznie kell, hogy a kérés érvényes-e a feldolgozás előtt.

esemény

Kétféle esemény létezik. Az egyik az események blokkolása , amelyeket a szolgáltatás vár az esemény válaszának folytatására. Az egyik az események blokkolásának feloldása , amelyeket a szolgáltatás nem vár meg az ilyen esemény válaszára a következő üzenet feldolgozása előtt.

Rendszeresemény connect

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

Kérelem formátuma:

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": "ABC"
        }
    ]
}

Sikeres válasz formátuma:

  • Fejléc ce-connectionState: Ha ez az élőfej létezik, a kapcsolat kapcsolati állapota a fejléc értékére frissül. Csak a blokkoló események frissíthetik a kapcsolat állapotát. Az alábbi minta base64 kódolású JSON-sztringet használ a kapcsolat összetett állapotának tárolásához.

  • Állapotkód:

    • 204: Siker tartalom nélkül.
    • 200: Sikeres, a tartalomnak JSON formátumúnak kell lennie, és a következő tulajdonságok engedélyezettek:

      • subprotocols

        Az connect esemény továbbítja az alprotocol és a hitelesítési adatokat az ügyfélről a felsőbb rétegbe. A Web PubSub szolgáltatás az állapotkód használatával állapítja meg, hogy a kérés frissítve lesz-e a WebSocket protokollra.

        Ha a kérelem tartalmazza a subprotocols tulajdonságot, a kiszolgálónak egy támogatott alprojektet kell visszaadnia. Ha a kiszolgáló nem szeretne alprotocolokat használni, nem szabad válaszként elküldenie a subprotocol tulajdonságot. Az üres fejléc küldése érvénytelen.

      • userId: {auth-ed user ID}

        Mivel a szolgáltatás névtelen kapcsolatokat tesz lehetővé, az connect esemény felelőssége, hogy a szolgáltatásnak az ügyfélkapcsolat felhasználói azonosítóját adja meg. A szolgáltatás beolvassa a felhasználói azonosítót a válasz hasznos adataiból userId , ha létezik. A kapcsolat megszakad, ha a felhasználói azonosító nem olvasható be a kérés jogcímeiből és az connect esemény válaszainak hasznos adataiból.

      • groups: {groups to join}

        A tulajdonság kényelmes módot biztosít arra, hogy a felhasználó ezt a kapcsolatot egy vagy több csoporthoz adja hozzá. Ily módon nincs szükség másik hívásra, hogy ezt a kapcsolatot hozzáadja egy csoporthoz.

      • roles: {roles the client has}

        A tulajdonság lehetővé teszi a felsőbb rétegbeli webhook számára az ügyfél engedélyezését. A PubSub WebSocket-ügyfelek kezdeti engedélyeinek megadásához különböző szerepkörök tartoznak. Az engedélyekkel kapcsolatos részleteket az ügyfélengedélyek ismertetik.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

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

Hibaválasz formátuma:

  • 4xx: Hiba, a rendszer a felsőbb réteg válaszát adja vissza az ügyfélkérés válaszaként.
HTTP/1.1 401 Unauthorized

Rendszeresemény connected

A szolgáltatás meghívja a felsőbb réteget, amikor az ügyfél befejezi a WebSocket kézfogását, és sikeresen csatlakozik.

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

A kérelem törzse üres JSON.

Kérelem formátuma:

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=

{}

Válaszformátum:

2xx: sikeres válasz.

connected aszinkron esemény, ha a válasz állapotkódja nem sikeres, a szolgáltatás hibát naplóz.

HTTP/1.1 200 OK

Rendszeresemény disconnected

disconnectedaz esemény mindig akkor aktiválódik, amikor az ügyfélkérés befejeződik, ha a kapcsolódási esemény állapotkódot ad 2xx vissza.

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

Kérelem formátuma:

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

    Ez reason a cikk azt ismerteti, hogy az ügyfél miért bontja le a kapcsolatot.

Válaszformátum:

2xx: sikeres válasz.

disconnected aszinkron esemény, ha a válasz állapotkódja nem sikeres, a szolgáltatás hibát naplóz.

HTTP/1.1 200 OK

Felhasználói esemény message az egyszerű WebSocket-ügyfelek számára

A szolgáltatás minden WebSocket-üzenetkerethez meghívja az eseménykezelőt.

  • ce-type: azure.webpubsub.user.message
  • Content-Type: application/octet-stream bináris kerethez; text/plain szövegkerethez;

A UserPayload az, amit az ügyfél küld.

Kérelem formátuma:

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

Sikeres válasz formátuma

  • Állapotkód
    • 204: Siker tartalom nélkül.
    • 200: Sikeresség, a UserResponsePayload formátum a választól függ Content-Type .
  • Content-Type: application/octet-stream bináris kerethez; text/plain szövegkerethez;
  • Fejléc Content-Type: application/octet-stream bináris kerethez; text/plain szövegkerethez;
  • Fejléc ce-connectionState: Ha ez az élőfej létezik, a kapcsolat kapcsolati állapota a fejléc értékére frissül. Csak a blokkoló események frissíthetik a kapcsolat állapotát. Az alábbi minta base64 kódolású JSON-sztringet használ a kapcsolat összetett állapotának tárolásához.

Ha igen Content-Typeapplication/octet-stream, a szolgáltatás WebSocket-kerettel binary küldi el UserResponsePayload az ügyfelet. Ha igen Content-Typetext/plain, a szolgáltatás WebSocket-kerettel text küldi el UserResponsePayload az ügyfelet.

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

Hibaválasz formátuma

Ha az állapotkód nem sikeres, a rendszer hibaválasznak tekinti. A kapcsolat megszakadna, ha a message válasz állapotkódja nem sikerül.

Egyéni felhasználói esemény {custom_event} PubSub WebSocket-ügyfelek számára

A szolgáltatás minden érvényes egyéni eseményüzenethez meghívja az eseménykezelő webhookját.

1. eset: esemény küldése szöveges adatokkal:

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

Amit a felsőbb rétegbeli eseménykezelő az alábbihoz hasonlóan kap, a Content-Type CloudEvents HTTP-kérése a text/plain következőre vonatkozik: dataType=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

2. eset: esemény küldése JSON-adatokkal:

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

Amit a felsőbb rétegbeli eseménykezelő az alábbihoz hasonlóan kap, a Content-Type CloudEvents HTTP-kérése a application/json következőre vonatkozik: dataType=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"
}

3. eset: esemény küldése bináris adatokkal:

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

Amit a felsőbb rétegbeli eseménykezelő az alábbihoz hasonlóan kap, a Content-Type CloudEvents HTTP-kérése a application/octet-stream következőre vonatkozik: dataType=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>

Sikeres válasz formátuma

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

UserResponsePayload
  • Állapotkód
    • 204: Siker tartalom nélkül.
    • 200: Sikeresség, a PubSub WebSocket-ügyfélnek küldött adatok az Content-Type;
  • Fejléc ce-connectionState: Ha ez az élőfej létezik, a kapcsolat kapcsolati állapota a fejléc értékére frissül. Csak a blokkoló események frissíthetik a kapcsolat állapotát. Az alábbi minta base64 kódolású JSON-sztringet használ a kapcsolat összetett állapotának tárolásához.
  • Ha a fejléc Content-Type azapplication/octet-stream, a szolgáltatás a base64-kódolt hasznos adatokkal binarydataType együtt küld UserResponsePayload vissza az ügyfélnek. Mintaválasz: 
    {
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
  • Ha igen Content-Typetext/plain, a szolgáltatás a hasznos adatsztring használatával textdataType küldi el UserResponsePayload az ügyfélnek.
  • Ha igen Content-Typeapplication/json, a szolgáltatás a válasz hasznos adattörzseként érték jogkivonattal data küldi UserResponsePayload el az ügyfelet=dataTypejson.

Hibaválasz formátuma

Ha az állapotkód nem sikeres, a rendszer hibaválasznak tekinti. A kapcsolat megszakadna, ha a {custom_event} válasz állapotkódja nem sikerül.

Következő lépések

Használja ezeket az erőforrásokat a saját alkalmazás létrehozásához:

Oktatóanyag: Üzenetek közzététele és feliratkozás az Azure Web PubSubban

Oktatóanyag: Egyszerű csevegőszoba létrehozása az Azure Web PubSub használatával

Oktatóanyag: Szolgáltatás által támogatott alprotocol használata az ügyfélstreameléshez

Oktatóanyag: Kiszolgáló nélküli csevegés létrehozása az Azure Functions és a Web PubSub használatával

Oktatóanyag: Eseményfigyelő konfigurálása

Élő bemutatók lejátszása

További Azure Web PubSub-minták felfedezése