Partilhar via

Protocolos de cliente WebSocket para Azure Web PubSub

  • Artigo

Os clientes se conectam ao Azure Web PubSub usando o protocolo WebSocket padrão.

Pontos finais de serviço

O serviço Web PubSub fornece dois tipos de pontos de extremidade aos quais os clientes se conectarem:

  • /client/hubs/{hub}
  • /client/?hub={hub}

{hub} é um parâmetro obrigatório que atua como isolamento para várias aplicações. Você pode defini-lo no caminho ou na consulta.

Autorização

Os clientes se conectam ao serviço com um JSON Web Token (JWT). O token pode estar na cadeia de caracteres de consulta, como /client/?hub={hub}&access_token={token}, ou no Authorization cabeçalho, como Authorization: Bearer {token}.

Aqui está um fluxo de trabalho de autorização geral:

  1. O cliente negocia com seu servidor de aplicativos. O servidor de aplicativos contém o middleware de autorização, que lida com 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 retornado do servidor de aplicativos.

Reivindicações suportadas

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:

Description Tipo de afirmação Valor da reivindicação Notas
O userId para a conexão do cliente sub o userId Só é permitida uma sub reivindicação.
O tempo de vida do token exp o tempo de expiração A exp declaração (tempo de expiração) identifica o tempo de expiração no qual ou após o qual o token NÃO DEVE ser aceito para processamento.
As permissões que a conexão do cliente tem inicialmente role O valor da função definido em Permissões Especifique várias role declarações se o cliente tiver várias permissões.
Os grupos iniciais aos quais a conexão do cliente se junta quando se conecta ao Azure Web PubSub group o grupo a aderir Especifique várias group declarações 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 no corpo da claims solicitação upstream de conexão.

SDKs de servidor fornece APIs para gerar o token de acesso para os clientes.

O cliente WebSocket simples

Um cliente WebSocket simples, como a nomenclatura indica, é uma conexão WebSocket simples. Ele também pode ter seu próprio subprotocolo personalizado.

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 PubSub WebSocket

Um cliente PubSub WebSocket é o cliente WebSocket usando subprotocolos definidos pelo serviço Azure Web PubSub:

  • json.webpubsub.azure.v1
  • protobuf.webpubsub.azure.v1

Com o subprotocolo suportado pelo serviço, os clientesPubSub WebSocket podem publicar mensagens diretamente em grupos quando tiverem as permissões.

O json.webpubsub.azure.v1 subprotocolo

Verifique aqui o subprotocolo JSON em detalhes.

Criar um cliente PubSub WebSocket

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

Junte-se diretamente a um grupo do cliente

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'joinGroup',
        group: 'group1',
        ackId: ++ackId
    }));

Enviar mensagens diretamente do cliente para um grupo

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'sendToGroup',
        group: 'group1',
        ackId: ++ackId,
        dataType: "json",
        data: {
            "hello": "world"
        }
    }));

O protobuf.webpubsub.azure.v1 subprotocolo

Buffers de protocolo (protobuf) é um protocolo baseado em binário, plataforma e neutralidade de linguagem que simplifica o envio de dados binários. O Protobuf fornece ferramentas para gerar clientes para muitas linguagens, como Java, Python, Objective-C, C# e C++. Saiba mais sobre protobuf.

Por exemplo, em JavaScript, você pode criar um cliente PubSub WebSocket com um subprotocolo 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');

Confira aqui o subprotocolo protobuf em detalhes.

Resposta AckId e Ack

O PubSub WebSocket Client suporta ackId propriedade para joinGroup, leaveGroupsendToGroup e event mensagens. Ao usar ackIdo , você pode receber uma mensagem de resposta ack quando sua solicitação for processada. Você pode optar por omitir ackId em cenários de fogo e esquecimento. No artigo, descrevemos as diferenças de comportamento entre especificar ackId ou não.

Comportamento quando não ackId especificado

Se ackId não for especificado, é fogo e esquecimento. Mesmo que haja erros ao intermediar mensagens, você não tem como ser notificado.

Comportamento quando ackId especificado

Idempotent publicar

ackId é um número uint64 e deve ser exclusivo dentro de um cliente com o mesmo ID de conexão. Web PubSub Service registra o ackId e 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 novamente evitar mensagens duplicadas. Por exemplo, se um cliente envia uma mensagem com ackId=5 e não recebe uma resposta ack com ackId=5, então o cliente tenta novamente e envia a mesma mensagem novamente. Em alguns casos, a mensagem já está intermediada e a resposta ack é perdida por algum motivo. O serviço rejeita a repetição e responde uma resposta ack com Duplicate razão.

Resposta Ack

Web PubSub Service envia ack resposta 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>"
    }
}

  • Os ackId associados o pedido.

  • success é um bool e indica se o pedido é processado com sucesso pelo serviço. Se for , os falseclientes precisam verificar o error.

  • error só existe quando success é false e os clientes devem ter lógica diferente para diferentes name. Você deve supor que pode haver mais tipo de name no futuro.

    • Forbidden: O cliente não tem permissão para o pedido. O cliente precisa ser adicionado funções relevantes.
    • InternalServerError: Ocorreu algum erro interno no serviço. É necessário repetir a tentativa.
    • Duplicate: A mensagem com o mesmo ackId já foi processada pelo serviço.

Permissões

Como você provavelmente notou na descrição anterior do cliente PubSub WebSocket, um cliente pode publicar para outros clientes somente quando estiver autorizado a fazê-lo. As permissões de um cliente podem ser concedidas quando ele está sendo conectado ou durante a vida útil da conexão.

Role Permissão
Não especificado O cliente pode enviar solicitações de eventos.
webpubsub.joinLeaveGroup O cliente pode entrar ou sair de qualquer grupo.
webpubsub.sendToGroup O cliente pode publicar mensagens em qualquer grupo.
webpubsub.joinLeaveGroup.<group> O cliente pode entrar ou sair do grupo <group>.
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. Atribua a função ao cliente ao gerar o token de acesso

O cliente pode se conectar ao serviço usando um token JWT. A carga útil do token pode transportar informações como a role do cliente. Ao assinar o token JWT para o cliente, você pode conceder permissões ao cliente dando ao cliente funções específicas.

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. Atribua a função ao cliente com o manipulador de connect eventos

As funções dos clientes também podem ser definidas quando o connect manipulador de eventos é registrado e o manipulador de eventos upstream pode retornar o roles do cliente para o serviço Web PubSub ao manipular os connect eventos.

Por exemplo, em JavaScript, você pode configurar o handleConnect evento 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. Atribua a função ao cliente por meio de APIs REST ou SDKs de servidor durante o tempo de execução

let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });

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