Поделиться через

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

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

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

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

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

Предпосылки

Настройка

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

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

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

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

    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 см. в README BOM Azure SDK.

<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-identity необходима для безпарольных подключений к службам 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 Identity, является рекомендуемым подходом для реализации подключений к службам Azure без пароля в вашем коде.

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

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

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

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

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

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

Это важно

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

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

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

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

  4. Выберите +Добавить из верхнего меню и добавьте назначение ролей из результирующего раскрывающегося меню.

Снимок экрана, на котором продемонстрировано назначение роли.

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

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

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

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

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

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

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

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

Схема архитектуры хранилища очередей

Используйте следующие классы 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, убедитесь, что вы добавили зависимость azure-identity в pom.xml, как описано в разделе "Установка пакетов". Кроме того, обязательно добавьте директиву 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 метод. Этот метод может изменить время видимости (timeout) и содержимое сообщения. Содержимое сообщения должно быть закодированной строкой 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

  • Last updated on