Partilhar via


Enviar e receber mensagens de filas do Barramento de Serviço do Azure (Java)

Este guia de início rápido fornece instruções passo a passo para um cenário simples de enviar mensagens para uma fila do Service Bus e recebê-las. Você cria uma aplicação Java para enviar mensagens para e receber mensagens de uma fila do Azure Service Bus. Você pode encontrar exemplos Java pré-configurados para o Barramento de Serviço do Azure no repositório do SDK do Azure para Java no GitHub.

Sugestão

Se você estiver trabalhando com recursos do Barramento de Serviço do Azure em um aplicativo Spring, recomendamos que considere o Spring Cloud Azure. O Spring Cloud Azure é um projeto de código aberto que fornece integração perfeita do Spring com os serviços do Azure. Para saber mais sobre o Spring Cloud Azure e ver um exemplo usando o Service Bus, consulte Spring Cloud Stream com o Azure Service Bus.

Pré-requisitos

Criar um espaço de nomes no portal do Azure

Para começar a usar entidades de mensagens do Service Bus no Azure, crie um namespace com um nome único em todo o Azure. Um namespace fornece um contêiner de escopo para recursos do Service Bus, como filas e tópicos, em seu aplicativo.

Para criar um espaço de nomes:

  1. Inicie sessão no portal Azure.

  2. Selecione o menu de opções no canto superior esquerdo e navegue para a página Todos os serviços.

  3. Na barra de navegação esquerda, selecione Integração.

  4. Role para baixo até Serviços de mensagens>Service Bus e selecione Criar.

    Captura de ecrã a mostrar a seleção de Criar um recurso, Integração e, em seguida, Barramento de Serviço no menu.

  5. Na guia Noções básicas da página Criar namespace , siga estas etapas:

    1. Em Assinatura, escolha uma assinatura do Azure na qual criar o namespace.

    2. Para Grupo de recursos, escolha um grupo de recursos existente ou crie um novo.

    3. Insira um nome de namespace que atenda às seguintes convenções de nomenclatura:

      • O nome deve ser exclusivo no Azure. O sistema verifica imediatamente a disponibilidade do nome.
      • O comprimento do nome é de pelo menos 6 e no máximo 50 caracteres.
      • O nome pode conter apenas letras, números hífenes -.
      • O nome deve começar com uma letra e terminar com uma letra ou número.
      • O nome não termina com -sb ou -mgmt.
    4. Em Local, escolha a região para hospedar seu namespace.

    5. Em Nível de preço, selecione o nível de preço (Básico, Standard ou Premium) para o namespace. Para este início rápido, selecione Padrão.

      Se você selecionar a camada Premium , poderá habilitar a replicação geográfica para o namespace. O recurso de replicação geográfica garante que os metadados e os dados de um namespace sejam replicados continuamente de uma região primária para uma ou mais regiões secundárias.

      Importante

      Se você quiser usar tópicos e assinaturas, escolha Standard ou Premium. Não há suporte para tópicos e assinaturas no nível de preço Básico.

      Se você selecionou o nível de preço Premium, especifique o número de unidades de mensagens. A camada premium fornece isolamento de recursos no nível de CPU e memória para que cada carga de trabalho seja executada isoladamente. Este contentor de recursos é designado por unidade de mensagens. Um namespace premium tem pelo menos uma unidade de mensagens. Você pode selecionar 1, 2, 4, 8 ou 16 unidades de mensagens para cada namespace Premium do Service Bus. Para obter mais informações, consulte Camada de mensagens premium do Service Bus.

    6. Selecione Revisar + criar no fundo da página.

      Captura de tela mostrando a página Criar um namespace

    7. Na página Rever + criar, reveja as definições e selecione Criar.

  6. Depois que a implantação do recurso for bem-sucedida, selecione Ir para o recurso na página de implantação.

    Captura de tela mostrando a página de implantação bem-sucedida com o link Ir para recurso.

  7. Você vê a página inicial do namespace do barramento de serviço.

    Captura de tela mostrando a home page do namespace do Service Bus criado.

Criar uma fila no portal do Azure

  1. Na página Namespace do Service Bus, expanda Entidades no menu de navegação à esquerda e selecione Filas.

  2. Na página Filas , na barra de ferramentas, selecione + Fila.

  3. Insira um nome para a fila. Deixe os outros valores com seus padrões.

  4. Selecione Criar.

    Captura de tela que mostra a página Criar fila.

Autenticar o aplicativo no Azure

Este artigo mostra duas maneiras de se conectar ao Barramento de Serviço do Azure: autenticação sem senha e cadeia de conexão.

A primeira opção mostra como usar o seu principal de segurança no Microsoft Entra ID e o controle de acesso baseado em função (RBAC) para se conectar a um namespace do Service Bus. Você não precisa se preocupar em ter uma cadeia de conexão codificada em seu código, em um arquivo de configuração ou em um armazenamento seguro como o Azure Key Vault.

A segunda opção mostra como usar uma cadeia de conexão para se conectar a um namespace do Service Bus. Se você for novo no Azure, talvez ache a opção de cadeia de conexão mais fácil de seguir. Recomendamos o uso da opção sem senha em aplicativos e ambientes de produção do mundo real. Para obter mais informações, consulte Autenticação e autorização do Service Bus. Para ler mais sobre autenticação sem senha, consulte Autenticar aplicativos .NET.

Atribuir funções ao usuário do Microsoft Entra

Ao desenvolver localmente, verifique se a conta de usuário que se conecta ao Barramento de Serviço do Azure tem as permissões corretas. Você precisa do cargo Data Owner do Azure Service Bus para enviar e receber mensagens. Para atribuir essa função a si mesmo, você precisa da função de Administrador de Acesso de Usuário ou outra função que inclua a Microsoft.Authorization/roleAssignments/write ação.

Você pode atribuir funções do RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Para saber mais sobre os escopos disponíveis para atribuições de função, consulte Entender o escopo do RBAC do Azure.

O exemplo seguinte atribui a função Azure Service Bus Data Owner à sua conta de utilizador, que fornece acesso total aos recursos do Azure Service Bus. Em um cenário real, siga o princípio do menor privilégio para dar aos usuários apenas as permissões mínimas necessárias para um ambiente de produção mais seguro.

Funções incorporadas do Azure para o Barramento de Serviço do Azure

Para o Barramento de Serviço do Azure, o gerenciamento de namespaces e todos os recursos relacionados por meio do portal do Azure e da API de gerenciamento de recursos do Azure já está protegido usando o modelo RBAC do Azure. O Azure fornece as seguintes funções internas do Azure para autorizar o acesso a um namespace do Service Bus:

Se você quiser criar uma função personalizada, consulte Direitos necessários para operações do Service Bus.

Adicionar usuário do Microsoft Entra à função de Proprietário do Barramento de Serviço do Azure

Adicione o seu nome de utilizador do Microsoft Entra à função Proprietário de Dados do Barramento de Serviço do Azure ao nível do namespace do Barramento de Serviço. Essa configuração permite que um aplicativo executado no contexto de sua conta de usuário envie mensagens para uma fila ou um tópico. Ele pode receber mensagens de uma fila ou da assinatura de um tópico.

Importante

Na maioria dos casos, leva um ou dois minutos para que a atribuição de função se propague no Azure. Em casos raros, pode demorar até oito minutos. Se você receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos e tente novamente.

  1. Se você não tiver a página Namespace do Service Bus aberta no portal do Azure, localize seu namespace do Service Bus usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página Visão geral , selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controlo de acesso (IAM), selecione o separador Atribuição de funções.

  4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função.

    Uma captura de tela mostrando como atribuir uma função.

  5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, procure Azure Service Bus Data Owner e selecione o resultado correspondente. Em seguida, escolha Avançar.

  6. Em Atribuir acesso a, selecione Utilizador, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

  7. Na caixa de diálogo, procure seu nome de usuário do Microsoft Entra (geralmente seu endereço de e-mail user@domain ) e escolha Selecionar na parte inferior da caixa de diálogo.

  8. Selecione Rever + atribuir para ir para a página final e, em seguida , Rever + atribuir novamente para concluir o processo.

Enviar mensagens para uma fila

Nesta seção, você cria um projeto de console Java e adiciona código para enviar mensagens para a fila criada anteriormente.

Criar um projeto de console Java

Crie um projeto Java usando o Eclipse ou uma ferramenta de sua escolha.

Configurar seu aplicativo para usar o Service Bus

Adicione referências às bibliotecas do Azure Core e do Azure Service Bus.

Se você estiver usando o Eclipse e tiver criado um aplicativo de console Java, converta seu projeto Java em um Maven: clique com o botão direito do mouse no projeto na janela do Package Explorer . Selecione Configurar>converter para projeto Maven. Em seguida, adicione dependências a essas duas bibliotecas, conforme mostrado no exemplo a seguir.

Atualize o arquivo pom.xml para adicionar dependências aos pacotes Azure Service Bus e Azure Identity.

    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-messaging-servicebus</artifactId>
            <version>7.13.3</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.8.0</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

Adicionar código para enviar mensagens para a fila

  1. Adicione as seguintes import instruções no tópico do arquivo Java.

    import com.azure.messaging.servicebus.*;
    import com.azure.identity.*;
    
    import java.util.concurrent.TimeUnit;
    import java.util.Arrays;
    import java.util.List;
    
  2. Na classe, defina variáveis para manter a cadeia de conexão e o nome da fila.

    static String queueName = "<QUEUE NAME>";
    

    Importante

    Substitua <QUEUE NAME> pelo nome da fila.

  3. Adicione um método nomeado sendMessage na classe para enviar uma mensagem para a fila.

    Importante

    Substitua NAMESPACENAME pelo nome do espaço de nomes do Service Bus.

    static void sendMessage()
    {
        // create a token using the default Azure credential
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
                .build();
    
        ServiceBusSenderClient senderClient = new ServiceBusClientBuilder()
                .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net")
                .credential(credential)
                .sender()
                .queueName(queueName)
                .buildClient();
    
        // send one message to the queue
        senderClient.sendMessage(new ServiceBusMessage("Hello, World!"));
        System.out.println("Sent a single message to the queue: " + queueName);
    }
    
    
  4. Adicione um método nomeado createMessages na classe para criar uma lista de mensagens. Normalmente, você recebe essas mensagens de diferentes partes do seu aplicativo. Neste exemplo, você usa uma lista de mensagens de exemplo.

    static List<ServiceBusMessage> createMessages()
    {
        // create a list of messages and return it to the caller
        ServiceBusMessage[] messages = {
                new ServiceBusMessage("First message"),
                new ServiceBusMessage("Second message"),
                new ServiceBusMessage("Third message")
        };
        return Arrays.asList(messages);
    }
    
  5. Adicione um método chamado sendMessageBatch método para enviar mensagens para a fila que você criou. Esse método cria um ServiceBusSenderClient para a fila, invoca o createMessages método para obter a lista de mensagens, prepara um ou mais lotes e envia os lotes para a fila.

    Importante

    Substitua NAMESPACENAME pelo nome do espaço de nomes do Service Bus.

    static void sendMessageBatch()
    {
        // create a token using the default Azure credential
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
                .build();
    
        ServiceBusSenderClient senderClient = new ServiceBusClientBuilder()
                .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net")
                .credential(credential)
                .sender()
                .queueName(queueName)
                .buildClient();
    
        // Creates an ServiceBusMessageBatch where the ServiceBus.
        ServiceBusMessageBatch messageBatch = senderClient.createMessageBatch();
    
        // create a list of messages
        List<ServiceBusMessage> listOfMessages = createMessages();
    
        // We try to add as many messages as a batch can fit based on the maximum size and send to Service Bus when
        // the batch can hold no more messages. Create a new batch for next set of messages and repeat until all
        // messages are sent.
        for (ServiceBusMessage message : listOfMessages) {
            if (messageBatch.tryAddMessage(message)) {
                continue;
            }
    
            // The batch is full, so we create a new batch and send the batch.
            senderClient.sendMessages(messageBatch);
            System.out.println("Sent a batch of messages to the queue: " + queueName);
    
            // create a new batch
            messageBatch = senderClient.createMessageBatch();
    
            // Add that message that we couldn't before.
            if (!messageBatch.tryAddMessage(message)) {
                System.err.printf("Message is too large for an empty batch. Skipping. Max size: %s.", messageBatch.getMaxSizeInBytes());
            }
        }
    
        if (messageBatch.getCount() > 0) {
            senderClient.sendMessages(messageBatch);
            System.out.println("Sent a batch of messages to the queue: " + queueName);
        }
    
        //close the client
        senderClient.close();
    }
    

Receber mensagens de uma fila

Nesta seção, você adiciona código para recuperar mensagens da fila.

  1. Adicione um método nomeado receiveMessages para receber mensagens da fila. Esse método cria um ServiceBusProcessorClient para a fila especificando um manipulador para processar mensagens e outro para manipular erros. Em seguida, ele inicia o processador, aguarda por alguns segundos, imprime as mensagens recebidas e, em seguida, para e fecha o processador.

    Importante

    • Substitua NAMESPACENAME pelo nome do espaço de nomes do Service Bus.
    // handles received messages
    static void receiveMessages() throws InterruptedException
    {
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
                .build();
    
        ServiceBusProcessorClient processorClient = new ServiceBusClientBuilder()
                .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net")
                .credential(credential)
                .processor()
                .queueName(queueName)
                .processMessage(context -> processMessage(context))
                .processError(context -> processError(context))
                .buildProcessorClient();
    
        System.out.println("Starting the processor");
        processorClient.start();
    
        TimeUnit.SECONDS.sleep(10);
        System.out.println("Stopping and closing the processor");
        processorClient.close();
    }
    
  2. Adicione o processMessage método para processar uma mensagem recebida da assinatura do Service Bus.

    private static void processMessage(ServiceBusReceivedMessageContext context) {
        ServiceBusReceivedMessage message = context.getMessage();
        System.out.printf("Processing message. Session: %s, Sequence #: %s. Contents: %s%n", message.getMessageId(),
            message.getSequenceNumber(), message.getBody());
    }
    
  3. Adicione o processError método para manipular mensagens de erro.

    private static void processError(ServiceBusErrorContext context) {
        System.out.printf("Error when receiving messages from namespace: '%s'. Entity: '%s'%n",
            context.getFullyQualifiedNamespace(), context.getEntityPath());
    
        if (!(context.getException() instanceof ServiceBusException)) {
            System.out.printf("Non-ServiceBusException occurred: %s%n", context.getException());
            return;
        }
    
        ServiceBusException exception = (ServiceBusException) context.getException();
        ServiceBusFailureReason reason = exception.getReason();
    
        if (reason == ServiceBusFailureReason.MESSAGING_ENTITY_DISABLED
            || reason == ServiceBusFailureReason.MESSAGING_ENTITY_NOT_FOUND
            || reason == ServiceBusFailureReason.UNAUTHORIZED) {
            System.out.printf("An unrecoverable error occurred. Stopping processing with reason %s: %s%n",
                reason, exception.getMessage());
        } else if (reason == ServiceBusFailureReason.MESSAGE_LOCK_LOST) {
            System.out.printf("Message lock lost for message: %s%n", context.getException());
        } else if (reason == ServiceBusFailureReason.SERVICE_BUSY) {
            try {
                // Choosing an arbitrary amount of time to wait until trying again.
                TimeUnit.SECONDS.sleep(1);
            } catch (InterruptedException e) {
                System.err.println("Unable to sleep for period of time");
            }
        } else {
            System.out.printf("Error source %s, reason %s, message: %s%n", context.getErrorSource(),
                reason, context.getException());
        }
    }
    
  4. Atualize o main método para invocar sendMessage, sendMessageBatche receiveMessages métodos e lançar InterruptedException.

    public static void main(String[] args) throws InterruptedException {
        sendMessage();
        sendMessageBatch();
        receiveMessages();
    }
    

Executar o aplicativo

  1. Se você estiver usando o Eclipse, clique com o botão direito do mouse no projeto, selecione Exportar, expanda Java, selecione Arquivo JAR executável e siga as etapas para criar um arquivo JAR executável.

  2. Se iniciou sessão com uma conta de utilizador que é diferente daquela que adicionou à função de Proprietário de Dados do Barramento de Serviço do Azure, siga estes passos. Caso contrário, passe para executar o arquivo Jar na próxima etapa.

    1. Instale a CLI do Azure em sua máquina.

    2. Execute o seguinte comando da CLI para entrar no Azure. Use a mesma conta de usuário que você adicionou à função de Proprietário de Dados do Barramento de Serviço do Azure.

      az login
      
  3. Execute o arquivo Jar usando o seguinte comando.

    java -jar <JAR FILE NAME>
    
  4. Você verá a seguinte saída na janela do console.

    Sent a single message to the queue: myqueue
    Sent a batch of messages to the queue: myqueue
    Starting the processor
    Processing message. Session: 88d961dd801f449e9c3e0f8a5393a527, Sequence #: 1. Contents: Hello, World!
    Processing message. Session: e90c8d9039ce403bbe1d0ec7038033a0, Sequence #: 2. Contents: First message
    Processing message. Session: 311a216a560c47d184f9831984e6ac1d, Sequence #: 3. Contents: Second message
    Processing message. Session: f9a871be07414baf9505f2c3d466c4ab, Sequence #: 4. Contents: Third message
    Stopping and closing the processor
    

Na página Visão geral do namespace do Service Bus no portal do Azure, você pode ver a contagem de mensagens de entrada e saída. Aguarde cerca de um minuto e, em seguida, atualize a página para ver os valores mais recentes.

A captura de tela mostra a contagem de mensagens de entrada e saída.

Selecione a fila nesta página Visão geral para navegar até a página Fila do Service Bus. Você vê a contagem de mensagens recebidas e enviadas nesta página também. Você também verá outras informações, como o tamanho atual da fila e o tamanho máximo, a contagem de mensagens ativas.

A captura de tela mostra os detalhes da fila para as mensagens dessa fila.

Consulte a seguinte documentação e exemplos: