Dela via

Azure Web PubSub-stödd JSON WebSocket-delprotokol

  • Artikel

JSON WebSocket-delprotokol json.webpubsub.azure.v1, , möjliggör utbyte av publicera/prenumerera meddelanden mellan klienter via tjänsten utan en tur och retur till den överordnade servern. En WebSocket-anslutning med hjälp av delprotokolen json.webpubsub.azure.v1 kallas för en PubSub WebSocket-klient.

Översikt

En enkel WebSocket-anslutning utlöser en message händelse när den skickar meddelanden och förlitar sig på serversidan för att bearbeta meddelanden och utföra andra åtgärder.

Med subprotokolen json.webpubsub.azure.v1 kan du skapa PubSub WebSocket-klienter som kan:

  • gå med i en grupp med hjälp av anslutningsbegäranden.
  • publicera meddelanden direkt till en grupp med publiceringsbegäranden.
  • dirigera meddelanden till olika överordnade händelsehanterare med hjälp av händelsebegäranden.

Du kan till exempel skapa en PubSub WebSocket-klient med följande JavaScript-kod:

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

I det här dokumentet beskrivs undergruppsbegäranden json.webpubsub.azure.v1 och svar. Både inkommande och utgående dataramar måste innehålla JSON-nyttolaster.

Behörigheter

En PubSub WebSocket-klient kan bara publicera till andra klienter när den är auktoriserad. Den roles tilldelade klienten avgör vilka behörigheter som beviljats klienten:

Roll Behörighet
Har inte angetts Klienten kan skicka händelsebegäranden.
webpubsub.joinLeaveGroup Klienten kan ansluta/lämna valfri grupp.
webpubsub.sendToGroup Klienten kan publicera meddelanden till valfri grupp.
webpubsub.joinLeaveGroup.<group> Klienten kan ansluta/lämna gruppen <group>.
webpubsub.sendToGroup.<group> Klienten kan publicera meddelanden till gruppen <group>.

Servern kan dynamiskt bevilja eller återkalla klientbehörigheter via REST-API:er eller server-SDK:er.

begäranden

Koppla grupper

Format:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId är identiteten för varje begäran och bör vara unik. Tjänsten skickar ett ack-svarsmeddelande för att meddela processresultatet för begäran. Mer information finns i AckId och Ack-svar

Lämna grupper

Format:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId är identiteten för varje begäran och bör vara unik. Tjänsten skickar ett ack-svarsmeddelande för att meddela processresultatet för begäran. Mer information finns i AckId och Ack-svar

Publicera meddelanden

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 är identiteten för varje begäran och bör vara unik. Tjänsten skickar ett ack-svarsmeddelande för att meddela processresultatet för begäran. Mer information finns i AckId och Ack-svar
  • noEcho är valfritt. Om värdet är true upprepas inte det här meddelandet till samma anslutning. Om det inte anges är standardvärdet falskt.
  • dataType kan anges till json, texteller binary:
    • json: data kan vara vilken typ som helst som JSON stöder och publiceras som vad det är. Om dataType inte har angetts är standardvärdet json.
    • text: data ska vara i strängformat och strängdata publiceras.
    • binary: data bör vara i base64-format och binära data publiceras.

Fall 1: Publicera textdata:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • De subprotokolklienter som finns i <group_name> tar emot:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • De enkla WebSocket-klienterna i <group_name> tar emot strängen text data.

Fall 2: Publicera JSON-data:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • De subprotokolklienter som finns i <group_name> tar emot:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • De enkla WebSocket-klienterna i <group_name> tar emot den serialiserade strängen {"hello": "world"}.

Fall 3: Publicera binära data:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • De subprotokolklienter som finns i <group_name> tar emot:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • De enkla WebSocket-klienterna i <group_name> tar emot binära data i den binära ramen.

Skicka anpassade händelser

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 är identiteten för varje begäran och bör vara unik. Tjänsten skickar ett ack-svarsmeddelande för att meddela processresultatet för begäran. Mer information finns i AckId och Ack-svar

dataType kan vara en av text, binaryeller json:

  • json: data kan vara alla typer av json-stöd och publiceras som vad de är. Standardvärdet är json.
  • text: data är i strängformat och strängdata publiceras.
  • binary: data är i base64-format och binära data publiceras.

Fall 1: Skicka händelse med textdata:

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

Den överordnade händelsehanteraren tar emot data som liknar:

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

Content-Type HTTP-begäran för CloudEvents är när dataType är text/plain text.

Fall 2: Skicka händelse med JSON-data:

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

Den överordnade händelsehanteraren tar emot data som liknar:

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

Content-Type HTTP-begäran för CloudEvents är när dataType är application/jsonjson

Fall 3: Skicka händelse med binära data:

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

Den överordnade händelsehanteraren tar emot data som liknar:

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

Content-Type HTTP-begäran för CloudEvents är när dataType är application/octet-stream binary. WebSocket-ramen kan vara text formaterad för textmeddelanderamar eller UTF8-kodade binärfiler för binary meddelanderamar.

Web PubSub-tjänsten nekar klienten om meddelandet inte matchar det beskrivna formatet.

Ping

Format:

{
    "type": "ping",
}

Klienten kan skicka ett ping meddelande till tjänsten för att göra det möjligt för Web PubSub-tjänsten att identifiera klientens livskraft.

Svar

Meddelandetyper som tas emot av klienten kan vara:

  • ack – Svaret på en begäran som innehåller en ackId.
  • message – Meddelanden från gruppen eller servern.
  • system – Meddelanden från Web PubSub-tjänsten.
  • pong – Svaret på ett ping meddelande.

Ack-svar

När klientbegäran innehåller returnerar ackIdtjänsten ett ack-svar för begäran. Klienten ska hantera ack-mekanismen genom att vänta på ack-svaret med en async await åtgärd och använda en timeout-åtgärd när ack-svaret inte tas emot under en viss period.

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

Klientimplementeringen SKA alltid kontrollera om success är true eller false först och sedan bara läsa felet när success är false.

Meddelandesvar

Klienter kan ta emot meddelanden som publicerats från en grupp som klienten har anslutit eller från servern, som i en serverhanteringsroll skickar meddelanden till specifika klienter eller användare.

  1. När meddelandet kommer från en grupp

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

  2. När meddelandet kommer från servern.

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

Fall 1: Skicka data Hello World till anslutningen via REST API med Content-Type=text/plain

  • En enkel WebSocket-klient tar emot en WebSocket-textram med data: Hello World;

  • En PubSub WebSocket-klient tar emot:

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

Fall 2: Skicka data { "Hello" : "World"} till anslutningen via REST API med Content-Type=application/json

  • En enkel WebSocket-klient tar emot en WebSocket-textram med strängifierade data: { "Hello" : "World"}.

  • En PubSub WebSocket-klient tar emot:

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

Om REST-API:et skickar en sträng Hello World med hjälp av application/json innehållstypen får den enkla WebSocket-klienten en JSON-sträng, som är "Hello World" omsluten med dubbla citattecken (").

Fall 3: Skicka binära data till anslutningen via REST API med Content-Type=application/octet-stream

  • En enkel WebSocket-klient tar emot en binär WebSocket-ram med binära data.

  • En PubSub WebSocket-klient tar emot:

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

Systemsvar

Tjänsten Web PubSub skickar systemrelaterade meddelanden till klienter.

Pong-svar

Tjänsten Web PubSub skickar ett pong meddelande till klienten när den tar emot ett ping meddelande från klienten.

Format:

{
    "type": "pong",
}

Connected

Meddelandet som skickas till klienten när klienten ansluter:

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

Frånkopplad

Meddelandet som skickas till klienten när servern stänger anslutningen eller när tjänsten nekar klienten.

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

Nästa steg

Använd dessa resurser för att börja skapa ett eget program:

Självstudie: Publicera och prenumerera på meddelanden i Azure Web PubSub

Självstudie: Skapa ett enkelt chattrum med Azure Web PubSub

Självstudie: Använda en underprotokol som stöds av tjänsten för klientströmning

Självstudie: Skapa serverlös chatt med Azure Functions och Web PubSub

Självstudie: Konfigurera en händelselyssnare

Spela upp med livedemonstrationer

Utforska fler Azure Web PubSub-exempel