Partilhar via

Biblioteca de clientes do serviço Azure Web PubSub para Java – versão 1.2.9

  • Artigo

O serviço Azure Web PubSub é um serviço gerenciado do Azure que ajuda os desenvolvedores a criar aplicativos Web de forma fácil com recursos em tempo real e padrão de publicação/assinatura. Qualquer cenário que exija mensagens de publicação/assinatura em tempo real entre o servidor e os clientes ou entre clientes pode usar o serviço Azure Web PubSub. Os recursos tradicionais em tempo real que geralmente exigem a sondagem do servidor ou o envio de solicitações HTTP também podem usar o serviço Azure Web PubSub.

Você pode usar essa biblioteca no lado do servidor de aplicativos para gerenciar as conexões de cliente WebSocket, conforme mostrado no diagrama abaixo:

Estouro

Use essa biblioteca para:

  • Enviar mensagens para hubs e grupos.
  • Enviar mensagens para usuários e conexões específicos.
  • Organizar usuários e conexões em grupos.
  • Fechar conexões
  • Conceder, revogar e verificar permissões para uma conexão existente

Os detalhes sobre os termos usados aqui são descritos na seção Principais conceitos.

Código-fonte | Documentação de referência da API | Documentação do produto | Exemplos

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.2.9</version>
</dependency>

Criar um WebPubSubServiceClient usando uma cadeia de conexão

WebPubSubServiceClient webPubSubServiceClient = new WebPubSubServiceClientBuilder()
    .connectionString("{connection-string}")
    .hub("chat")
    .buildClient();

Criar um WebPubSubServiceClient usando uma chave de acesso

WebPubSubServiceClient webPubSubServiceClient = new WebPubSubServiceClientBuilder()
    .credential(new AzureKeyCredential("{access-key}"))
    .endpoint("<Insert endpoint from Azure Portal>")
    .hub("chat")
    .buildClient();

Principais conceitos

Conexão

Uma conexão, também conhecida como cliente ou conexão cliente, representa uma conexão do WebSocket individual ao serviço Web PubSub. Quando conectado com sucesso, uma ID de conexão exclusiva é atribuída a essa conexão pelo serviço Web PubSub.

Hub

Um hub é um conceito lógico para um conjunto de conexões de cliente. Normalmente, você usa um hub para cada finalidade específica, por exemplo, o hub de chat ou o hub de notificações. Quando uma conexão de cliente é criada, ela se conecta a um hub e, durante seu tempo de vida, pertence a esse hub. Aplicativos diferentes podem compartilhar o mesmo serviço Azure Web PubSub usando nomes de hub diferentes.

Grupo

Um grupo é um subconjunto de conexões com o hub. Você pode adicionar uma conexão de cliente a um grupo ou removê-la do grupo sempre que desejar. Por exemplo, quando um cliente entra em uma sala de chat ou quando um cliente sai da sala de chat, essa sala de chat pode ser considerada um grupo. Um cliente pode ingressar em vários grupos e um grupo pode conter vários clientes.

Usuário

As conexões com o Web PubSub podem pertencer a um usuário. Um usuário pode ter várias conexões, por exemplo, quando apenas um usuário está conectado a vários dispositivos ou a várias guias do navegador.

Mensagem

Quando o cliente está conectado, ele pode enviar mensagens ao aplicativo upstream ou receber mensagens do aplicativo upstream por meio da conexão do WebSocket.

Exemplos

Transmitir mensagem para o hub inteiro

webPubSubServiceClient.sendToAll("Hello world!", WebPubSubContentType.TEXT_PLAIN);

Transmitir mensagem para o hub inteiro com filtro

// send a text message to the entire hub with a filter on userId
BinaryData message = BinaryData.fromString("Hello World - Broadcast test!");
webPubSubServiceClient.sendToAllWithResponse(
    message,
    WebPubSubContentType.TEXT_PLAIN,
    message.getLength(),
    new RequestOptions().addQueryParam("filter", "userId ne 'user1'"));

// send a text message to the entire hub with another filter on group
webPubSubServiceClient.sendToAllWithResponse(
    message,
    WebPubSubContentType.TEXT_PLAIN,
    message.getLength(),
    new RequestOptions().addQueryParam("filter", "'GroupA' in groups and not('GroupB' in groups)"));

Transmitir mensagem para um grupo

webPubSubServiceClient.sendToGroup("java", "Hello Java!", WebPubSubContentType.TEXT_PLAIN);

Enviar uma mensagem para uma conexão

webPubSubServiceClient.sendToConnection("myconnectionid", "Hello connection!", WebPubSubContentType.TEXT_PLAIN);

Enviar mensagem para um usuário

webPubSubServiceClient.sendToUser("Andy", "Hello Andy!", WebPubSubContentType.TEXT_PLAIN);

Solução de problemas

Habilitar o log do cliente

Você pode definir a variável de ambiente AZURE_LOG_LEVEL para exibir instruções de log feitas na biblioteca de cliente. Por exemplo, a configuração AZURE_LOG_LEVEL=2 mostraria todas as mensagens informativas, de aviso e de log de erros. Os níveis de log podem ser encontrados aqui: níveis de log.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL é um uber jar que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

  • Os exemplos são explicados em detalhes aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões