Biblioteca de clientes do Azure WebPubSub para Java

O SDK do lado do cliente visa acelerar o fluxo de trabalho do desenvolvedor; mais especificamente,

• simplifica o gerenciamento de conexões de cliente
• simplifica o envio de mensagens entre clientes
• tenta novamente de forma automática após quedas não intencionais da conexão do cliente
• entrega mensagens de maneira confiável em número e em ordem após a recuperação de quedas de conexão

Conforme mostrado no diagrama, seus clientes estabelecem conexões WebSocket com o recurso Web PubSub.

Introdução

Pré-requisitos

• JDK (Java Development Kit) com a versão 8 ou superior
• Assinatura do Azure
• Uma instância existente do Web PubSub

Adicionar o pacote ao seu produto

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub-client</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

Autenticar o cliente

Um cliente usa um Client Access URL para se conectar e autenticar com o serviço. A URL segue um padrão de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Há várias maneiras de obter um Client Access URL. Como um início rápido, você pode copiar e colar do portal do Azure e, para produção, você geralmente precisa de um servidor de negociação para gerar a URL. Veja detalhes.

Usar Client Access URL do portal do Azure

Como um início rápido, você pode acessar o portal do Azure e copiar a URL de Acesso para Cliente da folha Chaves.

Conforme mostrado no diagrama, o cliente recebe a permissão de enviar mensagens para grupos específicos e ingressar em grupos específicos. Para saber mais sobre permissões para cliente, confira permissões.

WebPubSubClient client = new WebPubSubClientBuilder()
    .clientAccessUrl("<client-access-url>")
    .buildClient();

Usar o servidor de negociação para gerar Client Access URL

Em produção, um cliente geralmente busca o Client Access URL de um servidor de negociação. O servidor mantém o connection string e gera o Client Access URL por meio de WebPubSubServiceClient. Como exemplo, o snippet de código apenas demonstra como gerar o Client Access URL dentro de um único processo.

As cadeias de conexão brutas aparecem neste artigo somente para fins de demonstração. Em ambientes de produção, sempre proteja suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua conexão com WebPubSubServiceClient.

// WebPubSubServiceAsyncClient is from com.azure:azure-messaging-webpubsub
// create WebPubSub service client
WebPubSubServiceAsyncClient serverClient = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("<hub>>")
    .buildAsyncClient();

// wrap WebPubSubServiceAsyncClient.getClientAccessToken as WebPubSubClientCredential
WebPubSubClientCredential clientCredential = new WebPubSubClientCredential(Mono.defer(() ->
    serverClient.getClientAccessToken(new GetClientAccessTokenOptions()
            .setUserId("<user-name>")
            .addRole("webpubsub.joinLeaveGroup")
            .addRole("webpubsub.sendToGroup"))
        .map(WebPubSubClientAccessToken::getUrl)));

// create WebPubSub client
WebPubSubClient client = new WebPubSubClientBuilder()
    .credential(clientCredential)
    .buildClient();

Recursos para diferenciar WebPubSubClient e WebPubSubServiceClient.

Exemplos

Consumir mensagens do servidor e de grupos

Um cliente pode adicionar retornos de chamada para consumir mensagens do servidor e de grupos. Observe que os clientes só podem receber mensagens de grupos aos quais tenha ingressado.

client.addOnGroupMessageEventHandler(event -> {
    System.out.println("Received group message from " + event.getFromUserId() + ": "
        + event.getData().toString());
});
client.addOnServerMessageEventHandler(event -> {
    System.out.println("Received server message: "
        + event.getData().toString());
});

Adicionar retornos de chamada para os eventos connected, disconnected e stopped

Quando uma conexão de cliente é conectada ao serviço, o evento connected é disparado.

Quando uma conexão de cliente é desconectada e não consegue se recuperar, o evento disconnected é disparado.

Quando um cliente é interrompido, o que significa que a conexão do cliente é desconectada e o cliente para de tentar se reconectar, o evento stopped é disparado. Isso geralmente acontece depois que o client.StopAsync() é chamado ou o AutoReconnect é desabilitado. Se você quiser reiniciar o cliente, poderá chamar client.StartAsync() no evento Stopped.

client.addOnConnectedEventHandler(event -> {
    System.out.println("Connection is connected: " + event.getConnectionId());
});
client.addOnDisconnectedEventHandler(event -> {
    System.out.println("Connection is disconnected");
});
client.addOnStoppedEventHandler(event -> {
    System.out.println("Client is stopped");
});

Operação e nova tentativa

Por padrão, a operação, como client.joinGroup(), client.leaveGroup(), client.sendToGroup() e client.sendEvent(), tem três tentativas. Você pode usar WebPubSubClientBuilder.retryOptions() para alterar. Se todas as novas tentativas falharem, será gerado um erro. Você pode continuar tentando, passando o mesmo ackId das tentativas anteriores, assim o serviço pode ajudar a deduplicar a operação com o mesmo ackId.

try {
    client.joinGroup("testGroup");
} catch (SendMessageFailedException e) {
    if (e.getAckId() != null) {
        client.joinGroup("testGroup", e.getAckId());
    }
}

Solução de problemas

Habilitar logs

Você pode definir a variável de ambiente a seguir para obter os logs de depuração ao usar essa biblioteca.

export AZURE_LOG_LEVEL=verbose

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Rastreamento ao vivo

Use a ferramenta Live Trace do portal do Azure para inspecionar o tráfego de mensagens ao vivo por meio do recurso Web PubSub.