Usare Archiviazione di Azure Queue nelle applicazioni Spring

Questo articolo illustra come usare Archiviazione di Azure Queue nelle applicazioni Java compilate con Spring Framework.

Archiviazione di Azure Queue implementa le code basate su cloud per consentire la comunicazione tra i componenti di un'applicazione distribuita. Ogni coda gestisce un elenco di messaggi che possono essere aggiunti da un componente mittente ed elaborati da un componente destinatario. Con una coda, l'applicazione si può ridimensionare immediatamente per soddisfare la domanda.

Spring Cloud Azure offre vari moduli per utilizzare i framework Spring per inviare e ricevere messaggi dalle Archiviazione di Azure Queues. È possibile usare questi moduli in modo indipendente o combinarli per casi d'uso diversi, come descritto nell'elenco seguente:

Prerequisiti

Nota

Per concedere all'account l'accesso alle risorse, nell'account Archiviazione di Azure appena creato assegnare il ruolo Storage Queue Data Contributor all'account Microsoft Entra attualmente in uso. Per altre informazioni, vedere Assegnare ruoli di Azure utilizzando il portale Azure.

Importante

Spring Boot versione 2.5 o successiva è necessario per completare i passaggi di questa esercitazione.

Preparare l'ambiente locale

In questa esercitazione le configurazioni e il codice non dispongono di alcuna operazione di autenticazione. Tuttavia, la connessione a un servizio di Azure richiede l'autenticazione. Per completare l'autenticazione, è necessario usare la libreria client Azure Identity. Spring Cloud Azure usa DefaultAzureCredential, che la libreria di identità Azure fornisce per ottenere le credenziali senza modifiche al codice.

DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi, ad esempio ambienti locali o di produzione, senza implementare codice specifico dell'ambiente. Per altre informazioni, vedere la sezione DefaultAzureCredential di Authenticate Azure-hosted Java applications.

Per usare interfaccia della riga di comando di Azure, IntelliJ o altri metodi per completare l'autenticazione negli ambienti di sviluppo locali, vedere autenticazione Azure negli ambienti di sviluppo Java. Per completare l'autenticazione negli ambienti di hosting Azure, è consigliabile usare l'identità gestita. Per altre informazioni, vedere Che sono identità gestite per le risorse Azure?

Usare Spring Cloud Archiviazione di Azure Queue Starter

Il modulo Spring Cloud Archiviazione di Azure Queue Starter importa la libreria client Archiviazione di Azure Queue per Java con il framework Spring Boot. È possibile usare Spring Cloud Azure e i Azure SDK insieme, in un modello non che si escludono a vicenda. È quindi possibile continuare a usare l'API client Java della coda di archiviazione nell'applicazione Spring.

Aggiungere le dipendenze

Per installare il modulo Spring Cloud Archiviazione di Azure Queue Starter, aggiungere le dipendenze seguenti al file pom.xml:

  • Spring Cloud Azure Bill of Materials (Elenco dei Materiali, BOM):

    <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>com.azure.spring</groupId>
           <artifactId>spring-cloud-azure-dependencies</artifactId>
           <version>7.4.0</version>
           <type>pom</type>
           <scope>import</scope>
           </dependency>
       </dependencies>
    </dependencyManagement>
    

    Nota

    Se si usa Spring Boot 4.0.x, impostare la spring-cloud-azure-dependencies versione su 7.4.0.

    Se si usa Spring Boot 3.5.x, impostare la spring-cloud-azure-dependencies versione su 6.5.0.

    Se si usa Spring Boot 3.1.x-3.5.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 5.25.0.

    Se si usa Spring Boot 2.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 4.20.0.

    Questo Bill of Material (BOM) deve essere configurato nella sezione <dependencyManagement> del file pom.xml. In questo modo, tutte le dipendenze di Spring Cloud Azure usano la stessa versione.

    Per ulteriori informazioni sulla versione utilizzata per questo BOM, consultare Quale versione di Spring Cloud Azure dovrei usare.

  • Artefatto di Spring Cloud archiviazione code di Azure Queue:

    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-starter-storage-queue</artifactId>
    </dependency>
    

Scrivere il codice dell'applicazione per inviare e ricevere messaggi

Questa sezione illustra come usare i client archiviazione code di Azure nel contesto di un'applicazione Spring. Sono disponibili le due opzioni seguenti:

  • Usare la configurazione automatica di Spring Boot e usare client predefiniti dal contesto Spring (scelta consigliata).
  • Costruire il client programmaticamente.

Con la configurazione automatica, i bean client vengono collegati automaticamente nel contenitore di inversione del controllo (IoC) di Spring. Questo approccio offre un'esperienza più flessibile ed efficiente durante lo sviluppo con i client di Storage Queue. La configurazione automatica presenta i vantaggi seguenti:

  • La configurazione automatica usa la configurazione esterna in modo che sia possibile usare lo stesso codice dell'applicazione in ambienti diversi.

  • È possibile delegare al framework Spring Boot il processo di apprendimento del modello di generatore e la registrazione dei client nel contesto dell'applicazione. Ci si concentra solo su come usare i client con i propri requisiti aziendali.

  • È possibile usare l'indicatore di integrità per controllare lo stato e l'integrità dell'applicazione e dei componenti interni.

Gli esempi di codice nelle sezioni seguenti illustrano come usare QueueClient con le due alternative descritte.

Suggerimento

Azure Java SDK per la coda di archiviazione offre più client per interagire con la coda di archiviazione. Lo starter fornisce anche la configurazione automatica per tutti i client delle code di archiviazione e i costruttori di client. Questo articolo usa solo QueueClient come esempio.

Usare la configurazione automatica di Spring Boot

Per l'invio e la ricezione dei messaggi dalle code di Archiviazione di Azure, seguire i seguenti passaggi per configurare l'applicazione:

  1. Configura il nome dell'account di archiviazione e il nome della coda, come mostrato nell'esempio seguente.

    spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
    spring.cloud.azure.storage.queue.queue-name=<your-storage-queue-name>
    
  2. Inserire nell'applicazione QueueClient Spring e chiamare le API correlate per inviare messaggi, come illustrato nell'esempio seguente:

    import com.azure.storage.queue.QueueClient;
    import com.azure.storage.queue.models.QueueMessageItem;
    import com.azure.storage.queue.models.SendMessageResult;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.CommandLineRunner;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class StorageQueueClientApplication implements CommandLineRunner {
    
        private final static Logger logger = LoggerFactory.getLogger(StorageQueueClientApplication.class);
    
        @Autowired
        private QueueClient queueClient;
    
        public static void main(String[] args) {
            SpringApplication.run(StorageQueueClientApplication.class, args);
        }
    
        @Override
        public void run(String... args) {
         // Using the QueueClient object, call the create method to create the queue in your storage account.
            queueClient.create();
            SendMessageResult sendMessageResult = queueClient.sendMessage("Hello world");
            logger.info("Send message id: {}", sendMessageResult.getMessageId());
    
            QueueMessageItem queueMessageItem = queueClient.receiveMessage();
            logger.info("Received message: {}", new String(queueMessageItem.getBody().toBytes()));
        }
    
    }
    
  3. Avviare l’applicazione. Dopo l'avvio, l'applicazione produce log simili all'esempio seguente:

    Send message id: ...
    Received message: Hello world
    

Creare il client programmaticamente

È possibile creare i componenti client da soli, ma il processo è complicato. Nelle applicazioni Spring Boot è necessario gestire le proprietà, apprendere il modello di generatore e registrare i client nel contesto dell'applicazione Spring. I passaggi seguenti illustrano come eseguire questa operazione.

  1. Compilare il client a livello di codice nell'applicazione Spring, come illustrato nell'esempio seguente. Assicurarsi di sostituire il <storage-account-name> segnaposto con il proprio valore.

    import com.azure.identity.DefaultAzureCredentialBuilder;
    import com.azure.storage.queue.QueueClient;
    import com.azure.storage.queue.QueueClientBuilder;
    import com.azure.storage.queue.models.QueueMessageItem;
    import com.azure.storage.queue.models.SendMessageResult;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.boot.CommandLineRunner;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class StorageQueueClientApplication implements CommandLineRunner {
    
        private final static String queueName = "test-queue";
        private final static String endpoint = "https://<storage-account-name>.queue.core.windows.net/";
        private final static Logger logger = LoggerFactory.getLogger(StorageQueueClientApplication.class);
    
        QueueClient queueClient = new QueueClientBuilder()
            .endpoint(endpoint)
            .queueName(queueName)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();
    
        public static void main(String[] args) {
            SpringApplication.run(StorageQueueClientApplication.class, args);
        }
    
        @Override
        public void run(String... args) {
         // Using the QueueClient object, call the create method to create the queue in your storage account.
            queueClient.create();
            SendMessageResult sendMessageResult = queueClient.sendMessage("Hello world");
            logger.info("Send message id: {}", sendMessageResult.getMessageId());
    
            QueueMessageItem queueMessageItem = queueClient.receiveMessage();
            logger.info("Received message: {}", new String(queueMessageItem.getBody().toBytes()));
        }
    
    }
    
  2. Avviare l’applicazione. Dopo l'avvio, l'applicazione produce log simili all'esempio seguente:

    Send message id: ...
    Received message: Hello world
    

L'elenco seguente illustra i motivi per cui questo codice non è flessibile né elegante.

  • I nomi dell'account di archiviazione e della coda sono inseriti direttamente nel codice.
  • Se usi @Value per ottenere configurazioni dall'ambiente Spring, non è possibile avere suggerimenti IDE nel file application.properties.
  • Se si ha uno scenario di microservizio, è necessario duplicare il codice in ogni progetto ed è facile commettere errori e rendere difficile la coerenza.

Fortunatamente, la costruzione dei bean client da soli non è necessaria con Spring Cloud Azure. È invece possibile inserirli direttamente e usare le proprietà di configurazione già note per configurare la coda di archiviazione. Per altre informazioni, vedere Spring Cloud Azure proprietà di configurazione.

Spring Cloud Azure fornisce anche le configurazioni globali seguenti per diversi scenari. Per altre informazioni, vedere Spring Cloud Azure proprietà di configurazione globali.

  • Opzioni proxy.
  • Opzioni di ripetizione dei tentativi.

È anche possibile connettersi a cloud Azure diversi. Per altre informazioni, vedere Connect to different Azure clouds.

Utilizzare Spring Messaging nella coda di archiviazione di Azure

Il modulo Spring Messaging Archiviazione di Azure Queue fornisce supporto per Spring Messaging framework con archiviazione code di Azure.

Se si usa Spring Messaging Archiviazione di Azure Queue, è possibile usare la funzionalità StorageQueueTemplate per inviare messaggi alle code di archiviazione in modo asincrono e sincrono.

Le sezioni seguenti illustrano come utilizzare "Spring Messaging" con "Archiviazione di Azure Queue" per inviare e ricevere messaggi dalle code di archiviazione.

Aggiungere le dipendenze

Per installare il modulo Spring Messaging Archiviazione di Azure Queue, aggiungere le dipendenze seguenti al file pom.xml:

  • Spring Cloud Azure Bill of Materials (Elenco dei Materiali, BOM):

    <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>com.azure.spring</groupId>
           <artifactId>spring-cloud-azure-dependencies</artifactId>
           <version>7.4.0</version>
           <type>pom</type>
           <scope>import</scope>
           </dependency>
       </dependencies>
    </dependencyManagement>
    

    Nota

    Se si usa Spring Boot 4.0.x, impostare la spring-cloud-azure-dependencies versione su 7.4.0.

    Se si usa Spring Boot 3.5.x, impostare la spring-cloud-azure-dependencies versione su 6.5.0.

    Se si usa Spring Boot 3.1.x-3.5.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 5.25.0.

    Se si usa Spring Boot 2.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 4.20.0.

    Questo Bill of Material (BOM) deve essere configurato nella sezione <dependencyManagement> del file pom.xml. In questo modo, tutte le dipendenze di Spring Cloud Azure usano la stessa versione.

    Per ulteriori informazioni sulla versione utilizzata per questo BOM, consultare Quale versione di Spring Cloud Azure dovrei usare.

  • Gli artefatti Spring Cloud Azure starter e Spring Messaging Storage Queue:

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

Scrivere il codice dell'applicazione per inviare e ricevere messaggi

Usare la procedura seguente per configurare e codificare l'applicazione:

  1. Configurare il nome dell'account Archiviazione di Azure per le code di archiviazione, come illustrato nell'esempio seguente:

    spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
    
  2. Collegare un mittente e un destinatario per inviare e ricevere messaggi con Spring, come illustrato nell'esempio seguente. Assicurarsi di sostituire il <storage-queue-name> segnaposto con il proprio valore.

    import com.azure.spring.messaging.AzureHeaders;
    import com.azure.spring.messaging.checkpoint.Checkpointer;
    import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.CommandLineRunner;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.messaging.Message;
    import org.springframework.messaging.support.MessageBuilder;
    import java.time.Duration;
    
    @SpringBootApplication
    public class StorageQueueMessagingApplication implements CommandLineRunner {
    
        private static final Logger LOGGER = LoggerFactory.getLogger(StorageQueueMessagingApplication.class);
        private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
    
        @Autowired
        StorageQueueTemplate storageQueueTemplate;
    
        public static void main(String[] args) {
            SpringApplication.run(StorageQueueMessagingApplication.class, args);
        }
    
        @Override
        public void run(String... args) {
            storageQueueTemplate
                .sendAsync(STORAGE_QUEUE_NAME, MessageBuilder.withPayload("Hello world").build())
                .subscribe();
            LOGGER.info("Message was sent successfully.");
    
            Message<?> message = storageQueueTemplate.receiveAsync(STORAGE_QUEUE_NAME, Duration.ofSeconds(30)).block();
            LOGGER.info("Received message: {}", new String((byte[]) message.getPayload()));
        }
    
    }
    
  3. Avviare l’applicazione. Dopo l'avvio, l'applicazione produce log simili all'esempio seguente:

    Message was sent successfully.
    ...
    Received message: Hello World
    

Usare Spring Integration Archiviazione di Azure Queue

Il modulo Spring Integration Archiviazione di Azure Queue fornisce supporto per il framework Spring Integration attraverso le code di archiviazione.

Se l'applicazione Spring usa canali di messaggio Spring Integration, è possibile instradare i messaggi tra i canali di messaggio e la coda di archiviazione usando gli adattatori di canale. Un adattatore del canale in ingresso inoltra i messaggi da una coda di archiviazione a un canale di messaggio. Un adattatore di canale in uscita pubblica messaggi da un canale di messaggio a una coda di memoria.

Le sezioni seguenti illustrano come usare Spring Integration Archiviazione di Azure Queue per inviare e ricevere messaggi da e verso code di archiviazione.

Aggiungere le dipendenze

Per installare il modulo Spring Integration Archiviazione di Azure Queue, aggiungere le dipendenze seguenti al file pom.xml:

  • Spring Cloud Azure Bill of Materials (Elenco dei Materiali, BOM):

    <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>com.azure.spring</groupId>
           <artifactId>spring-cloud-azure-dependencies</artifactId>
           <version>7.4.0</version>
           <type>pom</type>
           <scope>import</scope>
           </dependency>
       </dependencies>
    </dependencyManagement>
    

    Nota

    Se si usa Spring Boot 4.0.x, impostare la spring-cloud-azure-dependencies versione su 7.4.0.

    Se si usa Spring Boot 3.5.x, impostare la spring-cloud-azure-dependencies versione su 6.5.0.

    Se si usa Spring Boot 3.1.x-3.5.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 5.25.0.

    Se si usa Spring Boot 2.x, assicurarsi di impostare la spring-cloud-azure-dependencies versione su 4.20.0.

    Questo Bill of Material (BOM) deve essere configurato nella sezione <dependencyManagement> del file pom.xml. In questo modo, tutte le dipendenze di Spring Cloud Azure usano la stessa versione.

    Per ulteriori informazioni sulla versione utilizzata per questo BOM, consultare Quale versione di Spring Cloud Azure dovrei usare.

  • Elementi di Spring Integration Archiviazione di Azure Queue:

    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-starter-integration-storage-queue</artifactId>
    </dependency>
    

Scrivere il codice dell'applicazione per inviare e ricevere messaggi

Usare la procedura seguente per configurare e codificare l'applicazione:

  1. Configurare il nome dell'account Archiviazione di Azure per le code di archiviazione.

    spring.cloud.azure.storage.queue.account-name=<your-storage-account-name>
    
  2. Creare una nuova classe QueueReceiveConfiguration Java come illustrato nell'esempio seguente. Questa classe viene usata per definire un ricevitore di messaggi. Assicurarsi di sostituire il <storage-queue-name> segnaposto con il proprio valore.

    import com.azure.spring.integration.storage.queue.inbound.StorageQueueMessageSource;
    import com.azure.spring.messaging.AzureHeaders;
    import com.azure.spring.messaging.checkpoint.Checkpointer;
    import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.integration.annotation.InboundChannelAdapter;
    import org.springframework.integration.annotation.Poller;
    import org.springframework.integration.annotation.ServiceActivator;
    import org.springframework.messaging.handler.annotation.Header;
    
    @Configuration
    public class QueueReceiveConfiguration {
    
        private static final Logger LOGGER = LoggerFactory.getLogger(QueueReceiveConfiguration.class);
        private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
        private static final String INPUT_CHANNEL = "input";
    
        @Bean
        @InboundChannelAdapter(channel = INPUT_CHANNEL, poller = @Poller(fixedDelay = "1000"))
        public StorageQueueMessageSource storageQueueMessageSource(StorageQueueTemplate storageQueueTemplate) {
            return new StorageQueueMessageSource(STORAGE_QUEUE_NAME, storageQueueTemplate);
        }
    
        @ServiceActivator(inputChannel = INPUT_CHANNEL)
        public void messageReceiver(byte[] payload, @Header(AzureHeaders.CHECKPOINTER) Checkpointer checkpointer) {
            String message = new String(payload);
            LOGGER.info("Received message: {}", message);
        }
    
    }
    
  3. Creare una nuova classe QueueSendConfiguration Java come illustrato nell'esempio seguente. Questa classe viene usata per definire un mittente di messaggi. Assicurarsi di sostituire il <storage-queue-name> segnaposto con il proprio valore.

    import com.azure.spring.integration.core.handler.DefaultMessageHandler;
    import com.azure.spring.messaging.storage.queue.core.StorageQueueTemplate;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.integration.annotation.MessagingGateway;
    import org.springframework.integration.annotation.ServiceActivator;
    import org.springframework.messaging.MessageHandler;
    import org.springframework.util.concurrent.ListenableFutureCallback;
    
    @Configuration
    public class QueueSendConfiguration {
    
        private static final Logger LOGGER = LoggerFactory.getLogger(QueueSendConfiguration.class);
        private static final String STORAGE_QUEUE_NAME = "<storage-queue-name>";
        private static final String OUTPUT_CHANNEL = "output";
    
        @Bean
        @ServiceActivator(inputChannel = OUTPUT_CHANNEL)
        public MessageHandler messageSender(StorageQueueTemplate storageQueueTemplate) {
            DefaultMessageHandler handler = new DefaultMessageHandler(STORAGE_QUEUE_NAME, storageQueueTemplate);
            handler.setSendCallback(new ListenableFutureCallback<Void>() {
                @Override
                public void onSuccess(Void result) {
                    LOGGER.info("Message was sent successfully.");
                }
    
                @Override
                public void onFailure(Throwable ex) {
                    LOGGER.info("There was an error sending the message.");
                }
            });
            return handler;
        }
    
        @MessagingGateway(defaultRequestChannel = OUTPUT_CHANNEL)
        public interface StorageQueueOutboundGateway {
            void send(String text);
        }
    
    }
    
  4. Collegare un mittente e un destinatario per inviare e ricevere messaggi con Spring.

    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.context.ConfigurableApplicationContext;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.integration.config.EnableIntegration;
    
    @SpringBootApplication
    @EnableIntegration
    @Configuration(proxyBeanMethods = false)
    public class StorageQueueIntegrationApplication {
    
        public static void main(String[] args) {
            ConfigurableApplicationContext applicationContext = SpringApplication.run(StorageQueueIntegrationApplication.class, args);
            QueueSendConfiguration.StorageQueueOutboundGateway storageQueueOutboundGateway = applicationContext.getBeanQueueSendConfiguration.StorageQueueOutboundGateway.class);
            storageQueueOutboundGateway.send("Hello World");
        }
    
    }
    

    Suggerimento

    Ricordarsi di aggiungere l'annotazione @EnableIntegration , che abilita l'infrastruttura Spring Integration.

  5. Avviare l’applicazione. Dopo l'avvio, l'applicazione produce log simili all'esempio seguente:

    Message was sent successfully.
    Received message: Hello World
    

Effettuare la distribuzione su Azure Spring Apps

Ora che l'applicazione Spring Boot è in esecuzione in locale, è possibile spostarla nell'ambiente di produzione. Azure Spring Apps semplifica la distribuzione di applicazioni Spring Boot in Azure senza modifiche al codice. Il servizio gestisce l'infrastruttura delle applicazioni Spring per consentire agli sviluppatori di concentrarsi sul codice. Azure Spring Apps offre la gestione del ciclo di vita usando monitoraggio e diagnostica completi, gestione della configurazione, individuazione dei servizi, integrazione CI/CD, distribuzioni blu-verde e altro ancora. Per distribuire l'applicazione in Azure Spring Apps, vedere Distribuire la prima applicazione in Azure Spring Apps.

Passaggi successivi

Vedi anche

Per altre informazioni sugli starter Spring Boot disponibili per Microsoft Azure, vedere Che cos'è Spring Cloud Azure?