Отправка блочного BLOB-объекта с помощью Java

• .NET
• Java
• JavaScript
• Python
• Иди

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

Предварительные условия

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

Настройка среды

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

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

Примечание.

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

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

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

Добавьте инструкции импорта

Добавьте следующие import инструкции:

import com.azure.core.http.rest.*;
import com.azure.core.util.BinaryData;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.options.BlobUploadFromFileOptions;
import com.azure.storage.blob.specialized.*;

import java.io.ByteArrayInputStream;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.time.Duration;
import java.util.*;

Авторизация

Механизм авторизации должен иметь необходимые разрешения для отправки объекта blob. Для авторизации с помощью идентификатора Microsoft Entra (рекомендуется) требуется встроенная роль управления доступом на основе ролей (RBAC) Сотрудник данных BLOB-объектов хранилища или более высокая. Дополнительные сведения см. в руководстве по авторизации для Put Blob (REST API) и Put Block (REST API).

Создание клиентского объекта

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

В следующем примере используется 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>");

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

Отправка данных в блочный BLOB-объект

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

• отправить

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

• uploadFromFile

Каждый из этих методов можно вызывать с помощью объекта BLOBClient или объекта BlockBlobClient.

Примечание.

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

Загрузить блочный BLOB-объект из локального пути к файлу

В следующем примере файл загружается в блоковый блоб с помощью объекта BlobClient.

public void uploadBlobFromFile(BlobContainerClient blobContainerClient) {
    BlobClient blobClient = blobContainerClient.getBlobClient("sampleBlob.txt");

    try {
        blobClient.uploadFromFile("filepath/local-file.png");
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

Загрузите блочный BLOB-объект из потока

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

public void uploadBlobFromStream(BlobContainerClient blobContainerClient) {
    BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("sampleBlob.txt").getBlockBlobClient();
    String sampleData = "Sample data for blob";
    try (ByteArrayInputStream dataStream = new ByteArrayInputStream(sampleData.getBytes())) {
        blockBlobClient.upload(dataStream, sampleData.length());
    } catch (IOException ex) {
        ex.printStackTrace();
    }
}

Отправка блочного BLOB-объекта из объекта BinaryData

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

public void uploadDataToBlob(BlobContainerClient blobContainerClient) {
    // Create a BlobClient object from BlobContainerClient
    BlobClient blobClient = blobContainerClient.getBlobClient("sampleBlob.txt");
    String sampleData = "Sample data for blob";
    blobClient.upload(BinaryData.fromString(sampleData));
}

Отправка блочного BLOB-объекта с параметрами конфигурации

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

Указание параметров передачи данных при отправке

Значения в ParallelTransferOptions можно настроить для повышения производительности операций передачи данных. Следующие значения можно настроить для отправки в зависимости от потребностей приложения:

• blockSize: максимальный размер блока для передачи каждого запроса. Это значение можно задать с помощью метода setBlockSizeLong .
• maxSingleUploadSize: если размер данных меньше или равен этому значению, он передается в один раз, а не разбивается на блоки. Если данные загружаются единовременно, размер блока игнорируется. Это значение можно задать с помощью метода setMaxSingleUploadSizeLong .
• maxConcurrency: максимальное число параллельных запросов, выданных в любое время в рамках одной параллельной передачи. Это значение можно задать с помощью метода setMaxConcurrency .

Убедитесь, что у вас есть следующая директива import, чтобы использовать ParallelTransferOptions для загрузки:

import com.azure.storage.blob.models.*;

В следующем примере кода показано, как задать значения для ParallelTransferOptions и включить параметры в составе экземпляра BlobUploadFromFileOptions . Значения, указанные в этом примере, не предназначены для рекомендации. Чтобы правильно настроить эти значения, необходимо учитывать конкретные потребности приложения.

public void uploadBlockBlobWithTransferOptions(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
            .setBlockSizeLong((long) (4 * 1024 * 1024)) // 4 MiB block size
            .setMaxConcurrency(2)
            .setMaxSingleUploadSizeLong((long) 8 * 1024 * 1024); // 8 MiB max size for single request upload

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString());
    options.setParallelTransferOptions(parallelTransferOptions);

    try {
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, null, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

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

Отправка блочного BLOB-объекта с тегами индекса

Теги индекса Blob категоризируют данные в вашей учетной записи хранения с помощью атрибутов тегов "ключ-значение". Эти теги автоматически индексируются и представляются в виде многомерного индекса с поддержкой поиска для упрощения нахождения данных.

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

public void uploadBlockBlobWithIndexTags(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    Map<String, String> tags = new HashMap<String, String>();
    tags.put("Content", "image");
    tags.put("Date", "2022-01-01");

    Duration timeout = Duration.ofSeconds(10);

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString());
    options.setTags(tags);

    try {
        // Create a new block blob, or update the content of an existing blob
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, timeout, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

Установка уровня доступа объекта BLOB при загрузке

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

public void uploadBlobWithAccessTier(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString())
            .setTier(AccessTier.COOL);

    try {
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, null, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

Установка уровня доступа разрешена только для блочных блобов. Вы можете установить уровень доступа для блочного blob на Hot, Cool, Cold или Archive. Чтобы задать уровень Coldдоступа, необходимо использовать минимальную версию клиентской библиотеки 12.21.0.

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

Загрузить блочный BLOB путем поэтапной загрузки и фиксации блоков

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

public void uploadBlocks(BlobContainerClient blobContainerClient, Path filePath, int blockSize) throws IOException {
    String fileName = filePath.getFileName().toString();
    BlockBlobClient blobClient = blobContainerClient.getBlobClient(fileName).getBlockBlobClient();

    FileInputStream fileStream = new FileInputStream(filePath.toString());
    List<String> blockIDArrayList = new ArrayList<>();
    byte[] buffer = new byte[blockSize];
    int bytesRead;

    while ((bytesRead = fileStream.read(buffer, 0, blockSize)) != -1) {

        try (ByteArrayInputStream stream = new ByteArrayInputStream(buffer)) {
            String blockID = Base64.getEncoder().encodeToString(UUID.randomUUID().toString().getBytes(StandardCharsets.UTF_8));

            blockIDArrayList.add(blockID);
            blobClient.stageBlock(blockID, stream, buffer.length);
        }
    }

    blobClient.commitBlockList(blockIDArrayList);

    fileStream.close();
}

Ресурсы

Чтобы узнать больше о загрузке BLOB-объектов с использованием клиентской библиотеки Azure Blob Storage для Java, ознакомьтесь со следующими ресурсами.

Примеры кода

• Просмотр примеров кода из этой статьи (GitHub)

Операции REST API

Пакет SDK Azure для Java содержит библиотеки, которые создаются на основе REST API Azure, что позволяет взаимодействовать с операциями REST API через знакомые парадигмы Java. Методы клиентской библиотеки для отправки больших двоичных объектов используют следующие операции REST API:

• Размещение большого двоичного объекта (REST API)
• Put Block (REST API - интерфейс прикладного программирования REST)

Ресурсы клиентской библиотеки

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

См. также

• Управление данными больших двоичных объектов Azure и их поиск с помощью тегов индекса больших двоичных объектов
• Использование тегов индекса BLOB-объектов для управления и поиска данных на Хранилище BLOB-объектов Azure

Связанный контент

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