Biblioteca de cliente 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 clientes
• simplifica o envio de mensagens entre clientes
• Tentativas automáticas após quedas não intencionais da conexão do cliente
• entrega mensagens de forma confiável em número e em ordem após a recuperação de quedas de conexão

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

Introdução

Pré-requisitos

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

Adicionar a embalagem 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. O 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 URLarquivo . Como um início rápido, você pode copiar e colar do portal do Azure e, para produção, 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 ir para o portal do Azure e copiar a URL de Acesso para Cliente da folha Chaves.

Como mostrado no diagrama, o cliente recebe permissão para enviar mensagens para grupos específicos e ingressar em grupos específicos. Saiba mais sobre a permissão do cliente, consulte Permissões.

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

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

Na 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 através WebPubSubServiceClient. Como exemplo, o trecho de código apenas demonstra como gerar o dentro de Client Access URL um único processo.

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

// 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();

Características para diferenciar WebPubSubClient e WebPubSubServiceClient.

Exemplos

Consumir mensagens do servidor e grupos

Um cliente pode adicionar retornos de chamada para consumir mensagens do servidor e grupos. Observe que os clientes só podem receber mensagens de grupo às quais ele 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 connected, disconnectede stopped eventos

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

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

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

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 repetição

Por padrão, a operação como client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() tem três desativações. Você pode usar WebPubSubClientBuilder.retryOptions() para mudar. Se todas as novas tentativas tiverem falhado, um erro será lançado. Você pode continuar tentando novamente passando o mesmo ackId que as tentativas anteriores, assim, o serviço pode ajudar a desduplicar a operação com o mesmo ackId.

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

Resolução de Problemas

Ativar registos

Você pode definir a seguinte variável de ambiente 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, você pode consultar os documentos do pacote @azure/logger.

Rastreio em tempo real

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