Краткое руководство: Клиентская библиотека хранилища Blob-объектов Azure для Java SE

Примечание.

Опция «Build from Scratch» помогает вам создать проект, установить пакеты, написать код и запустить базовое консольное приложение. Выберите этот вариант, чтобы понять, как создать приложение, подключаемое к Хранилище BLOB-объектов Azure. Чтобы автоматизировать задачи развертывания и начать с готового проекта, выберите «Начать с шаблона».

Примечание.

Опция «Начать с шаблона» использует CLI Azure Developer для автоматизации задач развертывания и предоставляет завершённый проект. Выберите этот вариант, чтобы исследовать код, не выполняя задачи по установке. Чтобы получить пошаговые инструкции по сборке приложения, выберите Build from scratch.

Начните работать с клиентской библиотекой Хранилище BLOB-объектов Azure на Java для управления объектами BLOB и контейнерами.

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

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

Совет

Для приложений Spring, использующих ресурсы служба хранилища Azure, рассмотрите Spring Cloud Azure. Этот проект с открытым исходным кодом интегрирует Spring с сервисами Azure. Для примера Хранилище BLOB-объектов см. Загрузить файл в служба хранилища Azure Blob.

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

Необходимые условия

Установка

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

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

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

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

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.blobs.quickstart `
    --define artifactId=blob-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.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.056 s
[INFO] Finished at: 2019-10-23T11:09:21-07:00
[INFO] ------------------------------------------------------------------------
    ```

  3. Перейдите в только что созданную папку blob-quickstart .

    cd blob-quickstart

  4. Внутри каталога blob-quickstart создайте ещё одну папку под названием data. В этой папке создаются и хранятся файлы данных blob.

    mkdir data

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

Откройте файл 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 требуется зависимость azure-identity.

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

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

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

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

Код должен напоминать следующий шаблон:

package com.blobs.quickstart;

/**
 * Azure Blob Storage quickstart
 */
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;

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

Используя Azure Developer CLI, вы можете создать аккаунт хранения и выполнить примерный код всего несколькими командами. Вы можете запустить проект в локальной среде разработки или в DevContainer.

Инициализация шаблона интерфейса командной строки разработчика Azure и развертывание ресурсов

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

  • Клонируйте ресурсы репозитория быстрого запуска из GitHub и инициализируйте шаблон локально.

    azd init --template blob-storage-quickstart-java

    Вам будет предложено получить следующие сведения:

    • Environment name: Azure Developer CLI использует это значение в качестве префикса для всех ресурсов Azure, которые она создаёт. Имя должно быть уникальным для всех Azure подписок и в диапазоне от 3 до 24 символов. Имя может содержать только цифры и строчные буквы.

  • Войдите в Azure:

    azd auth login

  • Подготовка и развертывание ресурсов в Azure:

    azd up

    Вам будет предложено получить следующие сведения:

    • Подписка: подписка Azure для развертывания ваших ресурсов.
    • Местоположение: регион Azure для развертывания ваших ресурсов.

    Завершение развертывания может занять несколько минут. Результат выполнения команды azd up включает имя вновь созданной учетной записи хранения, которое позже понадобится для запуска кода.

Запуск примера кода

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

  • Обновите имя учетной записи хранения:
    1. В локальном каталоге перейдите к каталогу blob-quickstart/src/main/java/com/blobs/quickstart .
    2. Откройте файл с именем App.java в редакторе. Найдите заполнитель <storage-account-name> и замените его на настоящее имя учетной записи хранения, созданной командой azd up.
    3. Сохраните изменения.
  • Запустите проект:
    1. Перейдите в каталог blob-quickstart, содержащий pom.xml файл. Скомпилируйте проект с помощью следующей mvn команды: 
      mvn compile
    2. Упаковайте скомпилированный код в его распространяемом формате: 
      mvn package
    3. Выполните следующую mvn команду, чтобы выполнить приложение: 
      mvn exec:java
  • Просмотрите выходные данные: это приложение создает тестовый файл в локальной папке данных и отправляет его в контейнер в учетной записи хранения. Затем пример выводит список BLOB-объектов в контейнере и загружает файл с новым именем, чтобы можно было сравнить старый и новый файлы.

Дополнительные сведения о том, как работает образец кода, см. в примерах кода.

После завершения тестирования кода необходимо зайти в раздел Очистка ресурсов, чтобы удалить ресурсы, созданные командой azd up.

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

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

  • учетная запись хранения;
  • контейнер в учетной записи хранения;
  • блоб в контейнере

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

Диаграмма с изображением учётной записи хранения, содержащей контейнер BLOB-объектов и BLOB-объект.

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

  • BlobServiceClient: Класс BlobServiceClient управляет ресурсами служба хранилища Azure и blob containers. Учетная запись хранения предоставляет пространство имен верхнего уровня для службы Blob.
  • BlobServiceClientBuilder: Класс BlobServiceClientBuilder предоставляет свободный API для настройки и создания BlobServiceClient объектов.
  • BlobContainerClient: BlobContainerClient Класс управляет контейнерами служба хранилища Azure и их blob-ами.
  • BlobClient: Класс BlobClient управляет BLOB-объектами в служба хранилища Azure.
  • BlobItem: класс BlobItem представляет отдельные BLOB-объекты, возвращаемые при вызове метода listBlobs.

Примеры кода

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

Внимание

Добавьте зависимости и директивы, описанные в разделе «Настройка», прежде чем использовать образцы кода.

Примечание.

Шаблон ИНТЕРФЕЙСА командной строки разработчика Azure содержит файл с примером кода. В следующих примерах приведены подробные сведения для каждой части примера кода. Шаблон реализует рекомендуемый метод проверки подлинности без пароля, как описано в разделе "Проверка подлинности в Azure ". Метод строки подключения представлен как альтернатива, но не используется в шаблоне и не рекомендуется для промышленного кода.

Проверка подлинности в Azure и авторизация доступа к данным BLOB

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

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

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

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

Например, ваше приложение может аутентифицироваться, используя учетные данные входа в Visual Studio Code при локальной разработке. После развертывания в Azure ваше приложение сможет использовать управляемую идентичность. Для такого перехода не требуется изменять код.

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

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

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

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

Внимание

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

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

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

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

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

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

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

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

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

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

Войдите и подключите код приложения к Azure с помощью DefaultAzureCredential

Авторизуйте доступ к данным в вашем аккаунте хранения, следуя следующим шагам:

  1. Аутентифицируйтесь, используя тот же аккаунт Microsoft Entra, которому вы назначили роль аккаунта хранения. Используйте Azure CLI, Visual Studio Code или Azure PowerShell.

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

    az login

  2. Чтобы использовать DefaultAzureCredential, добавьте зависимость azure-identity в pom.xml:

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

  3. Добавьте этот код в main метод. Когда код работает на вашей локальной рабочей станции, он использует учетные данные разработчика приоритетного инструмента, в который вы вошли, для аутентификации в Azure, например, Azure CLI или Visual Studio Code.

    /*
 * The default credential first checks environment variables for configuration
 * If environment configuration is incomplete, it will try managed identity
 */
DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(defaultCredential)
        .buildClient();

  4. Обновите имя учётной записи хранения в URI вашего BlobServiceClient. Найдите имя аккаунта хранения на обзорной странице в портале Azure.

    Снимок экрана: как найти имя учетной записи хранения.

    Примечание.

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

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

Создайте контейнер в учетной записи хранения, вызвав метод createBlobContainer в объекте blobServiceClient . В этом примере код добавляет значение GUID к имени контейнера, чтобы убедиться, что он уникальный.

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

// 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);

Для получения дополнительной информации и примеров см. раздел «Создать blob container с помощью Java».

Внимание

Имена контейнеров должны состоять из знаков нижнего регистра. Дополнительные сведения об именовании контейнеров и больших двоичных объектов см. в статье Naming and Referencing Containers, Blobs, and Metadata (Именование контейнеров, больших двоичных объектов и метаданных и ссылка на них).

Загрузка блобов в контейнер.

Загрузите двоичный объект в контейнер, вызвав метод uploadFromFile. Пример кода создает текстовый файл в локальном каталоге данных для отправки в контейнер.

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

// 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);

Для получения дополнительной информации и примеров см. Загрузить blob с помощью Java.

Перечисление BLOB-объектов в контейнере

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

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

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

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

Для получения дополнительной информации и примеров см. раздел «Список блобов с Java».

Скачивание blobов

Скачайте ранее созданный объект blob, вызвав метод downloadToFile. Примерный код добавляет суффикс DOWNLOAD к имени файла, чтобы вы могли видеть оба файла в локальной файловой системе.

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

// 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);

Для получения дополнительной информации и примеров см. Скачивание BLOB с помощью Java.

Удаление контейнера

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

Приложение приостанавливается для ввода пользователя, вызывая System.console().readLine(), перед удалением блоба, контейнера и локальных файлов. Эта пауза даёт возможность убедиться, что приложение правильно создало ресурсы, прежде чем их удалять.

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

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 container с помощью Java.

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

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

Следуйте следующим шагам для компиляции, упаковки и запуска кода:

  1. Перейдите в каталог, pom.xml содержащий файл, и скомпилируйте проект с помощью следующей mvn команды: 
    mvn compile
  2. Упаковайте скомпилированный код в его распространяемом формате: 
    mvn package
  3. Выполните следующую mvn команду, чтобы выполнить приложение: 
    mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
    Чтобы упростить этап выполнения, добавьте exec-maven-plugin и pom.xml настройте его, как показано в следующем коде: 
    <plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>1.4.0</version>
  <configuration>
    <mainClass>com.blobs.quickstart.App</mainClass>
    <cleanupDaemonThreads>false</cleanupDaemonThreads>
  </configuration>
</plugin>
    В этой конфигурации выполните приложение следующей командой: 
    mvn exec:java

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

Azure Blob Storage - Java quickstart sample

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

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

Очистка ресурсов

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

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

azd down

Вы получаете запрос подтвердить удаление ресурсов. Введите y для подтверждения.

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

Примеры служба хранилища Azure и руководства для разработчиков по JavaКраткое руководство: расширение Quarkus для Хранилище BLOB-объектов AzureИспользование Spring Boot для отправки файла в Хранилище BLOB-объектов Azure

  • Последнее обновление: