Subprotocolo WebSocket JSON com suporte no Azure Web PubSub

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:

ingressar em um grupo usando solicitações de junção;
publicar 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 WebSocket PubSub só pode publicar em outros clientes quando estiver autorizado. O atribuído roles 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 ingressar/sair do grupo `<group>`.
`webpubsub.sendToGroup.<group>`	O cliente pode publicar mensagens no grupo `<group>`.

O servidor pode conceder ou revogar dinamicamente as permissões do cliente pelas 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 Ack Response

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 Ack Response

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 Ack Response
noEcho é opcional. Se definida como verdadeira, 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> recebem:

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}

Os clientes WebSocket simples em <group_name> recebem 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> recebem:

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}

Os clientes WebSocket simples em <group_name> recebem a cadeia de caracteres serializada {"hello": "world"}.

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> recebem:

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

Os clientes WebSocket simples em <group_name> recebem 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 Ack Response

dataType pode ser um de text, binary ou json:

json: os dados podem ser qualquer tipo para o qual o JSON dá suporte e serão publicados como eles são. O padrão é json.
text: os dados estão no formato de cadeia de caracteres e os dados da cadeia de caracteres serão publicados;
binary: os dados devem estar 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 uma solicitação semelhante 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

O Content-Type da solicitação HTTP do CloudEvents é text/plain, em que 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 uma solicitação semelhante 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"
}

O Content-Type da solicitação HTTP do CloudEvents é application/json, em que 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 uma solicitação semelhante 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

O Content-Type da solicitação HTTP do CloudEvents é application/octet-stream, em que 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.

Ping

Formato:

{
    "type": "ping",
}

O cliente pode enviar uma mensagem de ping para o serviço para habilitar o serviço Web PubSub a detectar a atividade do cliente.

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.
pong - A resposta a uma ping mensagem.

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 asyncawait 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 que 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.

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

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 os 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.

Resposta Pong

O serviço Web PubSub envia uma mensagem de pong para o cliente quando ele recebe uma mensagem de ping do cliente.

Formato:

{
    "type": "pong",
}

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

Comentários

Esta página foi útil?

Last updated on 2025-01-03

Compartilhar via

Subprotocolo WebSocket JSON com suporte no Azure Web PubSub

Visão geral

Permissões

Requests

Ingressar grupos

Sair dos grupos

Publicar mensagens

Caso 1: publicar dados de texto:

Caso 2: publicar dados JSON:

Caso 3: publicar dados binários:

Enviar eventos personalizados

Caso 1: enviar evento com dados de texto:

Caso 2: enviar evento com dados JSON:

Caso 3: enviar evento com dados binários:

Ping

Respostas

Resposta Ack

Resposta da mensagem

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

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

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

Resposta do sistema

Resposta Pong

Conectado

Desconectado

Próximas etapas

Comentários

Recursos adicionais

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

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

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