Compartilhar via

Subprotocolo WebSocket JSON com suporte no Azure Web PubSub

  • Artigo

O subprotocolo JSON WebSocket, json.webpubsub.azure.v1, permite a troca de mensagens de publicação/assinatura entre clientes por meio do serviço sem uma viagem de ida e volta para o servidor upstream. Uma conexão WebSocket usando o json.webpubsub.azure.v1 subprotocolo é chamada de cliente PubSub WebSocket.

Visão geral

Uma conexão WebSocket simples aciona um message evento quando envia mensagens e depende do lado do servidor para processar mensagens e fazer outras operações.

Com o json.webpubsub.azure.v1 subprotocolo, você pode criar clientes PubSub WebSocket que podem:

  • Participe de um grupo usando solicitações de ingresso.
  • Publique mensagens diretamente em um grupo usando solicitações de publicação.
  • Roteie mensagens para diferentes manipuladores de eventos upstream usando solicitações de eventos.

Por exemplo, você pode criar um cliente PubSub WebSocket com o seguinte código JavaScript:

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

Este documento descreve as solicitações e respostas do subprotocolo json.webpubsub.azure.v1 . Os quadros de dados de entrada e saída devem conter cargas JSON.

Permissões

Um cliente PubSub WebSocket só pode publicar em outros clientes quando estiver autorizado. O roles atribuído ao cliente determina as permissões concedidas ao cliente:

Função Permissão
Não especificado O cliente pode enviar solicitações de evento.
webpubsub.joinLeaveGroup O cliente pode ingressar/sair de qualquer grupo.
webpubsub.sendToGroup O cliente pode publicar mensagens em qualquer grupo.
webpubsub.joinLeaveGroup.<group> O cliente pode entrar/sair do grupo <group>.
webpubsub.sendToGroup.<group> O cliente pode publicar mensagens no grupo <group>.

O servidor pode conceder ou revogar dinamicamente permissões de cliente por meio de APIs REST ou SDKs de servidor.

Requests

Ingressar grupos

Formato:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId é a identidade de cada solicitação e deve ser exclusiva. O serviço envia uma mensagem de resposta ack para notificar o resultado do processo da solicitação. Para obter detalhes, consulte AckId e resposta Ack

Sair dos grupos

Formato:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId é a identidade de cada solicitação e deve ser exclusiva. O serviço envia uma mensagem de resposta ack para notificar o resultado do processo da solicitação. Para obter detalhes, consulte AckId e resposta Ack

Publicar mensagens

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 é a identidade de cada solicitação e deve ser exclusiva. O serviço envia uma mensagem de resposta ack para notificar o resultado do processo da solicitação. Para obter detalhes, consulte AckId e resposta Ack
  • noEcho é opcional. Se definido como true, essa mensagem não será ecoada de volta para a mesma conexão. Se não for definida, o valor padrão será falso.
  • dataType pode ser definido como json, text, ou binary:
    • json: data pode ser qualquer tipo que o JSON dá suporte e será publicado como ele é. Se dataType não for especificado, o padrão será json.
    • text: data deve estar no formato de cadeia de caracteres e os dados da cadeia de caracteres serão publicados;
    • binary: data deve estar no formato base64 e os dados binários serão publicados;

Caso 1: publicar dados de texto:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • Os clientes do subprotocolo em <group_name> receive:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Os clientes WebSocket simples recebem <group_name> a cadeia de caracteres text data.

Caso 2: publicar dados JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Os clientes do subprotocolo em <group_name> receive:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Os clientes WebSocket simples recebem <group_name> a cadeia de caracteres {"hello": "world"}serializada.

Caso 3: publicar dados binários:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • Os clientes do subprotocolo em <group_name> receive:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Os clientes WebSocket simples recebem <group_name> os dados binários no quadro binário.

Enviar 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 
}
  • ackId é a identidade de cada solicitação e deve ser exclusiva. O serviço envia uma mensagem de resposta ack para notificar o resultado do processo da solicitação. Para obter detalhes, consulte AckId e resposta Ack

dataType pode ser um de text, binary ou json:

  • json: os dados podem ser de qualquer tipo que o JSON suporte e serão publicados como são; O padrão é json.
  • text: os dados estão no formato de string e os dados da string serão publicados;
  • binary: os dados estão no formato base64 e os dados binários serão publicados;

Caso 1: enviar evento com dados de texto:

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

O manipulador de eventos upstream recebe dados semelhantes 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

A Content-Type solicitação HTTP do CloudEvents é text/plain quando dataType é text.

Caso 2: enviar evento com dados JSON:

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

O manipulador de eventos upstream recebe dados semelhantes 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"
}

A Content-Type solicitação HTTP para o CloudEvents é application/json quando dataType é json

Caso 3: enviar evento com dados binários:

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

O manipulador de eventos upstream recebe dados semelhantes 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

A Content-Type solicitação HTTP do CloudEvents é application/octet-stream quando dataType é binary. O quadro WebSocket pode ser o formato text para os quadros de mensagem de texto ou binários codificados UTF8 para quadros de mensagem binary.

O serviço Web PubSub recusará o cliente se a mensagem não corresponder ao formato descrito.

Respostas

Os tipos de mensagem recebidos pelo cliente podem ser:

  • ack - A resposta a uma solicitação que contém um ackIdarquivo .
  • message - Mensagens do grupo ou servidor.
  • system - Mensagens do serviço Web PubSub.

Resposta Ack

Quando a solicitação do cliente contiver ackId, o serviço retornará uma resposta ack para a solicitação. O cliente deve lidar com o mecanismo de confirmação, aguardando a resposta de confirmação com uma async await operação e usando uma operação de tempo limite quando a resposta de confirmação não for recebida em um determinado período.

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

A implementação do cliente DEVE sempre verificar se o success é true ou false primeiro, então só leia o erro quando success estiver false.

Resposta da mensagem

Os clientes podem receber mensagens publicadas de um grupo ao qual o cliente ingressou ou do servidor, que, operando em uma função de gerenciamento de servidor, envia mensagens para clientes ou usuários específicos.

  1. Quando a mensagem é de um grupo

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

  2. Quando a mensagem é de um servidor,

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

Casa 1: enviar dados Hello World para conexão por meio da API REST com Content-Type=text/plain

  • Um cliente WebSocket simples recebe um quadro WebSocket de texto com dados: Hello World;

  • Um cliente PubSub WebSocket recebe:

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

Caso 2: enviar dados { "Hello" : "World"} para a conexão API REST com Content-Type=application/json

  • Um cliente WebSocket simples recebe um quadro WebSocket de texto com dados em cadeia de caracteres: { "Hello" : "World"}.

  • Um cliente PubSub WebSocket recebe:

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

Se a API REST estiver enviando uma cadeia de caracteres Hello World usando application/json o tipo de conteúdo, o cliente WebSocket simples receberá uma cadeia de caracteres JSON, que é "Hello World" encapsulada com aspas duplas (").

Caso 3: enviar dados binários para a conexão por meio da API REST com Content-Type=application/octet-stream

  • Um cliente WebSocket simples recebe um quadro WebSocket binário com os dados binários.

  • Um cliente PubSub WebSocket recebe:

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

Resposta do sistema

O serviço Web PubSub envia mensagens relacionadas ao sistema para os clientes.

Conectado

A mensagem enviada ao cliente quando o cliente se conecta com êxito:

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

Desconectado

A mensagem enviada ao cliente quando o servidor fecha a conexão ou quando o serviço recusa o cliente.

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

Próximas etapas

Use estes recursos para começar a criar seu aplicativo:

Tutorial: Publicar e assinar mensagens no Azure Web PubSub

Tutorial: criar uma sala de chat simples com o Azure Web PubSub

Tutorial: Usar um subprotocolo com suporte do serviço para streaming de cliente

Tutorial: Criar um chat sem servidor com o Azure Functions e o Web PubSub

Tutorial: Configurar um ouvinte de eventos

Experimentar demonstrações ao vivo

Explorar mais exemplos do Azure Web PubSub