Suporte do Spring Cloud Azure para o Barramento de Serviço do Azure do Spring Messaging

  • Aplica-se a: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

Este artigo descreve como você pode usar o Spring Cloud Azure e o Spring Messaging Barramento de Serviço do Azure. O Spring Framework fornece amplo suporte para integração com sistemas de mensagens.

Barramento de Serviço do Azure Spring Messaging

Conceitos principais

O Barramento de Serviço do Azure é um broker de mensagens corporativo totalmente gerenciado com filas de mensagens e tópicos de publicação e assinatura. O projeto Spring Messaging para Barramento de Serviço do Azure aplica os conceitos centrais do Spring ao desenvolvimento de soluções de mensageria baseadas no Service Bus. Ele fornece um modelo como uma abstração de alto nível para enviar mensagens. Ele também fornece suporte para POJOs controlados por mensagem com anotações @ServiceBusListener e um contêiner de ouvinte . Essas bibliotecas promovem o uso da injeção de dependência e da configuração declarativa. Em todos esses casos, você pode ver semelhanças com o suporte do JMS no suporte do Spring Framework e do RabbitMQ no Spring AMQP.

Configuração de dependência

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-messaging-azure-servicebus</artifactId>
</dependency>

Configuração

A biblioteca fornece as seguintes opções de configuração para ServiceBusTemplate e @ServiceBusListener:

Propriedade Tipo Descrição
spring.cloud.azure.message-converter.isolated-object-mapper booleano Se um bean ObjectMapper isolado é usado no conversor de mensagens do Barramento de Serviço. Habilitado por padrão.
spring.cloud.azure.servicebus.enabled booleano Indica se o Barramento de Serviço do Azure está habilitado.
spring.cloud.azure.servicebus.connection-string fio Valor da string de conexão do namespace do Barramento de Serviço.
spring.cloud.azure.servicebus.custom-endpoint-address fio O endereço de endpoint personalizado usado ao se conectar ao Barramento de Serviço.
spring.cloud.azure.servicebus.namespace fio Valor do namespace do Barramento de Serviço, que é o prefixo do FQDN. Um FQDN deve ser composto por NamespaceName.DomainName
spring.cloud.azure.servicebus.entity-type fio Tipo de entidade do Barramento de Serviço do Azure.

Uso Básico

Conversor de mensagens personalizado do Barramento de Serviço

Há duas maneiras de configurar o conversor de mensagens do Barramento de Serviço:

  • Configure a propriedade a seguir para que o conversor de mensagens padrão do Barramento de Serviço use um bean ObjectMapper, que pode ser seu bean personalizado ObjectMapper ou um bean gerenciado pelo Spring Boot:

    spring:
  cloud:
    azure:
      message-converter:
        isolated-object-mapper: false

  • Defina diretamente o bean do conversor de mensagens do Barramento de Serviço:

    @Bean
AzureMessageConverter<ServiceBusReceivedMessage, ServiceBusMessage> serviceBusMessageConverter() {
    JsonMapper jsonMapper = JsonMapper.builder().addModule(new JavaTimeModule()).build();
    return new ServiceBusMessageConverter(jsonMapper);
}

Enviar mensagens para o Barramento de Serviço do Azure

Use as seguintes etapas para enviar mensagens:

  1. Preencha as opções de configuração de credencial usando uma das seguintes abordagens:

    • Para credenciais como DefaultAzureCredential, configure as seguintes propriedades em seu arquivo de application.yml:

      spring:
  cloud:
    azure:
      servicebus:
        namespace: ${AZURE_SERVICE_BUS_NAMESPACE}
        entity-type: ${AZURE_SERVICE_BUS_ENTITY_TYPE}

    • Para credenciais como cadeia de conexão, configure as seguintes propriedades no arquivo application.yml:

      spring:
  cloud:
    azure:
      servicebus:
        connection-string: ${AZURE_SERVICE_BUS_CONNECTION_STRING}
        entity-type: ${AZURE_SERVICE_BUS_ENTITY_TYPE}

    • Para credenciais como identidades gerenciadas, configure as seguintes propriedades em seu arquivo application.yml:

      spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
        client-id: ${AZURE_CLIENT_ID}
      profile:
        tenant-id: <tenant>
      servicebus:
        namespace: ${AZURE_SERVICE_BUS_NAMESPACE}
        entity-type: ${AZURE_SERVICE_BUS_ENTITY_TYPE}

Observação

Os valores a seguir são permitidos para tenant-id: common, organizations, consumersou a ID do locatário. Para obter mais informações sobre esses valores, consulte a seção Uso do ponto de extremidade incorreto (contas pessoais e de organização) do Error AADSTS50020 – A conta de usuário do provedor de identidade não existe no locatário. Para saber como converter seu aplicativo de locatário único, consulte Converter aplicativo de locatário único em multilocatário no Microsoft Entra ID.

  • Para credenciais de service principal, configure as seguintes propriedades no arquivo application.yml:

    spring:
  cloud:
    azure:
      credential:
        client-id: ${AZURE_CLIENT_ID}
        client-secret: ${AZURE_CLIENT_SECRET}
      profile:
        tenant-id: <tenant>
      servicebus:
        namespace: ${AZURE_SERVICE_BUS_NAMESPACE}
        entity-type: ${AZURE_SERVICE_BUS_ENTITY_TYPE}

Observação

Os valores a seguir são permitidos para tenant-id: common, organizations, consumersou a ID do locatário. Para obter mais informações sobre esses valores, consulte a seção Uso do ponto de extremidade incorreto (contas pessoais e de organização) do Error AADSTS50020 – A conta de usuário do provedor de identidade não existe no locatário. Para saber como converter seu aplicativo de locatário único, consulte Converter aplicativo de locatário único em multilocatário no Microsoft Entra ID.

  1. ServiceBusTemplate é configurado automaticamente, e você pode injetá-lo diretamente em seus próprios beans, conforme mostrado no exemplo a seguir:

    @Component
public class MyBean {

    private final ServiceBusTemplate serviceBusTemplate;

    public MyBean(ServiceBusTemplate serviceBusTemplate) {
        this.serviceBusTemplate = serviceBusTemplate;
    }

    public void someMethod() {
        this.serviceBusTemplate.sendAsync('QUEUE_NAME', MessageBuilder.withPayload("Hello world").build()).subscribe();
    }

}

Receber mensagens do Barramento de Serviço do Azure

Use as seguintes etapas para receber mensagens:

  1. Preencha as opções de configuração de credencial.

  2. Adicione a anotação @EnableAzureMessaging, o que aciona a descoberta de métodos anotados com @ServiceBusListener e cria internamente o contêiner do ouvinte de mensagens.

    @SpringBootApplication
@EnableAzureMessaging
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

    Observação

    Para evitar repetição, desde a versão 5.21.0, o Spring Cloud Azure Auto-configure habilita automaticamente a anotação @EnableAzureMessaging.

  3. Quando a infraestrutura do ServiceBus está presente, você pode anotar qualquer bean com @ServiceBusListener para criar um endpoint de escuta. O componente a seguir cria um endpoint de escuta na fila QUEUE_NAME:

    @Component
public class MyBean {

    @ServiceBusListener(destination = "QUEUE_NAME")
    public void processMessage(String content) {
        // ...
    }

}

Personalizar propriedades do cliente do Barramento de Serviço

Os desenvolvedores podem usar AzureServiceClientBuilderCustomizer para personalizar as propriedades do cliente do Barramento de Serviço. O exemplo a seguir personaliza a propriedade sessionIdleTimeout em ServiceBusClientBuilder:

@Bean
public AzureServiceClientBuilderCustomizer<ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder> customizeBuilder() {
    return builder -> builder.sessionIdleTimeout(Duration.ofSeconds(10));
}

Exemplos

Para obter mais informações, consulte o azure-spring-boot-samples repositório no GitHub.

  • Última atualização em