Краткое руководство. Хранилище BLOB-объектов Azure клиентская библиотека для Java

  • Статья

Примечание.

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

Примечание.

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

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

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

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

Совет

Если вы работаете с ресурсами служба хранилища Azure в приложении Spring, рекомендуется использовать Spring Cloud Azure в качестве альтернативы. Spring Cloud Azure — это проект с открытым исходным кодом, который обеспечивает простую интеграцию Spring со службами Azure. Дополнительные сведения о Spring Cloud 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 создайте другой каталог, называемый данными. В этой папке будут созданы и сохранены файлы данных BLOB-объектов.

    mkdir data

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

Откройте файл 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-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 можно создать учетную запись хранения и запустить пример кода с помощью нескольких команд. Проект можно запустить в локальной среде разработки или в DevContainer.

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

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

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

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

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

    • Имя среды: это значение используется в качестве префикса для всех ресурсов Azure, созданных Azure Developer CLI. Имя должно быть уникальным для всех подписок 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
  • Просмотрите выходные данные: это приложение создает тестовый файл в локальной папке данных и отправляет его в контейнер в учетной записи хранения. После этого выводится список больших двоичных объектов в контейнере, а затем файл загружается с новым именем, чтобы можно было сравнить старый и новый файлы.

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

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

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

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

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

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

Diagram of Blob storage architecture

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

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

Примеры кода

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

Внимание

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

Примечание.

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

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

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

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

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

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

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

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

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

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

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

Внимание

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

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

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

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

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

    A screenshot showing how to assign a role.

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

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

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

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

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

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

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

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

    az login

  2. Чтобы использовать DefaultAzureCredential, убедитесь, что зависимость удостоверений Azure добавляется в 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.

    A screenshot showing how to find the storage account name.

    Примечание.

    При развертывании в 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-объектов с помощью 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);

Дополнительные сведения о отправке больших двоичных объектов и изучении дополнительных примеров кода см. в статье "Отправка большого двоичного объекта с помощью Java".

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

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

Добавьте следующий код в конец метода 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.

скачивание больших двоичных объектов;

Скачайте созданный ранее большой двоичный объект, вызвав метод 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);

Дополнительные сведения о скачивании больших двоичных объектов и дополнительные примеры кода см. в статье "Скачать большой двоичный объект с помощью Java".

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

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

Приложение приостанавливается для ввода пользователя, вызывая 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-объектов с помощью Java".

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

В этом приложении тестовый файл создается в локальной папке, а затем передается в хранилище 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-pluginpom.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. Вы можете сравнить их и наблюдать, что они идентичны.

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

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

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

azd down

Вам будет предложено подтвердить удаление ресурсов. Введите y для подтверждения.

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

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

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

библиотека Хранилище BLOB-объектов Azure для примеров Java