Carregar um blob de bloco com Java

Artigo
10/18/2023

Este artigo mostra como carregar um blob de bloco usando a biblioteca de cliente do Armazenamento do Azure para Java. Você pode carregar dados para um blob de bloco a partir de um caminho de arquivo, um fluxo, um objeto binário ou uma cadeia de caracteres de texto. Você também pode carregar blobs com tags de índice.

Pré-requisitos

Este artigo pressupõe que você já tenha um projeto configurado para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para Java. Para saber mais sobre como configurar seu projeto, incluindo a instalação de pacotes, adicionar import diretivas e criar um objeto de cliente autorizado, consulte Introdução ao Armazenamento do Azure e Java.
O mecanismo de autorização deve ter permissões para executar uma operação de carregamento. Para saber mais, consulte as diretrizes de autorização para as seguintes operações de API REST:
- Colocar Blob
- Colocar Bloco

Carregar dados para um blob de bloco

Para carregar um blob de bloco de um fluxo ou um objeto binário, use o seguinte método:

upload

Para carregar um blob de bloco de um caminho de arquivo, use o seguinte método:

uploadFromFile

Cada um desses métodos pode ser chamado usando um objeto BlobClient ou um objeto BlockBlobClient .

Carregar um blob de bloco a partir de um caminho de arquivo local

O exemplo a seguir carrega um arquivo para um blob de bloco usando um BlobClient objeto:

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

Carregar um blob de bloco a partir de um fluxo

O exemplo a seguir carrega um blob de bloco criando um ByteArrayInputStream objeto e, em seguida, carregando esse objeto de fluxo:

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

Carregar um blob de bloco de um objeto BinaryData

O exemplo a BinaryData seguir carrega para um blob de bloco usando um BlobClient objeto:

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

Carregar um blob de bloco com opções de configuração

Você pode definir opções de configuração da biblioteca do cliente ao carregar um blob. Essas opções podem ser ajustadas para melhorar o desempenho, aumentar a confiabilidade e otimizar os custos. Os exemplos de código a seguir mostram como usar BlobUploadFromFileOptions para definir opções de configuração ao chamar um método de upload. Se você não estiver carregando de um arquivo, poderá definir opções semelhantes usando BlobParallelUploadOptions em um método de upload.

Especificar opções de transferência de dados ao carregar

Você pode configurar valores em ParallelTransferOptions para melhorar o desempenho das operações de transferência de dados. Os seguintes valores podem ser ajustados para carregamentos com base nas necessidades do seu aplicativo:

blockSize: O tamanho máximo do bloco a ser transferido para cada solicitação. Você pode definir esse valor usando o método setBlockSizeLong .
maxSingleUploadSize: Se o tamanho dos dados for menor ou igual a esse valor, eles serão carregados em uma única colocação, em vez de divididos em partes. Se os dados forem carregados em uma única captura, o tamanho do bloco será ignorado. Você pode definir esse valor usando o método setMaxSingleUploadSizeLong .
maxConcurrency: O número máximo de pedidos paralelos emitidos num determinado momento como parte de uma única transferência paralela. Você pode definir esse valor usando o método setMaxConcurrency .

Certifique-se de que tem a seguinte import diretiva para utilizar ParallelTransferOptions num carregamento:

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

O exemplo de código a seguir mostra como definir valores para ParallelTransferOptions e incluir as opções como parte de uma instância BlobUploadFromFileOptions . Os valores fornecidos neste exemplo não pretendem ser uma recomendação. Para ajustar corretamente esses valores, você precisa considerar as necessidades específicas do seu aplicativo.

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

Para saber mais sobre como ajustar as opções de transferência de dados, consulte Ajuste de desempenho para uploads e downloads com Java.

Carregar um blob de bloco com tags de índice

As tags de índice de Blob categorizam os dados em sua conta de armazenamento usando atributos de tag chave-valor. Essas tags são automaticamente indexadas e expostas como um índice multidimensional pesquisável para encontrar dados facilmente.

O exemplo a seguir carrega um blob de bloco com tags de índice definidas usando 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());
    }
}

Definir a camada de acesso de um blob ao carregar

Você pode definir a camada de acesso de um blob no upload usando a classe BlobUploadFromFileOptions . O exemplo de código a seguir mostra como definir a camada de acesso ao carregar um blob:

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

A definição da camada de acesso só é permitida para blobs de bloco. Você pode definir a camada de acesso para um blob de bloco como Hot, Cool, Coldou Archive. Para definir a camada de acesso como Cold, você deve usar uma versão mínima da biblioteca de cliente de 12.21.0.

Para saber mais sobre as camadas de acesso, consulte Visão geral das camadas de acesso.

Carregue um blob de bloco preparando blocos e confirmando

Você pode ter maior controle sobre como dividir os uploads em blocos preparando manualmente blocos individuais de dados. Quando todos os blocos que compõem um blob são preparados, você pode confirmá-los no Armazenamento de Blobs. Você pode usar essa abordagem para melhorar o desempenho carregando blocos em paralelo.

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

Recursos

Para saber mais sobre como carregar blobs usando a biblioteca de cliente do Armazenamento de Blobs do Azure para Java, consulte os recursos a seguir.

Operações da API REST

O SDK do Azure para Java contém bibliotecas que se baseiam na API REST do Azure, permitindo que você interaja com operações da API REST por meio de paradigmas Java familiares. Os métodos da biblioteca de cliente para carregar blobs usam as seguintes operações de API REST:

Partilhar via