Compartilhar via

Protocolos de cliente WebSocket para o Azure Web PubSub

  • Artigo

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:

  1. 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.
  2. O servidor de aplicativos retorna o JWT e a URL do serviço para o cliente.
  3. 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 for false, os clientes precisarão verificar o error.

  • O error só existe quando success é false e os clientes devem ter uma lógica diferente para diferentes name. Você deve supor que poderá haver mais tipos de name 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 mesmo ackId 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:

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