Protocolos de cliente WebSocket para o Azure Web PubSub
Os clientes conectam-se ao Azure Web PubSub usando o protocolo padrão WebSocket.
Pontos de extremidade de serviço
O serviço Web PubSub fornece dois tipos de pontos de extremidade para conexão dos clientes:
/client/hubs/{hub}
/client/?hub={hub}
{hub}
é um parâmetro obrigatório que funciona como isolamento para vários aplicativos. Defina-o no caminho ou na consulta.
Autorização
Os clientes se conectam ao serviço com um JWT (Token Web JSON). O token pode estar na cadeia de consulta, como /client/?hub={hub}&access_token={token}
, ou como o cabeçalho Authorization
, como Authorization: Bearer {token}
.
Aqui está um fluxo de trabalho de autorização geral:
- O cliente faz a negociação com o servidor de aplicativos. O servidor de aplicativos contém o middleware de autorização, que processa a solicitação do cliente e assina um JWT para o cliente se conectar ao serviço.
- O servidor de aplicativos retorna o JWT e a URL do serviço para o cliente.
- O cliente tenta se conectar ao serviço Web PubSub usando a URL e o token JWT retornados do servidor de aplicativos.
Declarações com suporte
Você também pode configurar propriedades para a conexão do cliente ao gerar o token de acesso especificando declarações especiais dentro do token JWT:
Descrição | Tipo de declaração | Valor da declaração | Observações |
---|---|---|---|
O userId para a conexão do cliente |
sub |
a userId | Apenas uma declaração sub é permitida. |
O tempo de vida do token | exp |
o tempo de expiração | A declaração exp (tempo de expiração) identifica o tempo de expiração em ou após o qual o token NÃO DEVE ser aceito para processamento. |
As permissões que a conexão do cliente inicialmente tem | role |
o valor da função definido em permissões | Especifique várias declarações role se o cliente tiver várias permissões. |
Os grupos iniciais que a conexão do cliente ingressa depois de se conectar ao Azure Web PubSub | webpubsub.group |
o grupo a ser ingressado | Especifique várias declarações webpubsub.group se o cliente ingressar em vários grupos. |
Você também pode adicionar declarações personalizadas ao token de acesso e esses valores são preservados como a propriedade claims
em corpo da solicitação de conexão upstream.
SDKs do Servidor fornecem APIs para gerar o token de acesso para os clientes.
O cliente WebSocket simples
Um cliente WebSocket simples, como o nome indica, é uma conexão WebSocket simples. Ele também pode ter um subprotocolo personalizado próprio.
Por exemplo, em JavaScript, você pode criar um cliente WebSocket simples usando o seguinte código:
// simple WebSocket client1
var client1 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');
// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'custom.subprotocol')
O cliente WebSocket simples tem dois modos: sendEvent
e sendToGroup
. O modo é determinado quando a conexão é estabelecida e não pode ser alterado posteriormente.
sendEvent
é o modo padrão para o cliente WebSocket simples. No modo sendEvent
, cada quadro WebSocket que o cliente enviou é considerado como um evento message
. Os usuários podem configurar manipuladores de eventos ou ouvintes de eventos para lidar com esses eventos message
.
// Every data frame is considered as a `message` event
var client3 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');
// Or explicitly set the mode
var client4 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendEvent');
No modo sendToGroup
, cada quadro WebSocket que o cliente enviou é considerado como uma mensagem a ser publicada em um grupo específico.
group
é um parâmetro de consulta necessário nesse modo e só é permitido um único valor. A conexão também deve ter permissões correspondentes para enviar mensagens para o grupo de destino. As funções webpubsub.sendToGroup.<group>
e webpubsub.sendToGroup
funcionam para ela.
Por exemplo, no JavaScript, você pode criar um cliente WebSocket simples no modo sendToGroup
com group=group1
usando o seguinte código:
var client5 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendToGroup&group=group1');
O cliente WebSocket PubSub
Um cliente WebSocket do PubSub é o cliente WebSocket usando subprotocolos definidos pelo serviço Azure Web PubSub:
json.webpubsub.azure.v1
protobuf.webpubsub.azure.v1
Com o subprotocolo com suporte de serviço, os clientes WebSocket do PubSub podem publicar mensagens diretamente em grupos quando eles têm as permissões.
O subprotocolo json.webpubsub.azure.v1
Verifique aqui para conhecer o subprotocolo JSON em detalhes.
Criar um cliente WebSocket do PubSub
var pubsubClient = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');
Ingressar diretamente em um grupo do cliente
let ackId = 0;
pubsubClient.send(
JSON.stringify({
type: 'joinGroup',
group: 'group1',
ackId: ++ackId
}));
Enviar mensagens para um grupo diretamente do cliente
let ackId = 0;
pubsubClient.send(
JSON.stringify({
type: 'sendToGroup',
group: 'group1',
ackId: ++ackId,
dataType: "json",
data: {
"hello": "world"
}
}));
O subprotocolo protobuf.webpubsub.azure.v1
Os protobufs (buffers de protocolo) são um protocolo baseado em binário, com neutralidade de idioma e em plataforma que simplificam o envio de dados binários. O protobuf oferece ferramentas que geram clientes para várias linguagens, como Java, Python, Objective-C, C# e C++. Saiba mais sobre o Protobuf.
Por exemplo, no JavaScript, você pode criar um cliente WebSocket do PubSub com um subprotocolo de protobuf usando o seguinte código:
// PubSub WebSocket client
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'protobuf.webpubsub.azure.v1');
Verifique aqui para conhecer o subprotocolo protobuf em detalhes.
Resposta AckId e Ack
O Cliente WebSocket do PubSub dá suporte à propriedade ackId
para mensagens joinGroup
, leaveGroup
, sendToGroup
e event
. Ao usar ackId
, você pode receber uma mensagem de resposta ack quando sua solicitação for processada. Você pode optar por omitir ackId
em cenários disparar e esquecer. No artigo, descrevemos as diferenças de comportamento entre especificar ackId
ou não.
Comportamento quando não houver ackId
especificado
Se ackId
não for especificado, será do tipo disparar e esquecer. Mesmo que haja erros ao agenciar mensagens, você não terá como ser notificado.
Comportamento quando houver ackId
especificado
Publicação idempotente
ackId
é um número uint64 e deve ser exclusivo em um cliente com a mesma ID de conexão. O Serviço Web PubSub registra o ackId
e as mensagens com o mesmo ackId
são tratadas como a mesma mensagem. O serviço se recusa a intermediar a mesma mensagem mais de uma vez, o que é útil para tentar evitar mensagens duplicadas. Por exemplo, se um cliente enviar uma mensagem com ackId=5
e não receber uma resposta ack com ackId=5
, o cliente repetirá e enviará a mesma mensagem novamente. Em alguns casos, a mensagem já está agenciada e a resposta ACK é perdida por algum motivo. O serviço rejeita a repetição e resposta de uma resposta ACK com o motivo Duplicate
.
Resposta Ack
O Serviço Web PubSub envia uma resposta rápida para cada solicitação com ackId
.
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>"
}
}
O
ackId
associa a solicitação.success
é um booliano e indica se a solicitação é processada com êxito pelo serviço. Se forfalse
, os clientes precisarão verificar oerror
.O
error
só existe quandosuccess
éfalse
e os clientes devem ter uma lógica diferente para diferentesname
. Você deve supor que poderá haver mais tipos dename
no futuro.-
Forbidden
: o cliente não tem a permissão para a solicitação. O cliente precisa ser adicionado a funções relevantes. -
InternalServerError
: ocorreu um erro interno no serviço. É necessário tentar novamente. -
Duplicate
: a mensagem com o mesmoackId
já foi processada pelo serviço.
-
Permissões
Como você provavelmente observou na descrição anterior do cliente WebSocket do PubSub, um cliente pode fazer uma publicação em outros clientes somente quando estiver autorizado a fazer isso. As permissões de um cliente podem ser concedidas quando ele está sendo conectado ou durante o tempo de vida da conexão.
Função | Permissão |
---|---|
Não especificado | O cliente pode enviar solicitações de evento. |
webpubsub.joinLeaveGroup |
O cliente pode ingressar em qualquer grupo ou sair dele. |
webpubsub.sendToGroup |
O cliente pode publicar mensagens em qualquer grupo. |
webpubsub.joinLeaveGroup.<group> |
O cliente pode ingressar no grupo <group> ou sair dele. |
webpubsub.sendToGroup.<group> |
O cliente pode publicar mensagens no grupo <group> . |
A permissão de um cliente pode ser concedida de várias maneiras:
1. Atribuir a função ao cliente ao gerar o token de acesso
O cliente pode se conectar ao serviço usando um token JWT. O conteúdo do token pode transportar informações como o role
do cliente. Ao assinar o token JWT para o cliente, você pode conceder permissões ao cliente, concedendo funções específicas ao cliente.
Por exemplo, vamos assinar um token JWT que tenha a permissão para enviar mensagens para group1
e group2
:
let token = await serviceClient.getClientAccessToken({
roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});
2. Atribuir a função ao cliente com o manipulador de eventos connect
As funções dos clientes também podem ser definidas quando o manipulador de eventos connect
é registrado e o manipulador de eventos upstream pode retornar o roles
do cliente para o serviço Web PubSub ao manipular os eventos connect
.
Por exemplo, no JavaScript, você pode configurar o evento handleConnect
para fazer isso:
let handler = new WebPubSubEventHandler("hub1", {
handleConnect: (req, res) => {
// auth the connection and set the userId of the connection
res.success({
roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});
},
});
3. Atribuir a função ao cliente por meio de APIs REST ou SDKs de servidor durante o runtime
let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });
Próximas etapas
Use estes recursos para começar a criar seu aplicativo: