Subprotocolo JSON WebSocket suportado pelo Azure Web PubSub

Artigo
10/26/2023

O subprotocolo JSON WebSocket, json.webpubsub.azure.v1, permite a troca de mensagens de publicação/assinatura entre clientes através 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.

Descrição geral

Uma conexão WebSocket simples dispara 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:

Ingresse em um grupo usando solicitações de ingresso.
Publique mensagens diretamente em um grupo usando solicitações de publicação.
Encaminhe 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 úteis JSON.

Permissões

Um cliente PubSub WebSocket só pode publicar para outros clientes quando é autorizado. Os roles atribuídos ao cliente determinam as permissões concedidas ao cliente:

Role	Permissão
Não especificado	O cliente pode enviar solicitações de eventos.
`webpubsub.joinLeaveGroup`	O cliente pode entrar/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.

Pedidos do

Junte-se a grupos

Formato:

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

ackId é a identidade de cada pedido e deve ser única. 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 pedido e deve ser única. 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 pedido e deve ser única. 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 true, essa mensagem não será repercutida na mesma conexão. Se não estiver definido, o valor padrão será false.
dataType pode ser definido como json, textou binary:
- json: data pode ser qualquer tipo que o JSON suporta e será publicado como o que é; Se dataType não for especificado, o padrão será json.
- text: data deve estar em 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 recebem <group_name> :

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

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

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

Os clientes WebSocket simples em <group_name> receber a seqüência 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 recebem <group_name> :

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

Os clientes WebSocket simples em <group_name> receber 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 pedido e deve ser única. 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 dos text, binaryou json:

json: os dados podem ser de qualquer tipo que json suporta e serão publicados como o que são; O padrão é json.
text: os dados estão em formato de cadeia de caracteres e os dados da cadeia de caracteres 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 para o 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"
}

O Content-Type para a solicitação HTTP do 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 para o CloudEvents é application/octet-stream quando dataType é binary. O quadro WebSocket pode ser text formatado para quadros de mensagem de texto ou binários codificados UTF8 para binary quadros de mensagem.

O serviço Web PubSub recusa 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 um pedido que contém um ackIdficheiro .
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 ack, aguardando a resposta ack com uma async await operação e usando uma operação de tempo limite quando a resposta ack não é 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, em seguida, só ler o erro quando success é false.

Resposta à mensagem

Os clientes podem receber mensagens publicadas de um grupo ao qual o cliente aderiu 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 é do servidor.

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

Caso 1: Enviando dados `Hello World` para a conexão através 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: Enviando dados `{ "Hello" : "World"}` para a conexão através da API REST com `Content-Type`=`application/json`

Um cliente WebSocket simples recebe um quadro WebSocket de texto com dados stringificados: { "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: Enviando dados binários para a conexão através 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 clientes.

Ligado

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

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

Desligado

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óximos passos

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

Tutorial: Publicar e subscrever mensagens no Azure Web PubSub

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

Tutorial: Usar um subprotocolo suportado por serviço para streaming de cliente

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

Tutorial: Configurar um ouvinte de eventos

Jogue com demonstrações ao vivo

Explore mais exemplos do Azure Web PubSub

Partilhar via

Subprotocolo JSON WebSocket suportado pelo Azure Web PubSub

Descrição geral

Permissões

Pedidos do

Junte-se a 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:

Respostas

Resposta Ack

Resposta à mensagem

Caso 1: Enviando dados `Hello World` para a conexão através da API REST com `Content-Type`=`text/plain`

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

Caso 3: Enviando dados binários para a conexão através da API REST com `Content-Type`=`application/octet-stream`

Resposta do sistema

Ligado

Desligado

Próximos passos

Comentários

Recursos adicionais

Partilhar via

Subprotocolo JSON WebSocket suportado pelo Azure Web PubSub

Descrição geral

Permissões

Pedidos do

Junte-se a 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:

Respostas

Resposta Ack

Resposta à mensagem

Caso 1: Enviando dados Hello World para a conexão através da API REST com Content-Type=text/plain

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

Caso 3: Enviando dados binários para a conexão através da API REST com Content-Type=application/octet-stream

Resposta do sistema

Ligado

Desligado

Próximos passos

Comentários

Recursos adicionais

Caso 1: Enviando dados `Hello World` para a conexão através da API REST com `Content-Type`=`text/plain`

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

Caso 3: Enviando dados binários para a conexão através da API REST com `Content-Type`=`application/octet-stream`