Rozšíření CloudEvents pro obslužnou rutinu události Azure Web PubSub s protokolem HTTP

Článek
10/26/2023

Služba Web PubSub doručuje události klienta do upstreamového webhooku pomocí vazby protokolu HTTP CloudEvents.

Data odeslaná ze služby Web PubSub na server jsou vždy ve formátu CloudEvents binary .

Ověření webhooku
Rozšíření atributů Web PubSub CloudEvents
Události
- Blokování událostí
  - Systémová connect událost
  - Události uživatelů
- Odblokování událostí
  - Systémová connected událost
  - Systémová disconnected událost

Ověření webhooku

Ověření webhooku se řídí CloudEvents. Požadavek vždy obsahuje WebHook-Request-Origin: xxx.webpubsub.azure.com v hlavičce.

Pokud cíl doručení povoluje doručení událostí, musí odpovědět na požadavek zahrnutím WebHook-Allowed-Origin hlavičky, například:

WebHook-Allowed-Origin: *

Nebo:

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

Prozatím se nepodporuje funkce WebHook-Request-Rate a WebHook-Request-Callback.

Rozšíření atributů Web PubSub CloudEvents

Také jsme si poznamenali, že specifikace HTTP nyní sleduje podobný vzor tím, že už nenavrhuje, aby hlavičky HTTP rozšíření byly předpony X-.

Toto rozšíření definuje atributy používané web pubSub pro každou událost, kterou vytvoří.

Atributy

Name	Typ	Popis
`userId`	`string`	Uživatel, který připojení autoroval
`hub`	`string`	Centrum, do které připojení patří
`connectionId`	`string`	ID připojení je jedinečné pro připojení klienta.
`eventName`	`string`	Název události bez předpony
`subprotocol`	`string`	Dílčí souhrn, který klient používá, pokud existuje
`connectionState`	`string`	Definuje stav připojení. Stejnou hlavičku odpovědi můžete použít k resetování hodnoty stavu. Více `connectionState` záhlaví není povoleno. Do base64 kódovat řetězcovou hodnotu, pokud obsahuje složité znaky uvnitř, `base64(jsonString)` například předat komplexní objekt pomocí tohoto atributu.
`signature`	`string`	Podpis upstreamového webhooku, který ověří, jestli příchozí požadavek pochází z očekávaného původu. Služba vypočítá hodnotu pomocí primárního přístupového klíče i sekundárního přístupového `HMAC` klíče jako klíče: `Hex_encoded(HMAC_SHA256(accessKey, connectionId))`. Upstream by měl před zpracováním zkontrolovat, jestli je požadavek platný.

Událost

Existují dva typy událostí. Jedna blokuje události, které služba čeká na pokračování odpovědi události. Jedním z nich je odblokování událostí, které služba nečeká na odpověď takové události před zpracováním další zprávy.

Blokování událostí
- Systémová connect událost
- Události uživatelů
Odblokování událostí
- Systémová connected událost
- Systémová disconnected událost

Systémová `connect` událost

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

Formát požadavku:

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

Formát odpovědi na úspěch:

Hlavička ce-connectionState: Pokud tato hlavička existuje, stav připojení tohoto připojení se aktualizuje na hodnotu hlavičky. Stav připojení může aktualizovat pouze blokující události. Následující ukázka používá řetězec JSON kódovaný v base64 k uložení komplexního stavu připojení.
Stavový kód:
- 204: Úspěch bez obsahu.
- 200: Úspěch, obsah by měl být formát JSON s následujícími povolenými vlastnostmi:
  - subprotocols
    
    Událost connect předá subprotocol a ověřovací informace do upstreamu z klienta. Služba Web PubSub používá stavový kód k určení, jestli se požadavek upgraduje na protokol WebSocket.
    
    Pokud požadavek obsahuje subprotocols vlastnost, měl by server vrátit jeden dílčí souhrn, který podporuje. Pokud server nechce používat žádné dílčí souhrny, neměl subprotocol by odeslat vlastnost v odpovědi. Odeslání prázdné hlavičky je neplatné.
  - userId: {auth-ed user ID}
    
    Protože služba umožňuje anonymní připojení, je connect zodpovědností události informovat službu o ID uživatele připojení klienta. Pokud existuje, služba načte ID uživatele z datové části userId odpovědi. Připojení se zahodí, pokud ID uživatele nelze číst z deklarací identity požadavku ani connect datové části odpovědi události.
  - groups: {groups to join}
    
    Vlastnost poskytuje pohodlný způsob, jak uživatel přidat toto připojení k jedné nebo více skupinám. Tímto způsobem není potřeba mít další volání pro přidání tohoto připojení do určité skupiny.
  - roles: {roles the client has}
    
    Vlastnost poskytuje způsob, jak upstream Webhook autorizovat klienta. Existují různé role k udělení počátečních oprávnění pro klienty PubSub WebSocket. Podrobnosti o oprávněních jsou popsány v oprávněních klienta.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

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

Formát odpovědi na chybu:

4xx: Chyba, odpověď z upstreamu bude vrácena jako odpověď pro požadavek klienta.

HTTP/1.1 401 Unauthorized

Systémová `connected` událost

Služba volá upstream, když klient dokončí metodu handshake protokolu WebSocket a úspěšně se připojí.

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

Text požadavku je prázdný JSON.

Formát požadavku:

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=

{}

Formát odpovědi:

2xx: odpověď na úspěch.

connected je asynchronní událost, pokud stavový kód odpovědi není úspěšný, služba zaznamená chybu.

HTTP/1.1 200 OK

Systémová `disconnected` událost

disconnected událost se vždy aktivuje, když se požadavek klienta dokončí, pokud událost připojení vrátí 2xx stavový kód.

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

Formát požadavku:

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

Popisuje reason důvod, proč se klient odpojí.

Formát odpovědi:

2xx: odpověď na úspěch.

disconnected je asynchronní událost, pokud stavový kód odpovědi není úspěšný, služba zaznamená chybu.

HTTP/1.1 200 OK

Událost `message` uživatele pro jednoduché klienty WebSocket

Služba vyvolá upstream obslužné rutiny události pro každý rámec zprávy WebSocket.

ce-type: azure.webpubsub.user.message
Content-Type: application/octet-stream pro binární rámec; text/plain pro textový rámec;

UserPayload je to, co klient odesílá.

Formát požadavku:

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

Formát odpovědi na úspěch

Stavový kód
- 204: Úspěch bez obsahu.
- 200: Úspěch, formát odpovědi UserResponsePayload závisí na Content-Type odpovědi.
Content-Type: application/octet-stream pro binární rámec; text/plain pro textový rámec;
Hlavička Content-Type: application/octet-stream pro binární rámeček; text/plain pro textový rámeček;
Hlavička ce-connectionState: Pokud tato hlavička existuje, stav připojení tohoto připojení se aktualizuje na hodnotu hlavičky. Stav připojení může aktualizovat pouze blokující události. Následující ukázka používá řetězec JSON kódovaný v base64 k uložení složitého stavu připojení.

Pokud je application/octet-stream, Content-Type služba odešle UserResponsePayload klientovi pomocí binary rámce WebSocket. Pokud je text/plain, Content-Type služba odešle UserResponsePayload klientovi pomocí text rámce WebSocket.

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

Formát odpovědi na chybu

Pokud stavový kód není úspěšný, považuje se za chybovou odpověď. Pokud stavový kód odpovědi nebude úspěšný, připojení se zahodímessage.

Vlastní událost `{custom_event}` uživatele pro klienty PubSub WebSocket

Služba volá webhook obslužné rutiny události pro každou platnou vlastní zprávu události.

Případ 1: Odeslání události s textovými daty:

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

Co obslužná rutina upstreamové události přijímá jako v následujícím příkladu Content-Type , pro požadavek HTTP CloudEvents je text/plain určený 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

Případ 2: Odeslání události s daty JSON:

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

Co obslužná rutina upstreamové události přijímá jako v následujícím příkladu Content-Type , pro požadavek HTTP CloudEvents je application/json určený 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"
}

Případ 3: Odeslání události s binárními daty:

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

Co obslužná rutina upstreamové události přijímá jako v následujícím příkladu Content-Type , pro požadavek HTTP CloudEvents je application/octet-stream určený 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>

Formát odpovědi na úspěch

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

UserResponsePayload

Stavový kód
- 204: Úspěch bez obsahu.
- 200: Úspěch, odesílání dat do klienta PubSub WebSocket závisí na Content-Type;
Hlavička ce-connectionState: Pokud tato hlavička existuje, stav připojení tohoto připojení se aktualizuje na hodnotu hlavičky. Stav připojení může aktualizovat pouze blokující události. Následující ukázka používá řetězec JSON kódovaný v base64 k uložení komplexního stavu připojení.
Pokud je hlavička Content-Type , služba odešle UserResponsePayload zpět klientovi, který používá dataType jako binary s kódováním base64 datové application/octet-streamčásti. Ukázková odpověď:
```
{
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
```
Pokud je text/plaintomu takContent-Type, služba odešle UserResponsePayload klientovi jako dataType text s řetězcem datové části.
Pokud je application/json, Content-Type služba odešle UserResponsePayload klientovi pomocí dataType=json tokenu data hodnoty jako tělo datové části odpovědi.

Formát odpovědi na chybu

Pokud stavový kód není úspěšný, považuje se za chybovou odpověď. Pokud stavový kód odpovědi nebude úspěšný, připojení se zahodí{custom_event}.

Další kroky

Pomocí těchto prostředků můžete začít vytvářet vlastní aplikaci:

Kurz: Publikování a přihlášení k odběru zpráv ve službě Azure Web PubSub

Kurz: Vytvoření jednoduché chatovací místnosti pomocí azure Web PubSub

Kurz: Použití subprotokolu podporované služby pro streamování klientů

Kurz: Vytváření bezserverového chatu se službou Azure Functions a web pubSub

Kurz: Konfigurace naslouchacího procesu událostí

Přehrávání s živými ukázkami

Prozkoumání dalších ukázek Azure Web PubSub

Sdílet prostřednictvím

Rozšíření CloudEvents pro obslužnou rutinu události Azure Web PubSub s protokolem HTTP

Ověření webhooku

Rozšíření atributů Web PubSub CloudEvents

Atributy

Událost

Systémová `connect` událost

Formát požadavku:

Formát odpovědi na úspěch:

Formát odpovědi na chybu:

Systémová `connected` událost

Formát požadavku:

Formát odpovědi:

Systémová `disconnected` událost

Formát požadavku:

Formát odpovědi:

Událost `message` uživatele pro jednoduché klienty WebSocket

Formát požadavku:

Formát odpovědi na úspěch

Formát odpovědi na chybu

Vlastní událost `{custom_event}` uživatele pro klienty PubSub WebSocket

Případ 1: Odeslání události s textovými daty:

Případ 2: Odeslání události s daty JSON:

Případ 3: Odeslání události s binárními daty:

Formát odpovědi na úspěch

Formát odpovědi na chybu

Další kroky

Váš názor

Další materiály

Sdílet prostřednictvím

Rozšíření CloudEvents pro obslužnou rutinu události Azure Web PubSub s protokolem HTTP

Ověření webhooku

Rozšíření atributů Web PubSub CloudEvents

Atributy

Událost

Systémová connect událost

Formát požadavku:

Formát odpovědi na úspěch:

Formát odpovědi na chybu:

Systémová connected událost

Formát požadavku:

Formát odpovědi:

Systémová disconnected událost

Formát požadavku:

Formát odpovědi:

Událost message uživatele pro jednoduché klienty WebSocket

Formát požadavku:

Formát odpovědi na úspěch

Formát odpovědi na chybu

Vlastní událost {custom_event} uživatele pro klienty PubSub WebSocket

Případ 1: Odeslání události s textovými daty:

Případ 2: Odeslání události s daty JSON:

Případ 3: Odeslání události s binárními daty:

Formát odpovědi na úspěch

Formát odpovědi na chybu

Další kroky

Váš názor

Další materiály

Systémová `connect` událost

Systémová `connected` událost

Systémová `disconnected` událost

Událost `message` uživatele pro jednoduché klienty WebSocket

Vlastní událost `{custom_event}` uživatele pro klienty PubSub WebSocket