Azure Web PubSub-stödd JSON WebSocket-delprotokol

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:

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>.
webpubsub.joinLeaveGroups.<pattern> Klienten kan ansluta/lämna valfri grupp vars namn matchar <pattern> (se Mönster för jokerteckengrupproll).
webpubsub.sendToGroups.<pattern> Klienten kan publicera meddelanden till alla grupper vars namn matchar <pattern> (se Mönster för jokerteckengrupproll).

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

Anmärkning

Jokerteckenroller (t.ex. webpubsub.sendToGroups.<pattern>) stöds inte i REST-API:er eller server-SDK:er under körning ännu.

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.

Börja strömma meddelanden

För att starta en gruppström, skicka en sendToGroup förfrågan med egenskapen stream . En strömstartsförfrågan innehåller datainte , dataType, eller ackId.

Format:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "noEcho": true|false,
    "stream": {
        "streamId": "<stream_id>",
        "idleTimeoutMs": 300000
    }
}
  • stream.streamId är identifieraren för den logiska strömmen. Det måste vara en icke-tom sträng och vara unik bland aktiva strömmar på samma klientanslutning. Klientbibliotek rekommenderas för att generera ett globalt unikt värde, såsom en GUID eller UUID.
  • stream.idleTimeoutMs är valfritt. Om specificerat måste den vara större än 0. Om den utelämnas är servicestandarden millisekunder 300000 . Värdet är en inaktiv timeout, inte en total strömlivslängd. Skicka strömdata, skicka en ström som hålls vid liv, eller avsluta strömmen innan denna timeout går ut när applikationen behöver hålla strömmen öppen.
  • noEcho är valfritt. Om det är sant inställt på true skickas inte streammeddelanden tillbaka till samma anslutning. Om det inte anges är standardvärdet falskt.

När strömmen accepteras får klienten ett ström-ack-svar med expectedSequenceId satt till 1.

Skicka strömmande data

För att skicka strömdata, skicka en streamData förfrågan med streamId, streamSequenceId, dataType, och data.

Format:

{
    "type": "streamData",
    "streamId": "<stream_id>",
    "streamSequenceId": 1,
    "dataType" : "json|text|binary",
    "data": {}
}
  • streamId identifierar en aktiv ström på samma klientanslutning.
  • streamSequenceId är ett positivt UINT64-tal. Det första datafragmentet i en ström använder 1, och varje efterföljande datafragment för samma streamId ökar med exakt 1.
  • dataType kan sättas till json, text, eller binary, med samma datakodningsregler som publiceringsmeddelanden.

För att hålla en ström aktiv utan att leverera data till prenumeranter, skicka en streamData förfrågan med endast type och streamId.

{
    "type": "streamData",
    "streamId": "<stream_id>"
}

Avsluta strömningsmeddelanden

För att avsluta en stream, skicka en streamEnd förfrågan.

Format:

{
    "type": "streamEnd",
    "streamId": "<stream_id>"
}

För att avsluta en ström med ett applikationsdefinierat fel, inkludera den valfria error egenskapen.

{
    "type": "streamEnd",
    "streamId": "<stream_id>",
    "error": {
        "message": "<error_detail>",
        "userErrorCode": "<application_error_code>"
    }
}
  • error.message är ett valfritt mänskligt läsbart felmeddelande.
  • error.userErrorCode är en valfri felkod definierad av applikationen.

När strömmen stängs får utgivaren ett svar om strömmen stängd.

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 text/plain är dataTypetext.

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 application/json är dataTypejson

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 application/octet-stream är dataTypebinary. 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.
  • streamAck – Svaret som bekräftar accepterad strömdata och rapporterar nästa förväntade strömsekvens-ID.
  • streamNack – Svaret vid ett återkallbart strömfel.
  • streamClosed – Svaret på terminalens publiceringssida av stream.

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

Svar på strömmande meddelande

När ett meddelande tillhör en ström innehåller gruppmeddelandet en stream egenskap.

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data": {},
    "fromUserId": "abc",
    "stream": {
        "streamId": "<stream_id>",
        "streamSequenceId": 1,
        "endOfStream": true,
        "error": {
            "name": "IdleTimeout|InternalServerError|Forbidden|Cancelled|UserError",
            "message": "<error_detail>",
            "userErrorCode": "<application_error_code>"
        }
    }
}
  • stream.streamId är den logiska strömidentifieraren.
  • stream.streamSequenceId är sekvensnumret för meddelandet i strömmen.
  • stream.endOfStream är valfritt. När det sätts till trueär meddelandet strömmens terminalmeddelande.
  • stream.error är valfritt och finns endast när strömmen avslutas med ett fel. userErrorCode är endast närvarande för UserError.

Stream ack-respons

Tjänsten skickar ett streamAck svar för att bekräfta accepterad strömdata och rapportera nästa strömsekvens-ID den förväntar sig.

Format:

{
    "type": "streamAck",
    "streamId": "<stream_id>",
    "expectedSequenceId": 2
}

Stream nack-respons

Tjänsten skickar ett streamNack svar på ett återförhållbart strömfel.

Format:

{
    "type": "streamNack",
    "streamId": "<stream_id>",
    "expectedSequenceId": 2,
    "name": "InvalidSequenceId|TransientError",
    "message": "<error_detail>"
}

Strömstängt respons

Tjänsten skickar ett streamClosed svar när strömmen på publicistsidan stängs.

Format:

{
    "type": "streamClosed",
    "streamId": "<stream_id>",
    "error": {
        "name": "StreamNotFound|Forbidden|BadRequest|InternalServerError|IdleTimeout",
        "message": "<error_detail>"
    }
}

Fastigheten error utelämnas när bäcken stängs normalt.

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

  • Last updated on