Compartir a través de

Subprotocolo de WebSocket JSON compatible con Azure Web PubSub

  • Artículo

El subprotocolo json WebSocket, json.webpubsub.azure.v1, permite el intercambio de mensajes de publicación o suscripción entre clientes a través del servicio sin un recorrido de ida y vuelta al servidor ascendente. Una conexión WebSocket mediante el json.webpubsub.azure.v1 subprotocolo se denomina cliente WebSocket de PubSub.

Información general

Una conexión WebSocket simple desencadena un message evento cuando envía mensajes y se basa en el lado servidor para procesar los mensajes y realizar otras operaciones.

Con el json.webpubsub.azure.v1 subprotocolo, puede crear clientes De PubSub WebSocket que pueden:

  • unirse a un grupo mediante solicitudes de unión.
  • publicar mensajes directamente en un grupo mediante solicitudes de publicación.
  • enrutar mensajes a diferentes controladores de eventos ascendentes mediante solicitudes de eventos.

Por ejemplo, puede crear un cliente WebSocket de PubSub con el código JavaScript siguiente:

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

En este documento se describen las solicitudes y respuestas de subprotocolos json.webpubsub.azure.v1 . Los marcos de datos entrantes y salientes deben contener cargas JSON.

Permisos

Un cliente webSocket de PubSub solo puede publicar en otros clientes cuando está autorizado. El roles objeto asignado al cliente determina los permisos concedidos al cliente:

Role Permiso
No especificado El cliente puede enviar solicitudes de eventos.
webpubsub.joinLeaveGroup El cliente puede unirse a cualquier grupo o abandonarlo.
webpubsub.sendToGroup El cliente puede publicar mensajes en cualquier grupo.
webpubsub.joinLeaveGroup.<group> El cliente puede unirse o dejar el grupo <group>.
webpubsub.sendToGroup.<group> El cliente puede publicar mensajes en el grupo <group>.

El servidor puede conceder o revocar dinámicamente permisos de cliente a través de api REST o SDK de servidor.

Requests

Unión a grupos

Formato:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}

Salida de grupos

Formato:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}

Publicar mensajes

Formato:

{
    "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 es la identidad de cada solicitud y debe ser única. El servicio envía un mensaje de respuesta de confirmación para notificar el resultado del proceso de la solicitud. Para obtener más información, consulte AckId y respuesta de Ack.
  • noEcho es opcional. Si se establece en true, este mensaje no se devuelve a la misma conexión. Si no se establece, el valor predeterminado es false.
  • dataType se puede establecer en json, texto binary:
    • json: data puede ser cualquier tipo que JSON admita y se publicará como lo que sea. Si dataType no se especifica, el valor predeterminado es json.
    • text: data debe estar en formato de cadena y se publicarán los datos de cadena.
    • binary: data debe estar en formato base64 y se publicarán los datos binarios.

Caso 1: publicar datos de texto:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • Los clientes subprotocolos de <group_name> recepción:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Los clientes webSocket simples de <group_name> reciben la cadena text data.

Caso 2: publicar datos JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Los clientes subprotocolos de <group_name> recepción:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Los clientes webSocket simples de <group_name> reciben la cadena {"hello": "world"}serializada .

Caso 3: publicar datos binarios:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • Los clientes subprotocolos de <group_name> recepción:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Los clientes webSocket simples en <group_name> reciben los datos binarios en el marco binario.

Envío de eventos personalizados

Formato:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}

dataType puede ser de tipo text, binary o json:

  • json: los datos pueden ser cualquier tipo que admita json y se publicarán como lo que es; El valor predeterminado es json.
  • text: los datos están en formato de cadena y se publicarán los datos de cadena;
  • binary: los datos están en formato base64 y se publicarán los datos binarios;

Caso 1: envío de eventos con datos de texto:

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

El controlador de eventos ascendente recibe datos similares a los siguientes:

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

El Content-Type para la solicitud HTTP de CloudEvents es text/plain cuando dataType es text.

Caso 2: envío de eventos con datos JSON:

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

El controlador de eventos ascendente recibe datos similares a los siguientes:

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

El Content-Type para la solicitud HTTP de CloudEvents es application/json cuando dataType es json

Caso 3: envío de eventos con datos binarios:

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

El controlador de eventos ascendente recibe datos similares a los siguientes:

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

El Content-Type para la solicitud HTTP de CloudEvents es application/octet-stream cuando dataType es binary. El marco de WebSocket puede tener formato text para marcos de mensajes de texto o binarios con codificación UTF8 para marcos de mensaje binary.

El servicio Web PubSub rechaza el cliente si el mensaje no coincide con el formato descrito.

Respuestas

Los tipos de mensaje recibidos por el cliente pueden ser:

  • ack: la respuesta a una solicitud que contiene .ackId
  • message: mensajes del grupo o servidor.
  • system: mensajes del servicio Web PubSub.

Respuesta de confirmación

Cuando la solicitud de cliente contiene ackId, el servicio devolverá una respuesta de confirmación para la solicitud. El cliente debe controlar el mecanismo de confirmación, esperando la respuesta de confirmación con una async await operación y usando una operación de tiempo de espera cuando la respuesta de confirmación no se recibe en un período determinado.

Formato:

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

La implementación del cliente debe comprobar siempre si success es true o false primero y, a continuación, solo leer el error cuando success es false.

Respuesta del mensaje

Los clientes pueden recibir mensajes publicados desde un grupo al que el cliente se ha unido o desde el servidor, que, funcionando en un rol de administración de servidores, envía mensajes a clientes o usuarios específicos.

  1. Cuando el mensaje es de un grupo.

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

  2. Cuando el mensaje es sea del servidor.

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

Caso 1: envío de datos Hello World a la conexión a través de la API REST con Content-Type=text/plain

  • Un cliente webSocket simple recibe un marco webSocket de texto con datos: Hello World;

  • Un cliente webSocket de PubSub recibe:

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

Caso 2: envío de datos { "Hello" : "World"} a la conexión a través de la API REST con Content-Type=application/json

  • Un cliente webSocket simple recibe un marco webSocket de texto con datos con cadena: { "Hello" : "World"}.

  • Un cliente webSocket de PubSub recibe:

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

Si la API REST envía una cadena Hello World mediante el tipo de contenido, el cliente webSocket simple recibe una cadena JSON, que se "Hello World" ajusta con comillas dobles ("application/json).

Caso 3: envío de datos binarios a la conexión a través de la API REST con Content-Type=application/octet-stream

  • Un cliente webSocket simple recibe un marco binario de WebSocket con los datos binarios.

  • Un cliente webSocket de PubSub recibe:

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

Respuesta del sistema

El servicio Web PubSub envía mensajes relacionados con el sistema a los clientes.

Conectado

Mensaje enviado al cliente cuando el cliente se conecta correctamente:

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

Escenario desconectado

Mensaje enviado al cliente cuando el servidor cierra la conexión o cuando el servicio rechaza el cliente.

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

Pasos siguientes

Use estos recursos para empezar a compilar su propia aplicación:

Tutorial: Publicación y suscripción de mensajes en Azure Web PubSub

Tutorial: Creación de una sala de chat simple con Azure Web PubSub

Tutorial: Uso de un subprotocolo compatible con el servicio para streaming de clientes

Tutorial: Creación de chat sin servidor con Azure Functions y Web PubSub

Tutorial: Configuración de un cliente de escucha de eventos

Reproducción con demostraciones dinámicas

Explore más ejemplos de Azure Web PubSub.