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:

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 de WebSocket de PubSub solo puede publicar en otros clientes cuando está autorizado. El roles 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 al grupo <group> o abandonarlo.
webpubsub.sendToGroup.<group> El cliente puede publicar mensajes en el grupo <group>.

El servidor puede conceder o revocar los permisos de un cliente de forma dinámica por medio 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 Id. de confirmación y respuesta de confirmación
  • noEcho es opcional. Si se establece en true, este mensaje no se repite en la misma conexión. Si no se establece, el valor predeterminado es false.
  • Se puede establecer en dataType, json, text o 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 del subprotocolo en <group_name> reciben:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Los clientes de WebSocket simple en <group_name> reciben la cadena text data.

Caso 2: publicar datos JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Los clientes del subprotocolo en <group_name> reciben:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Los clientes de WebSocket simple en <group_name> reciben la cadena serializada {"hello": "world"}.

Caso 3: publicar datos binarios:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • Los clientes del subprotocolo en <group_name> reciben:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Los clientes de WebSocket simple 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 JSON admita y se publicará como lo que sea. 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:

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 valor Content-Type de la solicitud HTTP de CloudEvents es text/plain, donde 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:

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 valor Content-Type de la solicitud HTTP de CloudEvents es application/json, donde 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:

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 valor Content-Type de la solicitud HTTP de CloudEvents es application/octet-stream, donde 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 al cliente si el mensaje no coincide con el formato descrito.

Ping

Formato:

{
    "type": "ping",
}

El cliente puede enviar un ping mensaje al servicio para permitir que el servicio Web PubSub detecte la vida del cliente.

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.
  • pong: la respuesta a un ping mensaje.

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 de WebSocket binario 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.

Respuesta de Pong

El servicio Web PubSub envía un pong mensaje al cliente cuando recibe un ping mensaje del cliente.

Formato:

{
    "type": "pong",
}

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.