Sdílet prostřednictvím

Podsložka Json Web PubSub podporovala podprotokol json WebSocket

  • Článek

Subprotocol json.webpubsub.azure.v1JSON WebSocket umožňuje výměnu zpráv publikování a odběru mezi klienty prostřednictvím služby bez odezvy na nadřazený server. Připojení WebSocket pomocí json.webpubsub.azure.v1 subprotocol se nazývá klient PubSub WebSocket.

Přehled

Jednoduché připojení WebSocket aktivuje message událost při odesílání zpráv a spoléhá na zpracování zpráv na straně serveru a provádění dalších operací.

json.webpubsub.azure.v1 Pomocí subprotocolu můžete vytvořit klienty PubSub WebSocket, kteří můžou:

  • připojte se ke skupině pomocí žádostí o připojení.
  • publikování zpráv přímo do skupiny pomocí žádostí o publikování
  • směruje zprávy do různých upstreamových obslužných rutin událostí pomocí požadavků na události.

Můžete například vytvořit klienta PubSub WebSocket s následujícím kódem JavaScriptu:

// PubSub WebSocket client
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');

Tento dokument popisuje požadavky a odpovědi meziprotokoly json.webpubsub.azure.v1 . Příchozí i odchozí datové rámce musí obsahovat datové části JSON.

Oprávnění

Klient PubSub WebSocket může publikovat pouze do jiných klientů, pokud je autorizovaný. Přiřazené roles klientovi určují oprávnění udělená klientovi:

Role Oprávnění
Neurčeno Klient může odesílat žádosti o události.
webpubsub.joinLeaveGroup Klient se může připojit nebo opustit libovolnou skupinu.
webpubsub.sendToGroup Klient může publikovat zprávy do libovolné skupiny.
webpubsub.joinLeaveGroup.<group> Klient se může ke skupině <group>připojit nebo ji opustit .
webpubsub.sendToGroup.<group> Klient může publikovat zprávy do skupiny <group>.

Server může dynamicky udělovat nebo odvolávat klientská oprávnění prostřednictvím rozhraní REST API nebo sad SDK serveru.

Žádosti

Připojení ke skupinám

Formát:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId je identita každého požadavku a měla by být jedinečná. Služba odešle zprávu odpovědi ack, která oznámí výsledek procesu požadavku. Podrobnosti najdete v tématu AckId a Odpověď Ack.

Opustit skupiny

Formát:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId je identita každého požadavku a měla by být jedinečná. Služba odešle zprávu odpovědi ack, která oznámí výsledek procesu požadavku. Podrobnosti najdete v tématu AckId a Odpověď Ack.

Publikování zpráv

Formát:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId je identita každého požadavku a měla by být jedinečná. Služba odešle zprávu odpovědi ack, která oznámí výsledek procesu požadavku. Podrobnosti najdete v tématu AckId a Odpověď Ack.
  • noEcho je volitelné. Pokud je nastavená hodnota true, tato zpráva se neodpoví zpátky ke stejnému připojení. Pokud není nastavená, výchozí hodnota je false.
  • dataType lze nastavit na jsonhodnotu , textnebo binary:
    • json: data může být libovolný typ, který JSON podporuje, a bude publikován jako to, co je; Pokud dataType není zadáno, výchozí hodnota je json.
    • text: data měla by být ve formátu řetězce a data řetězce budou publikována;
    • binary: data měla by být ve formátu base64 a binární data budou publikována;

Případ 1: Publikování textových dat:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • Klienti subprotocol v <group_name> příjmu:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Jednoduché klienty WebSocket obdrží <group_name> řetězec text data.

Případ 2: Publikování dat JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Klienti subprotocol v <group_name> příjmu:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Jednoduché klienty WebSocket obdrží <group_name> serializovaný řetězec {"hello": "world"}.

Případ 3: Publikování binárních dat:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • Klienti subprotocol v <group_name> příjmu:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Jednoduchí klienti WebSocket obdrží <group_name> binární data v binárním rámci.

Odesílání vlastních událostí

Formát:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId je identita každého požadavku a měla by být jedinečná. Služba odešle zprávu odpovědi ack, která oznámí výsledek procesu požadavku. Podrobnosti najdete v tématu AckId a Odpověď Ack.

dataType může být jedním z text, binarynebo json:

  • json: data můžou být libovolným typem JSON podporována a budou publikována jako to, co to je; Výchozí hodnota je json.
  • text: data jsou ve formátu řetězce a data řetězce budou publikována;
  • binary: data jsou ve formátu base64 a binární data budou publikována;

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

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

Obslužná rutina upstreamové události přijímá data podobná:

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>

text data

Požadavek Content-Type HTTP CloudEvents je text/plain v případě , že dataType je text.

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

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

Obslužná rutina upstreamové události přijímá data podobná:

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>

{
    "hello": "world"
}

Požadavek Content-Type HTTP CloudEvents je v případě, že dataType je application/jsonjson

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

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_binary", 
}

Obslužná rutina upstreamové události přijímá data podobná:

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>

binary

Požadavek Content-Type HTTP CloudEvents je application/octet-stream v případě , že dataType je binary. Rámeček WebSocket může být text formátován pro rámečky textových zpráv nebo binární soubory kódované UTF8 pro binary rámce zpráv.

Služba Web PubSub odmítne klienta, pokud zpráva neodpovídá popsanému formátu.

Odpovědi

Typy zpráv přijaté klientem mohou být:

  • ack – odpověď na požadavek obsahující .ackId
  • message – Zprávy ze skupiny nebo serveru
  • system – zprávy ze služby Web PubSub.

Odpověď Ack

Když požadavek klienta obsahuje ackId, služba vrátí odpověď ack pro požadavek. Klient by měl zpracovat mechanismus ack tím, že čeká na odpověď ack s async await operací a použije operaci vypršení časového limitu, když odpověď ack není přijata v určitém období.

Formát:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

Implementace klienta BY měla vždy zkontrolovat, zda success je true nebo false je první, pak číst pouze chybu, pokud success je false.

Odpověď na zprávu

Klienti můžou přijímat zprávy publikované ze skupiny, ke které se klient připojil, nebo ze serveru, který funguje v roli správy serveru, odesílá zprávy konkrétním klientům nebo uživatelům.

  1. Když je zpráva ze skupiny

    {
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
    "fromUserId": "abc"
}

  2. Když je zpráva ze serveru.

    {
    "type": "message",
    "from": "server",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
}

Případ 1: Odesílání dat Hello World do připojení prostřednictvím rozhraní REST API s využitím Content-Type=text/plain

  • Jednoduchý klient WebSocket obdrží textový rámec WebSocket s daty: Hello World;

  • Klient PubSub WebSocket přijímá:

    {
    "type": "message",
    "from": "server",
    "dataType" : "text",
    "data": "Hello World", 
}

Případ 2: Odesílání dat { "Hello" : "World"} do připojení prostřednictvím rozhraní REST API s využitím Content-Type=application/json

  • Jednoduchý klient WebSocket obdrží textový rámec WebSocket s řetězci dat: { "Hello" : "World"}.

  • Klient PubSub WebSocket přijímá:

    {
    "type": "message",
    "from": "server",
    "dataType" : "json",
    "data": {
        "Hello": "World"
    }
}

Pokud rozhraní REST API odesílá řetězec Hello World pomocí application/json typu obsahu, jednoduchý klient WebSocket obdrží řetězec JSON, který je "Hello World" zabalený dvojitými uvozovkami (").

Případ 3: Odesílání binárních dat do připojení prostřednictvím rozhraní REST API s využitím Content-Type=application/octet-stream

  • Jednoduchý klient WebSocket obdrží binární rámec WebSocket s binárními daty.

  • Klient PubSub WebSocket přijímá:

    {
    "type": "message",
    "from": "server",
    "dataType" : "binary",
    "data": "<base64_binary>"
}

Systémová odpověď

Služba Web PubSub odesílá klientům zprávy související se systémem.

Připojeno

Zpráva odeslaná klientovi, když se klient úspěšně připojí:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

Odpojeno

Zpráva odeslaná klientovi, když server ukončí připojení nebo když služba klienta odmítne.

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

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