Краткое руководство. Клиентская библиотека служба хранилища очереди Azure для Java

  • Статья

Начало работы с клиентской библиотекой служба хранилища очереди Azure для Java. Хранилище очередей Azure — это служба хранения большого количества сообщений для последующего извлечения и обработки. Выполните приведенные здесь действия, чтобы установить пакет и протестировать пример кода для выполнения базовых задач.

Справочная документация по API | Исходный код библиотеки | Пакет (Maven) | Примеры

Используйте клиентская библиотека служба хранилища очереди Azure для Java:

  • Создать очередь
  • Добавление сообщений в очередь
  • Просмотр сообщений из очереди
  • Обновление сообщений в очереди
  • Получение длины очереди
  • Получение сообщений из очереди
  • Удаление сообщений из очереди
  • Удаление очереди

Необходимые компоненты

Установка

В этом разделе описывается подготовка проекта для работы с клиентской библиотекой очередей Azure служба хранилища для Java.

Создание проекта

Создайте приложение Java с именем queues-quickstart.

  1. В окне консоли (например, cmd, PowerShell или Bash) используйте Maven для создания нового консольного приложения с очередью имен и кратким руководством. Введите следующую mvn команду, чтобы создать "Hello, world!" Проект Java.

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.queues.quickstart `
    --define artifactId=queues-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. Примерный результат создания проекта показан ниже.

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.queues.quickstart
[INFO] Parameter: artifactId, Value: queues-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/queues/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.quickstart
[INFO] Parameter: groupId, Value: com.queues.quickstart
[INFO] Parameter: artifactId, Value: queues-quickstart
[INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.394 s
[INFO] Finished at: 2019-12-03T09:58:35-08:00
[INFO] ------------------------------------------------------------------------

  3. Перейдите в только что созданный каталог queues-quickstart .

    cd queues-quickstart

Установка пакетов

Откройте файл pom.xml в текстовом редакторе.

Добавьте azure-sdk-bom , чтобы получить зависимость от последней версии библиотеки. В следующем фрагменте кода замените {bom_version_to_target} заполнитель номером версии. Использование azure-sdk-bom позволяет указать версию каждой отдельной зависимости. Дополнительные сведения о BOM см. в статье BOM SDK azure README.

<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>

Затем добавьте следующие элементы зависимостей в группу зависимостей. Зависимость удостоверений Azure необходима для бессерверных подключений к службам Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-queue</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Настройка платформы приложения

Из каталога проекта:

  1. Перейдите в каталог /src/main/java/com/queues/quickstart.
  2. Откройте файл App.java в редакторе.
  3. Удалите оператор System.out.println("Hello, world");.
  4. Добавьте директивы import.

Вот этот код:

package com.queues.quickstart;

/**
 * Azure Queue Storage client library quickstart
 */
import com.azure.identity.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Аутентификация в Azure

Запросы приложений к большинству служб Azure должны быть авторизованы. DefaultAzureCredential Использование класса, предоставленного клиентской библиотекой удостоверений Azure, является рекомендуемым подходом для реализации бессерверных подключений к службам Azure в коде.

Вы также можете авторизовать запросы к службам Azure с помощью паролей, строка подключения или других учетных данных напрямую. Однако этот подход следует использовать с осторожностью. Разработчики должны быть старательными, чтобы никогда не предоставлять эти секреты в небезопасном расположении. Любой, кто получает доступ к паролю или секретному ключу, может пройти проверку подлинности. DefaultAzureCredential предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля. Оба варианта показаны в следующем примере.

DefaultAzureCredential — это класс, предоставляемый клиентской библиотекой удостоверений Azure для Java. Дополнительные сведения DefaultAzureCredentialсм. в обзоре DefaultAzureCredential. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды.

Например, приложение может пройти проверку подлинности с помощью учетных данных входа Azure CLI при разработке локально, а затем использовать управляемое удостоверение после развертывания в Azure. Для такого перехода не требуется изменять код.

При разработке локально убедитесь, что учетная запись пользователя, которая обращается к данным очереди, имеет правильные разрешения. Вам потребуется служба хранилища участник данных очереди для чтения и записи данных очереди. Чтобы назначить себе эту роль, вам потребуется назначить роль Администратор istrator для доступа пользователей или другую роль, включающую действие Microsoft.Authorization/roleAssignments/write. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Дополнительные сведения о доступных областях назначения ролей можно узнать на странице обзора области.

В этом сценарии вы назначите разрешения учетной записи пользователя, которая ограничена учетной записью хранения, чтобы обеспечить соблюдение принципа минимальных привилегий. В рамках этой практики пользователям предоставляются только минимальные необходимые разрешения, что позволяет создавать более защищенные рабочие среды.

В следующем примере роль участника данных очереди служба хранилища назначается учетной записи пользователя, которая предоставляет доступ для чтения и записи к данным очереди в учетной записи хранения.

Важно!

В большинстве случаев для распространения назначения ролей в Azure потребуется минута или две, но в редких случаях может потребоваться до восьми минут. Если при первом запуске кода возникают ошибки аутентификации, подождите несколько минут и повторите попытку.

  1. На портале Azure найдите свою учетную запись хранения, воспользовавшись основной панелью поиска или областью навигации слева.

  2. На странице обзора учетной записи хранения выберите Контроль доступа (IAM) в меню слева.

  3. На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.

  4. Выберите + Добавить в верхнем меню, а затем выберите Добавить назначение роли в появившемся раскрывающемся меню.

A screenshot showing how to assign a role.

  1. Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере выполните поиск служба хранилища участника данных очереди и выберите соответствующий результат, а затем нажмите кнопку "Далее".

  2. В разделе Назначение доступа для выберите Пользователь, группа или субъект-служба и + Выбрать членов.

  3. В диалоговом окне найдите имя пользователя Microsoft Entra (обычно ваш user@domain адрес электронной почты), а затем выберите в нижней части диалогового окна.

  4. Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Объектная модель

Служба Хранилище очередей Azure предназначена для хранения большого количества произвольных сообщений. Максимальный размер сообщения в очереди составляет 64 КБ. Очередь может содержать миллионы сообщений вплоть до лимита всей емкости учетной записи хранения. Очереди обычно используются для создания списка невыполненных заданий для асинхронной обработки. В Хранилище очередей предлагается три типа ресурсов:

  • Учетная запись хранения. Доступ к службе хранилища Azure всегда осуществляется с помощью учетной записи хранения. Дополнительные сведения о учетных записях хранения см. в служба хранилища обзоре учетной записи
  • Очередь. Очередь содержит набор сообщений. Все сообщения должны находиться в очереди. Обратите внимание: имя очереди должно содержать только строчные символы. Дополнительные сведения см. в статье о присвоении имен очередям и метаданным.
  • Сообщение. Сообщение в любом формате размером до 64 КБ. Сообщение может оставаться в очереди не более 7 дней. Начиная с версии 2017-07-29, максимальный срок жизни может быть задан любым положительным числом или значением -1, свидетельствующим о том, что срок жизни сообщения неограничен. Если этот параметр не указан, срок жизни по умолчанию составляет семь дней.

На следующей схеме показана связь между этими ресурсами.

Diagram of Queue storage architecture

Используйте следующие классы Java для взаимодействия с этими ресурсами.

  • QueueClientBuilder: класс QueueClientBuilder настраивает объект QueueClient и создает его экземпляр.
  • QueueServiceClient: QueueServiceClient позволяет управлять всеми очередями в учетной записи хранения.
  • QueueClient: класс QueueClient позволяет управлять отдельной очередью и сообщениями в ней.
  • QueueMessageItem: класс QueueMessageItem представляет отдельные объекты, которые возвращаются при вызове ReceiveMessages для очереди.

Примеры кода

В этих примерах фрагментов кода показано, как выполнять следующие действия с помощью клиентской библиотеки Хранилища очередей Azure для Java.

Авторизация доступа и создание клиентского объекта

Убедитесь, что вы прошли проверку подлинности с той же учетной записью Microsoft Entra, которую вы назначили роли. Вы можете пройти проверку подлинности с помощью Azure CLI, Visual Studio Code или Azure PowerShell.

Войдите в Azure с помощью Azure CLI, выполнив следующую команду:

az login

После проверки подлинности можно создать и авторизовать QueueClient объект, используя DefaultAzureCredential для доступа к данным очереди в учетной записи хранения. DefaultAzureCredential автоматически обнаруживает и использует учетную запись, вошедшего в систему на предыдущем шаге.

Чтобы авторизовать использованиеDefaultAzureCredential, убедитесь, что вы добавили зависимость pom.xmlудостоверений Azure, как описано в разделе "Установка пакетов". Кроме того, обязательно добавьте директиву импорта в com.azure.identity файл App.java:

import com.azure.identity.*;

Определите имя очереди и создайте экземпляр QueueClient класса, используя DefaultAzureCredential для авторизации. Этот клиентский объект используется для создания и взаимодействия с ресурсом очереди в учетной записи хранения.

Важно!

Имя очереди может содержать только строчные буквы, цифры и дефисы и должно начинаться с буквы или цифры. Перед каждым дефисом должен быть знак без дефиса. Количество символов в имени должно быть от 3 до 63. Дополнительные сведения см. в статье о присвоении имен очередям и метаданным.

Добавьте этот код в main метод и замените <storage-account-name> значение заполнителя:

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
// TODO: replace <storage-account-name> with the actual name
QueueClient queueClient = new QueueClientBuilder()
        .endpoint("https://<storage-account-name>.queue.core.windows.net/")
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

Примечание.

Сообщения, отправленные QueueClient с помощью класса, должны находиться в формате, который может быть включен в XML-запрос с кодировкой UTF-8. При необходимости можно задать параметр QueueMessageEncoding для BASE64 обработки сообщений, не соответствующих требованиям.

Создать очередь

QueueClient С помощью объекта вызовите create метод для создания очереди в учетной записи хранения.

Добавьте следующий код в конец метода main.

System.out.println("Creating queue: " + queueName);

// Create the queue
queueClient.create();

Добавление сообщений в очередь

Следующий фрагмент кода добавляет сообщения в очередь, вызывая метод sendMessage. Он также сохраняет SendMessageResult, возвращенный вызовом sendMessage. Этот результат используется для обновления сообщения далее в коде программы.

Добавьте следующий код в конец метода main.

System.out.println("\nAdding messages to the queue...");

// Send several messages to the queue
queueClient.sendMessage("First message");
queueClient.sendMessage("Second message");

// Save the result so we can update this message later
SendMessageResult result = queueClient.sendMessage("Third message");

Просмотр сообщений из очереди

Чтобы просмотреть сообщения в очереди, вызовите метод peekMessages. Этот метод извлекает одно или несколько сообщений из начала очереди, не изменяя видимость этих сообщений.

Добавьте следующий код в конец метода main.

System.out.println("\nPeek at the messages in the queue...");

// Peek at messages in the queue
queueClient.peekMessages(10, null, null).forEach(
    peekedMessage -> System.out.println("Message: " + peekedMessage.getMessageText()));

Обновление сообщений в очереди

Чтобы обновить содержимое сообщения, вызовите метод updateMessage. Этот метод позволяет изменить время видимости сообщения и его содержимое. Содержимое сообщение должно иметь формат строки в кодировке UTF-8 длиной не более 64 КБ. Вместе с новым содержимым сообщения передайте идентификатор сообщения и подтверждение извлечения, используя сохраненный ранее SendMessageResult. Идентификатор сообщения и подтверждение извлечения указывают, какое сообщение следует обновить.

System.out.println("\nUpdating the third message in the queue...");

// Update a message using the result that
// was saved when sending the message
queueClient.updateMessage(result.getMessageId(),
                          result.getPopReceipt(),
                          "Third message has been updated",
                          Duration.ofSeconds(1));

Получение длины очереди

Вы можете узнать приблизительное количество сообщений в очереди.

Метод getProperties возвращает несколько значений, включая количество сообщений, находящихся в очереди в данный момент. Счетчик указывает число лишь приблизительно, так как сообщения могут добавляться или удаляться из вашего запроса. Метод getApproximateMessageCount возвращает последнее значение, полученное при вызове метода getProperties, без вызова хранилища очередей.

QueueProperties properties = queueClient.getProperties();
long messageCount = properties.getApproximateMessagesCount();

System.out.println(String.format("Queue length: %d", messageCount));

Получение и удаление сообщений из очереди

Чтобы скачать ранее добавленные сообщения, вызовите метод receiveMessages. Также этот пример кода удаляет из очереди сообщения, которые уже получены и обработаны. В нашем примере обработка сводится к выводу сообщения в консоль.

Перед получением и удалением сообщений приложение ожидает ввода от пользователя, вызывая метод System.console().readLine();. Перед удалением ресурсов убедитесь на портале Azure, что они были правильно созданы. Все сообщения, которые явно не удалены, в конечном итоге становятся видимыми в очереди еще раз, чтобы еще один шанс обработать их.

Добавьте следующий код в конец метода main.

System.out.println("\nPress Enter key to receive messages and delete them from the queue...");
System.console().readLine();

// Get messages from the queue
queueClient.receiveMessages(10).forEach(
    // "Process" the message
    receivedMessage -> {
        System.out.println("Message: " + receivedMessage.getMessageText());

        // Let the service know we're finished with
        // the message and it can be safely deleted.
        queueClient.deleteMessage(receivedMessage.getMessageId(), receivedMessage.getPopReceipt());
    }
);

При вызове receiveMessages метода можно дополнительно указать значение maxMessagesдля , которое является числом сообщений, извлекаемых из очереди. Значение по умолчанию — 1 сообщение, а максимальное — 32 сообщения. Можно также указать значение, visibilityTimeoutкоторое скрывает сообщения от других операций за период ожидания. Значение по умолчанию — 30 секунд.

Удаление очереди

Следующий код очищает созданные приложением ресурсы, удаляя очередь с помощью метода Delete.

Добавьте следующий код в конец метода main.

System.out.println("\nPress Enter key to delete the queue...");
System.console().readLine();

// Clean up
System.out.println("Deleting queue: " + queueClient.getQueueName());
queueClient.delete();

System.out.println("Done");

Выполнение кода

Это приложение создает три сообщения и добавляет их в очередь Azure. Затем код получает список сообщений, извлекает и удаляет их, и наконец удаляет саму очередь.

В окне консоли перейдите к каталогу приложения, выполните его сборку и запустите его.

mvn compile

Затем выполните сборку пакета.

mvn package

Выполните следующую команду mvn для запуска этого приложения.

mvn exec:java -Dexec.mainClass="com.queues.quickstart.App" -Dexec.cleanupDaemonThreads=false

Вы должны увидеть выходные данные приложения, как показано ниже.

Azure Queue Storage client library - Java quickstart sample

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Press Enter key to receive messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-fbf58f33-4d5a-41ac-ac0e-1a05d01c7003
Done

Когда приложение приостановится перед получением сообщений, проверьте учетную запись хранения на портале Azure. Убедитесь, что сообщения находятся в очереди.

Нажмите клавишу Enter, чтобы получить и удалить сообщения. При появлении запроса снова нажмите клавишу Enter, чтобы удалить очередь и завершить демонстрацию.

Следующие шаги

Из этого краткого руководства вы узнали, как создавать очередь и добавлять в нее сообщения из кода на Java. Затем вы изучили процессы вставки, просмотра, получения и удаления сообщений. Наконец, вы узнали, как удалить очередь сообщений.

Руководства, примеры, краткие руководства и другую документацию можно найти здесь:

Azure для разработчиков облачных приложений Java