Быстрый старт: Расширение Quarkus для Blob-хранилища Azure

Начало работы с расширением Quarkus для Azure Blob Storage для управления блобами и контейнерами. В этой статье описано, как попробовать пример кода для основных задач.

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

Предпосылки

Учетная запись Azure с активной подпиской — создайте учетную запись бесплатно.
Azure CLI. Установите Azure CLI 2.62.0 или более поздней версии для выполнения команд Azure CLI.
Учетная запись хранения Azure — создайте учетную запись хранения.
Пакет средств разработки Java (JDK) версии 17 или более поздней.
Apache Maven.

Настройка

В этом разделе описывается подготовка проекта для работы с расширениями Quarkus для хранилища BLOB-объектов Azure.

Скачивание примера приложения

Пример приложения, используемого в этом кратком руководстве, является базовым приложением Quarkus.

Используйте git , чтобы скачать копию приложения в среду разработки и перейти к каталогу storage-blob-quarkus .

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

Аутентификация в Azure и авторизация доступа к данным блоб-объектов

Запросы приложений к хранилищу BLOB-объектов Azure должны быть авторизованы. Использование DefaultAzureCredential и клиентской библиотеки удостоверений Azure — это рекомендуемый подход для реализации беспарольных подключений к службам Azure в вашем коде, включая хранилище объектов Blob. Расширение Quarkus для служб Azure поддерживает этот подход.

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

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

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

Назначение ролей учетной записи пользователя Microsoft Entra

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

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

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

Это важно

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

На портале Azure найдите свою учетную запись хранения, воспользовавшись основной панелью поиска или областью навигации слева.
На странице обзора учетной записи хранилища выберите Управление доступом (IAM) в меню слева.
На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.
Выберите +Добавить из верхнего меню и добавьте назначение ролей из результирующего раскрывающегося меню.
Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере найдите Storage Blob Data Contributor, выберите соответствующий результат, а затем выберите ‘Next’.
В разделе Назначение доступа выберите Пользователь, группа или сервисный принципал, а затем нажмите + Выбрать участников.
В диалоговом окне найдите имя пользователя Microsoft Entra (обычно ваш адрес электронной почты user@domain), а затем выберите Select в нижней части диалогового окна.
Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Чтобы назначить роль на уровне ресурсов с помощью Azure CLI, сначала необходимо получить идентификатор ресурса с помощью az storage account show команды. Вы можете отфильтровать выходные свойства с помощью параметра --query.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Скопируйте результат Id из предыдущей команды. Затем можно назначить роли с помощью команды az role в Azure CLI.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Чтобы назначить роль на уровне ресурсов с помощью Azure PowerShell, сначала необходимо получить идентификатор ресурса с помощью Get-AzResource команды.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Скопируйте значение Id из выходных данных предыдущей команды. После этого можно назначить роли с помощью команды New-AzRoleAssignment в PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

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

Убедитесь, что вы прошли проверку подлинности с той же учетной записью Microsoft Entra, которую вы назначили роль учетной записи хранения. В следующем примере показано, как пройти проверку подлинности с помощью Azure CLI:
```
az login
```
Убедитесь, что вы указали конечную точку вашей учетной записи Azure Blob Storage. В следующем примере показано, как задать конечную точку с помощью переменной QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT среды с помощью Azure CLI. Перед выполнением команды замените <resource-group-name> и <storage-account-name> на названия вашей группы ресурсов и учетной записи хранения.
```
export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)
```

Замечание

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

Запустите пример

В примере кода выполняются следующие действия:

Внедряет клиентский объект, который уже авторизован для доступа к данным с помощью DefaultAzureCredential расширения Quarkus для хранилища BLOB-объектов Azure.
Создает контейнер в учетной записи хранения.
Загружает BLOB в контейнер.
Перечисляет блобы в контейнере.
Загружает данные BLOB в локальную файловую систему.
Удаляет ресурсы BLOB-объектов и контейнеров, созданные приложением.
Удаляет локальный источник и скачанные файлы.

Запустите приложение в режиме JVM, выполнив следующую команду:

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

Выходные данные приложения аналогичны следующему примеру (значения UUID, пропущенные для удобочитаемости):

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

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

При необходимости можно запустить пример в родном режиме. Для этого необходимо установить GraalVM или использовать сборочный образ для создания нативного исполняемого файла. Дополнительные сведения см. в разделе "Создание собственного исполняемого файла". В этом кратком руководстве используется Docker в качестве среды выполнения контейнера для создания нативного исполняемого файла Linux. Если вы не установили Docker, его можно скачать на веб-сайте Docker.

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

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

Понять пример кода

Далее вы изучите пример кода, чтобы понять, как это работает.

Внедрение клиентского объекта с авторизованным доступом

Работа с любым ресурсом Azure с помощью пакета SDK начинается с создания клиентского объекта. Расширение Quarkus для хранилища Azure Blob Storage автоматически подключает клиентский объект с авторизованным доступом с помощью DefaultAzureCredential.

Чтобы успешно внедрить клиентский объект, сначала необходимо добавить расширения quarkus-arc и quarkus-azure-storage-blob в файл pom.xml в качестве зависимостей:

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

Расширение quarkus-arc требуется для использования заметки @Inject для внедрения клиентского объекта в код приложения. Зависимости quarkus-bom и quarkus-azure-services-bom используются для управления версиями платформы Quarkus и расширения Quarkus для служб Azure.

Затем можно внедрить клиентский объект в код приложения с помощью заметки @Inject :

@Inject
BlobServiceClient blobServiceClient;

Вот весь код, который необходим для получения клиентского объекта с помощью расширения Quarkus для хранилища BLOB-объектов Azure. Чтобы убедиться, что клиентский объект авторизован для доступа к учетной записи хранения во время выполнения, необходимо выполнить действия, описанные в предыдущем разделе "Проверка подлинности в Azure" и авторизацию доступа к данным BLOB-объектов перед запуском приложения.

Управление блобами и контейнерами

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

Замечание

Запись в локальную файловую систему считается плохой практикой в облачных собственных приложениях. Однако в примере используется локальная файловая система, чтобы проиллюстрировать использование BLOB-хранилища таким образом, чтобы пользователь мог легко проверить. Когда вы берете приложение в рабочую среду, просмотрите параметры хранилища и выберите оптимальный вариант для ваших потребностей. Дополнительные сведения см. в разделе "Просмотр параметров хранилища".

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

Эти операции похожи на те, которые описаны в кратком руководстве: клиентская библиотека хранилища BLOB-объектов Azure для Java SE. Более подробные объяснения кода см. в следующих разделах в этом кратком руководстве.

Очистка

Чтобы развернуть приложение Quarkus в Azure, перейдите по ссылкам в разделе "Дальнейшие действия ". Кроме того, можно очистить учетную запись хранения, удалив группу ресурсов. Дополнительные сведения см. в разделе "Группа ресурсов Azure Resource Manager" и удаление ресурсов.

Дальнейшие шаги

Примеры использования службы хранилища Azure и руководства для разработчиков по Java Развертывание Java-приложения с Quarkus в кластере Azure Kubernetes Service Развертывание Java-приложения с Quarkus в Azure Container Apps

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-10-09