Upload a block blob with Java

Статья
2025-04-12

This article shows how to upload a block blob using the Azure Storage client library for Java. You can upload data to a block blob from a file path, a stream, a binary object, or a text string. You can also upload blobs with index tags.

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

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

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

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

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

Примечание.

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

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

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

Add import statements

Add the following import statements:

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.*;

Авторизация

The authorization mechanism must have the necessary permissions to upload a blob. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role Storage Blob Data Contributor or higher. Дополнительные сведения см. в руководстве по авторизации для 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>");

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

Upload data to a block blob

To upload a block blob from a stream or a binary object, use the following method:

отправить

To upload a block blob from a file path, use the following method:

uploadFromFile

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

Примечание.

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

Upload a block blob from a local file path

В следующем примере файл загружается в блоковый блоб с помощью объекта 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());
    }
}

Upload a block blob from a stream

The following example uploads a block blob by creating a ByteArrayInputStream object, then uploading that stream object:

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();
    }
}

Upload a block blob from a BinaryData object

The following example uploads BinaryData to a block blob using a BlobClient object:

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

Upload a block blob with configuration options

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

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

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

blockSize: максимальный размер блока для передачи каждого запроса. Это значение можно задать с помощью метода setBlockSizeLong .
maxSingleUploadSize: если размер данных меньше или равен этому значению, он передается в один раз, а не разбивается на блоки. If the data is uploaded in a single shot, the block size is ignored. Это значение можно задать с помощью метода 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.

Upload a block blob with index tags

Blob index tags categorize data in your storage account using key-value tag attributes. Эти теги автоматически индексируются и представляются в виде многомерного индекса с поддержкой поиска для упрощения нахождения данных.

The following example uploads a block blob with index tags set using 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());
    }
}

Set a blob's access tier on upload

Уровень доступа блоба можно задать при загрузке с помощью класса 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());
    }
}

Setting the access tier is only allowed for block blobs. You can set the access tier for a block blob to Hot, Cool, Cold, or Archive. Чтобы задать уровень Coldдоступа, необходимо использовать минимальную версию клиентской библиотеки 12.21.0.

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

Upload a block blob by staging blocks and committing

Вы можете иметь больший контроль над тем, как разделять загрузки на блоки, вручную обрабатывая отдельные блоки данных. When all of the blocks that make up a blob are staged, you can commit them to Blob Storage. Этот подход можно использовать для повышения производительности, отправляя блоки параллельно.

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:

Put Blob (REST API)
Put Block (REST API)

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

См. также

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