Udostępnij za pośrednictwem

Usługa Azure Web PubSub obsługiwana podprotocol protokołu JSON WebSocket

  • Artykuł

Podprotocol json.webpubsub.azure.v1protokołu JSON WebSocket umożliwia wymianę komunikatów publikowania/subskrybowania między klientami za pośrednictwem usługi bez rundy na serwerze nadrzędnym. Połączenie protokołu WebSocket przy użyciu json.webpubsub.azure.v1 podprotokolu jest nazywane klientem protokołu WebSocket PubSub.

Omówienie

Proste połączenie protokołu WebSocket wyzwala message zdarzenie podczas wysyłania komunikatów i opiera się na stronie serwera w celu przetwarzania komunikatów i wykonywania innych operacji.

Za pomocą json.webpubsub.azure.v1 podprotocol można utworzyć klientów protokołu WebSocket PubSub, którzy mogą:

  • dołącz do grupy przy użyciu żądań dołączenia.
  • publikowanie komunikatów bezpośrednio w grupie przy użyciu żądań publikowania.
  • kierowanie komunikatów do różnych programów obsługi zdarzeń nadrzędnych przy użyciu żądań zdarzeń.

Możesz na przykład utworzyć klienta protokołu WebSocket PubSub przy użyciu następującego kodu JavaScript:

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

W tym dokumencie opisano żądania i odpowiedzi subprotocol json.webpubsub.azure.v1 . Ramki danych przychodzących i wychodzących muszą zawierać ładunki JSON.

Uprawnienia

Klient protokołu WebSocket PubSub może publikować tylko na innych klientach, gdy jest autoryzowany. Przypisany roles do klienta określ uprawnienia przyznane klientowi:

Rola Uprawnienie
Nieokreślona Klient może wysyłać żądania zdarzeń.
webpubsub.joinLeaveGroup Klient może dołączyć/pozostawić dowolną grupę.
webpubsub.sendToGroup Klient może publikować komunikaty w dowolnej grupie.
webpubsub.joinLeaveGroup.<group> Klient może dołączyć/opuścić grupę <group>.
webpubsub.sendToGroup.<group> Klient może publikować komunikaty w grupie <group>.

Serwer może dynamicznie udzielać lub odwoływać uprawnienia klienta za pośrednictwem interfejsów API REST lub zestawów SDK serwera.

Żądania

Dołączanie grup

Format:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId to tożsamość każdego żądania i powinna być unikatowa. Usługa wysyła komunikat odpowiedzi ack, aby powiadomić wynik procesu żądania. Aby uzyskać szczegółowe informacje, zobacz AckId i Ack Response

Pozostaw grupy

Format:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId to tożsamość każdego żądania i powinna być unikatowa. Usługa wysyła komunikat odpowiedzi ack, aby powiadomić wynik procesu żądania. Aby uzyskać szczegółowe informacje, zobacz AckId i Ack Response

Publikowanie komunikatów

Format:

{
    "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 to tożsamość każdego żądania i powinna być unikatowa. Usługa wysyła komunikat odpowiedzi ack, aby powiadomić wynik procesu żądania. Aby uzyskać szczegółowe informacje, zobacz AckId i Ack Response
  • Element noEcho jest opcjonalny. Jeśli ustawiono wartość true, ten komunikat nie jest ponownie zwracany do tego samego połączenia. Jeśli nie zostanie ustawiona, wartość domyślna to false.
  • dataType można ustawić na json, textlub binary:
    • json: data może być dowolnym typem, który obsługuje kod JSON i będzie publikowany jako to, co to jest; Jeśli dataType nie zostanie określony, wartość domyślna to json.
    • text: data powinien być w formacie ciągu, a dane ciągu zostaną opublikowane;
    • binary: data powinien być w formacie base64, a dane binarne zostaną opublikowane;

Przypadek 1: publikowanie danych tekstowych:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • Klienci subprotocol w <group_name> odbieraniu:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Prosti klienci protokołu WebSocket w <group_name> programie otrzymują ciąg text data.

Przypadek 2: publikowanie danych JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Klienci subprotocol w <group_name> odbieraniu:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Prosti klienci protokołu WebSocket w <group_name> programie otrzymują serializowany ciąg {"hello": "world"}.

Przypadek 3. Publikowanie danych binarnych:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • Klienci subprotocol w <group_name> odbieraniu:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Prosti klienci protokołu WebSocket odbierają <group_name> dane binarne w ramce binarnej .

Wysyłanie zdarzeń niestandardowych

Format:

{
    "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 to tożsamość każdego żądania i powinna być unikatowa. Usługa wysyła komunikat odpowiedzi ack, aby powiadomić wynik procesu żądania. Aby uzyskać szczegółowe informacje, zobacz AckId i Ack Response

dataType może być jednym z textelementów , binarylub json:

  • json: dane mogą być dowolnym typem obsługiwane w formacie JSON i będą publikowane jako to, co to jest; Wartość domyślna to json.
  • text: dane są w formacie ciągu, a dane ciągu zostaną opublikowane;
  • binary: dane są w formacie base64, a dane binarne zostaną opublikowane;

Przypadek 1: wysyłanie zdarzenia z danymi tekstowymi:

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

Program obsługi zdarzeń nadrzędnych odbiera dane podobne do następujących:

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

Wartość Content-Type dla żądania HTTP cloudEvents to , gdy dataType ma wartość text/plain text.

Przypadek 2: wysyłanie zdarzenia z danymi JSON:

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

Program obsługi zdarzeń nadrzędnych odbiera dane podobne do następujących:

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

Wartość Content-Type dla żądania HTTP cloudEvents to, gdy dataType jest application/jsonjson

Przypadek 3: wysyłanie zdarzenia z danymi binarnymi:

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

Program obsługi zdarzeń nadrzędnych odbiera dane podobne do następujących:

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

Wartość Content-Type dla żądania HTTP cloudEvents to , gdy dataType ma wartość application/octet-stream binary. Ramka Protokołu WebSocket może być text formatowana dla ramek wiadomości tekstowych lub plików binarnych zakodowanych w formacie UTF8 dla binary ramek komunikatów.

Usługa Web PubSub odrzuca klienta, jeśli komunikat nie jest zgodny z opisanym formatem.

Polecenie ping

Format:

{
    "type": "ping",
}

Klient może wysłać ping komunikat do usługi, aby umożliwić usłudze Web PubSub wykrywanie aktywności klienta.

Odpowiedzi

Typy komunikatów odebrane przez klienta mogą być następujące:

  • ack — odpowiedź na żądanie zawierające element ackId.
  • message — komunikaty z grupy lub serwera.
  • system — komunikaty z usługi Web PubSub.
  • pong - odpowiedź na ping wiadomość.

Odpowiedź Ack

Gdy żądanie klienta zawiera ackIdelement , usługa zwróci odpowiedź ack dla żądania. Klient powinien obsługiwać mechanizm ack, czekając na odpowiedź ack z async await operacją i używając operacji przekroczenia limitu czasu, gdy odpowiedź ack nie zostanie odebrana w określonym okresie.

Format:

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

Implementacja klienta POWINNA zawsze sprawdzać, czy success element jest true lub false pierwszy, a następnie odczytywać błąd tylko wtedy, gdy success ma wartość false.

Odpowiedź na komunikat

Klienci mogą odbierać komunikaty publikowane z grupy, do której klient dołączył lub z serwera, który działa w roli zarządzania serwerem, wysyła komunikaty do określonych klientów lub użytkowników.

  1. Gdy komunikat pochodzi z grupy

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

  2. Gdy komunikat pochodzi z serwera.

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

Przypadek 1: Wysyłanie danych Hello World do połączenia za pośrednictwem interfejsu API REST za pomocą polecenia Content-Type=text/plain

  • Prosty klient protokołu WebSocket otrzymuje tekstową ramkę protokołu WebSocket z danymi: Hello World;

  • Klient protokołu WebSocket PubSub otrzymuje:

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

Przypadek 2: Wysyłanie danych { "Hello" : "World"} do połączenia za pośrednictwem interfejsu API REST za pomocą polecenia Content-Type=application/json

  • Prosty klient protokołu WebSocket otrzymuje tekstową ramkę protokołu WebSocket z danymi ciągowymi: { "Hello" : "World"}.

  • Klient protokołu WebSocket PubSub otrzymuje:

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

Jeśli interfejs API REST wysyła ciąg przy użyciu application/json typu zawartości, prosty klient protokołu WebSocket otrzymuje ciąg Hello World JSON, który jest "Hello World" owinięty podwójnymi cudzysłowami (").

Przypadek 3. Wysyłanie danych binarnych do połączenia za pośrednictwem interfejsu API REST za pomocą polecenia Content-Type=application/octet-stream

  • Prosty klient protokołu WebSocket otrzymuje binarną ramkę protokołu WebSocket z danymi binarnymi.

  • Klient protokołu WebSocket PubSub otrzymuje:

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

Odpowiedź systemu

Usługa Web PubSub wysyła komunikaty związane z systemem do klientów.

Odpowiedź na ponga

Usługa Web PubSub wysyła pong komunikat do klienta po odebraniu ping komunikatu z klienta.

Format:

{
    "type": "pong",
}

Połączono

Komunikat wysłany do klienta po pomyślnym nawiązaniu połączenia z klientem:

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

Odłączony

Komunikat wysłany do klienta, gdy serwer zamknie połączenie lub gdy usługa odrzuci klienta.

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

Następne kroki

Użyj tych zasobów, aby rozpocząć tworzenie własnej aplikacji:

Samouczek: publikowanie i subskrybowanie komunikatów w usłudze Azure Web PubSub

Samouczek: tworzenie prostego czatroomu za pomocą usługi Azure Web PubSub

Samouczek: używanie podprotokolu obsługiwanego przez usługę na potrzeby przesyłania strumieniowego klienta

Samouczek: tworzenie czatu bezserwerowego za pomocą usług Azure Functions i Web PubSub

Samouczek: konfigurowanie odbiornika zdarzeń

Odtwarzanie z pokazami na żywo

Zapoznaj się z więcej przykładów usługi Azure Web PubSub