Начало работы с Хранилище BLOB-объектов Azure и Java

Статья
10/22/2024

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

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

Примеры | исходного кода | библиотеки api reference | Package (Maven) | Library дают отзыв

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

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

Настройка проекта

Примечание.

В рамках этой статьи для сборки и запуска примера кода используется средство сборки Maven. Для работы с пакетами SDK Azure для Java есть и другие средства сборки, например Gradle.

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

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

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

Включение BOM-файла

Добавьте 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-storage-common</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Включение прямой зависимости

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

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>{package_version_to_target}</version>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
      <version>{package_version_to_target}</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{package_version_to_target}</version>
</dependency>

Включение директив импорта

Затем откройте файл кода и добавьте необходимые import директивы. В этом примере мы добавим в файл App.java следующие директивы:

import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.specialized.*;
import com.azure.storage.common.*;

Сведения о клиентской библиотеке BLOB-объектов:

com.azure.storage.blob: содержит основные классы (клиентские объекты), которые можно использовать для работы со службой, контейнерами и большими двоичными объектами.
com.azure.storage.blob.models: содержит служебные классы, структуры и типы перечисления.
com.azure.storage.blob.specialized: содержит классы, которые можно использовать для выполнения операций, относящихся к типу BLOB-объектов (например, добавление больших двоичных объектов).

Авторизация доступа и подключения к хранилищу BLOB-объектов

Чтобы подключить приложение к хранилищу BLOB-объектов, создайте экземпляр класса BlobServiceClient . Вы также можете использовать класс BlobServiceAsyncClient для асинхронного программирования. Этот объект является отправной точкой для взаимодействия с ресурсами данных на уровне учетной записи хранения. Его можно использовать для работы с учетной записью хранения и ее контейнерами. Вы также можете использовать клиент службы для создания клиентов контейнеров или клиентов БОЛЬШИХ двоичных объектов в зависимости от ресурса, с которым требуется работать.

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

Вы можете авторизовать BlobServiceClient объект с помощью маркера авторизации Microsoft Entra, ключа доступа к учетной записи или подписанного URL-адреса (SAS). Для оптимальной безопасности корпорация Майкрософт рекомендует использовать идентификатор Microsoft Entra с управляемыми удостоверениями для авторизации запросов к данным BLOB-объектов. Дополнительные сведения см. в разделе "Авторизация доступа к BLOB-объектам" с помощью идентификатора Microsoft Entra.

Для авторизации с помощью идентификатора Microsoft Entra необходимо использовать субъект безопасности. Какой тип субъекта безопасности требуется, зависит от того, где выполняется ваше приложение. Руководствуйтесь следующей таблицей.

Где выполняется приложение	Субъект безопасности	Руководство
Локальный компьютер (разработка и тестирование)	Субъект-служба	Сведения о регистрации приложения, настройке группы Microsoft Entra, назначении ролей и настройке переменных среды см. в статье "Авторизация доступа с помощью субъектов-служб разработчиков".
Локальный компьютер (разработка и тестирование)	Удостоверение пользователя	Сведения о настройке группы Microsoft Entra, назначении ролей и входе в Azure см. в статье "Авторизация доступа с помощью учетных данных разработчика".
Размещено в Azure	Управляемое удостоверение	Сведения о включении управляемого удостоверения и назначении ролей см. в статье "Авторизация доступа из размещенных в Azure приложений с помощью управляемого удостоверения".
Размещенные вне Azure (например, локальные приложения)	Субъект-служба	Сведения о регистрации приложения, назначении ролей и настройке переменных среды см. в статье "Авторизация доступа из локальных приложений с помощью субъекта-службы приложений"

Авторизация доступа с помощью DefaultAzureCredential

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

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

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

// 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(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

Используйте BLOBServiceClientBuilder для создания объекта BLOBServiceClient с помощью маркера SAS:

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .sasToken(sasToken)
            .buildClient();

    return blobServiceClient;
}

Дополнительные сведения о создании маркеров SAS и управлении ими см. в следующих статьях:

Примечание.

В сценариях, когда используются подписанные URL-адреса (SAS), корпорация Майкрософт рекомендует использовать SAS делегирования пользователей. SAS делегирования пользователей защищены учетными данными Microsoft Entra вместо ключа учетной записи.

Создайте объект StorageSharedKeyCredential с помощью имени учетной записи хранения и ключа учетной записи. Затем инициализировать объект BlobServiceClient используйте этот объект.

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Azure SDK client builders accept the credential as a parameter
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))
            .credential(credential)
            .buildClient();

    return blobServiceClient;        
}

Вы также можете создать BlobServiceClient объект с помощью строка подключения.

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {
    // 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/")
            .connectionString(connectionString)
            .buildClient();

    return blobServiceClient;        
}

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

Внимание

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

Настройка TTL JVM для подстановок DNS-имен

Виртуальная машина Java (JVM) кэширует ответы из успешных подстановок DNS-имен в течение указанного периода времени, известного как срок жизни (TTL). Значение TTL по умолчанию для многих виртуальных машин — это -1означает, что JVM кэширует ответ на неопределенный срок или до перезапуска JVM.

Так как ресурсы Azure используют записи DNS-имен, которые могут измениться, рекомендуется задать значение TTL JVM в 10 секунд. Эта конфигурация гарантирует, что обновленный IP-адрес ресурса возвращается с помощью следующего DNS-запроса.

Чтобы глобально изменить значение TTL для всех приложений с помощью JVM, задайте networkaddress.cache.ttl свойство в java.security файле.

networkaddress.cache.ttl=10

Для Java 8 java.security файл находится в каталоге $JAVA_HOME/jre/lib/security . Для Java 11 и более поздних версий файл находится в каталоге $JAVA_HOME/conf/security .

Сборка приложения

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

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

Руководство	Description
Настройка политики повторных попыток	Реализуйте политики повторных попыток для клиентских операций.
Копирование больших двоичных объектов	Скопируйте большой двоичный объект из одного расположения в другое.
Создание контейнера	Создание контейнеров BLOB-объектов.
Создание SAS для делегирования пользователя	Создайте SAS делегирования пользователей для контейнера или большого двоичного объекта.
Создание аренды BLOB-объектов и управление ими	Создайте блокировку большого двоичного объекта и управляйте ими.
Создание аренды контейнеров и управление ими	Создайте блокировку контейнера и управляйте ею.
Удаление и восстановление больших двоичных объектов	Удаление BLOB-объектов. Если включено обратимое удаление, восстановление удаленных BLOB-объектов.
Удаление и восстановление контейнеров	Удаление контейнеров. Если включено обратимое удаление включено, восстановление удаленных контейнеров.
скачивание больших двоичных объектов;	Скачивание BLOB-объектов с помощью строк, потоков и путей к файлам.
Поиск BLOB-объектов с помощью тегов	Задание и извлечение тегов, а также использование тегов для поиска BLOB-объектов.
Перечисление больших двоичных объектов	Перечисление BLOB-объектов различными способами.
Перечисление контейнеров	Перечисление контейнеров в учетной записи и различные параметры, доступные для настройки списка.
Управление свойствами и метаданными (BLOB-объектами)	Получение и задание свойств и метаданных для BLOB-объектов.
Управление свойствами и метаданными (контейнерами)	Получение и задание свойств и метаданных для контейнеров.
Настройка производительности для передачи данных	Оптимизируйте производительность операций передачи данных.
Установка или изменение уровня доступа большого двоичного объекта	Задайте или измените уровень доступа для блочного большого двоичного объекта.
отправка больших двоичных объектов;	Отправка BLOB-объектов с помощью строк, потоков, путей к файлам и других методов.

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