Azure Web PubSub Reliable JSON WebSocket subprotocol

JSON WebSocket-delprotokol json.reliable.webpubsub.azure.v1, , möjliggör ett mycket tillförlitligt utbyte av publicera/prenumerera meddelanden direkt mellan klienter via tjänsten utan en tur och retur till den överordnade servern.

Det här dokumentet beskriver delprotokolen json.reliable.webpubsub.azure.v1.

När WebSocket-klientanslutningar tas bort på grund av tillfälliga nätverksproblem kan meddelanden gå förlorade. I ett pub-/undersystem frikopplas utgivare från prenumeranter och kanske inte identifierar en prenumerants förlorade anslutning eller meddelandeförlust.

För att lösa tillfälliga nätverksproblem och upprätthålla tillförlitlig meddelandeleverans kan du använda underprotokolen Azure WebPubSub json.reliable.webpubsub.azure.v1 för att skapa en Reliable PubSub WebSocket-klient.

En Reliable PubSub WebSocket-klient kan:

  • återställa en anslutning från tillfälliga nätverksproblem.
  • återställa från meddelandeförlust.
  • gå med i en grupp med hjälp av anslutningsbegäranden.
  • lämna en grupp med hjälp av ledighetsbegäranden.
  • publicera meddelanden direkt till en grupp med publiceringsbegäranden.
  • dirigera meddelanden direkt till överordnade händelsehanterare med hjälp av händelsebegäranden.

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

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

Se Skapa tillförlitliga klienter för att implementera återanslutning och meddelandetillförlitlighet för utgivare och prenumerantklienter.

När klienten använder den här subprotokolen måste både utgående och inkommande dataramar 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.

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.

Sekvens-Ack

Format:

{
    "type": "sequenceAck",
    "sequenceId": "<sequenceId>",
}

Reliable PubSub WebSocket-klienten måste skicka ett sekvens-ack-meddelande när det tar emot ett meddelande från tjänsten. Mer information finns i Skapa tillförlitliga klienter

  • sequenceId är ett inkrementellt uint64-nummer från det mottagna meddelandet.

Svar

Meddelanden som tas emot av klienten kan vara flera typer: ack, message, systemoch pong. Meddelanden med typ message har sequenceId en egenskap. Klienten måste skicka en Sekvens-Ack till tjänsten när den har fått ett meddelande.

Ack-svar

När begäran innehåller returnerar ackIdtjänsten ett ack-svar för den här begäran. Klientimplementeringen bör hantera den här ack-mekanismen, inklusive att vänta på ack-svaret med hjälp av en asyncawait åtgärd, och ha en timeout-hanterare 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 den success är true eller false den första. Endast när success är false klienten läser från error.

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. Svarsmeddelandet från en grupp:

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

  2. Svarsmeddelandet från servern:

    {
    "sequenceId": 1,
    "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 meddelandet i JSON:

    {
    "sequenceId": 1,
    "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 meddelandet i JSON:

    {
    "sequenceId": 1,
    "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 tar den enkla WebSocket-klienten emot JSON-strängen "Hello World" omsluten i ".

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 meddelandet i JSON:

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

Systemsvar

Web PubSub-tjänsten kan returnera systemrelaterade svar till klienten.

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

Svaret på klientanslutningsbegäran:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
    "reconnectionToken": "<token>"
}

connectionId och reconnectionToken används för återanslutning. Gör en anslutningsbegäran med URI för återanslutning:

wss://<service-endpoint>/client/hubs/<hub>?awps_connection_id=<connectionId>&awps_reconnection_token=<reconnectionToken>

Mer information finns i Anslutningsåterställning

Frånkopplad

Svaret när servern stänger anslutningen eller när tjänsten nekar klientanslutningen:

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