Protocolos de cliente WebSocket para Azure Web PubSub

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 possam conectar-se:

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

{hub} é um parâmetro obrigatório que atua como isolamento para várias aplicações. Pode configurá-lo no caminho de acesso ou nos parâmetros de 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 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 JWT:

Você também pode adicionar declarações personalizadas ao token de acesso, e esses valores são preservados como a propriedade claims no corpo da 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 WebSocket simples tem dois modos: sendEvent e sendToGroup. O modo é determinado assim que a conexão é estabelecida e não pode ser alterado posteriormente.

sendEvent é o modo padrão para o cliente WebSocket simples. No sendEvent modo, cada quadro WebSocket enviado pelo cliente é considerado como um message evento. Os usuários podem configurar manipuladores de eventos ou ouvintes de eventos para manipular esses message eventos.

// 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 sendToGroup modo, cada quadro WebSocket enviado pelo cliente é considerado como uma mensagem a ser publicada em um grupo específico. group é um parâmetro de consulta obrigatório neste modo, e apenas um único valor é permitido. A conexão também deve ter permissões correspondentes para enviar mensagens para o grupo-alvo. Tanto os papéis webpubsub.sendToGroup.<group> quanto webpubsub.sendToGroup trabalham para isso.

Por exemplo, em JavaScript, você pode criar um cliente WebSocket simples no sendToGroup modo 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 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, neutro em termos de linguagem e plataforma, que facilita 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 a ackId propriedade para joinGroup, leaveGroup, sendToGroup e event mensagens. Ao utilizar ackId, poderá receber uma mensagem de confirmação assim que o seu pedido for processado. 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 o ackId não está 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

Publicação idempotente

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 de confirmação é perdida por alguma razão. O serviço rejeita a repetição e responde uma resposta ack com Duplicate razão.

Resposta Ack

Web PubSub Service envia uma resposta de confirmação 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 o pedido.

• success é um bool e indica se o pedido é processado com sucesso pelo serviço. Se for false, os clientes 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 tipos de name no futuro.

  • Forbidden: O cliente não tem permissão para o pedido. O cliente precisa ter funções relevantes atribuídas.
  • 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.

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 JWT. A carga útil do token pode transportar informações como a role do cliente. Ao assinar o JWT para o cliente, você pode conceder permissões ao cliente dando ao cliente funções específicas.

Por exemplo, vamos assinar um JWT que tem 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 é registado e o manipulador de eventos upstream pode devolver o roles do cliente para o serviço Web PubSub ao processar os eventos connect.

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: