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

Статья
10/18/2023

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

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

В этой статье предполагается, что у вас уже есть проект, настроенный для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для Java. Сведения о настройке проекта, включая установку пакетов, добавление import директив и создание авторизованного клиентского объекта, см. в статье "Начало работы с служба хранилища Azure и Java".
Механизм авторизации должен иметь разрешения для выполнения операции отправки. Дополнительные сведения см. в руководстве по авторизации для следующих операций REST API:
- вставка большого двоичного объекта;
- Put Block

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

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

отправить

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

uploadFromFile

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

Отправка блочного 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-объекта из потока

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

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

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-объект с тегами индекса, заданными с помощью 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());
    }
}

Настройка уровня доступа большого двоичного объекта при отправке

Уровень доступа большого двоичного объекта можно задать при отправке с помощью класса 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можно задать для , Coldили CoolArchive. Чтобы задать уровень 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 для Java см. в следующих ресурсах.

Операции REST API

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