Suporte do Spring Cloud Azure para o Spring Messaging Azure Service Bus

  • 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 Azure Service Bus. O Spring Framework fornece suporte extensivo para integração com sistemas de mensagens.

Spring Messaging Azure Service Bus

Conceitos-chave

O Azure Service Bus é um broker de mensagens empresarial totalmente gerido com filas de mensagens e tópicos de publicação e subscrição. O projeto Spring Messaging for Azure Service Bus aplica os principais conceitos do Spring ao desenvolvimento de soluções de mensagens baseadas em barramento de serviço. Ele fornece um modelo como uma abstração de alto nível para enviar mensagens. Também oferece suporte a POJOs acionados por mensagens com anotações @ServiceBusListener e um contentor de escuta. Essas bibliotecas promovem o uso de injeção de dependência e configuração declarativa. Em todos esses casos, você pode ver semelhanças com o suporte JMS no Spring Framework e o suporte 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 isolado do ObjectMapper é usado para o conversor de mensagens do Service Bus. Ativado por padrão.
spring.cloud.azure.servicebus.enabled Booleano Se o Azure Service Bus está ativado.
spring.cloud.azure.servicebus.connection-string Cordão Valor da cadeia de ligação do namespace do Service Bus.
spring.cloud.azure.servicebus.custom-endpoint-address Cordão O endereço do ponto final personalizado a utilizar ao estabelecer ligação ao Service Bus.
spring.cloud.azure.servicebus.namespace Cordão Valor do espaço de nomes do Service Bus, que é o prefixo do FQDN. Um FQDN deve ser composto por NamespaceName.DomainName
spring.cloud.azure.servicebus.entity-type Cordão Tipo de entidade do Azure Service Bus.

Utilização básica

Conversor de mensagens personalizado do Service Bus

Há duas maneiras de configurar o conversor de mensagens do Service Bus:

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

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

  • Defina diretamente o bean conversor de mensagens do Service Bus:

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

Enviar mensagens para o Azure Service Bus

Use as seguintes etapas para enviar mensagens:

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

    • Para credenciais como DefaultAzureCredential, configure as seguintes propriedades no arquivo 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 seguintes valores são permitidos para tenant-id: common, organizations, consumersou o ID do locatário. Para obter mais informações sobre esses valores, consulte a secção Usou o ponto de extremidade errado (contas pessoais e de organização) na secção Erro AADSTS50020 - A conta de utilizador do provedor de identidade não existe no inquilino. Para obter informações sobre 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 principal de serviço, configure as seguintes propriedades no ficheiro 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 seguintes valores são permitidos para tenant-id: common, organizations, consumersou o ID do locatário. Para obter mais informações sobre esses valores, consulte a secção Usou o ponto de extremidade errado (contas pessoais e de organização) na secção Erro AADSTS50020 - A conta de utilizador do provedor de identidade não existe no inquilino. Para obter informações sobre 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 autoconectá-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 Azure Service Bus

Use as seguintes etapas para receber mensagens:

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

  2. Adicione a anotação @EnableAzureMessaging, que desencadeia a deteção de métodos anotados com @ServiceBusListener, criando nos bastidores o contentor de escuta de mensagens.

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

    Observação

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

  3. Quando a infraestrutura do ServiceBus estiver presente, pode anotar qualquer bean com @ServiceBusListener para criar um endpoint de escuta. O componente seguinte cria um ponto de escuta na fila de QUEUE_NAME:

    @Component
public class MyBean {

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

}

Personalizar as propriedades do cliente do Service Bus

Os desenvolvedores podem usar AzureServiceClientBuilderCustomizer para personalizar as propriedades do Service Bus Client. O exemplo a seguir personaliza a propriedade sessionIdleTimeout no ServiceBusClientBuilder:

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

Exemplos

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

  • Última atualização a