Compartilhar via

Carregar um blob de blocos com Java

  • Artigo

Este artigo mostra como carregar um blob de blocos usando a Biblioteca de clientes do Armazenamento do Microsoft Azure para Java. Você pode carregar dados em um blob de blocos 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 marcas de índice.

Pré-requisitos

Configure seu ambiente

Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para que ele funcione com a biblioteca de clientes do Armazenamento de Blobs do Azure para Java. Para obter mais informações, confira Introdução ao Armazenamento de Blobs do Azure e ao Java.

Para trabalhar com os exemplos de código neste artigo, siga estas etapas para configurar seu projeto.

Observação

Este artigo usa a ferramenta de build do Maven para compilar e executar o código de exemplo. Outras ferramentas de build, como o Gradle, também funcionam com o SDK do Azure para Java.

Instalar Pacotes

Abra o arquivo pom.xml no seu editor de texto. Instale os pacotes incluindo o arquivo BOM ou incluindo uma dependência direta.

Adicionar instruções de importação

Adicione as seguintes declarações de 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.*;

Autorização

O mecanismo de autorização precisa ter as permissões necessárias para carregar um blob. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna de Colaborador de Dados de Blob de Armazenamento ou superior do RBAC do Azure. Para saber mais, consulte as diretrizes de autorização para Put Blob (REST API) e Put Block (REST API).

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blobs, crie uma instância do BlobServiceClient.

O exemplo a seguir usa BlobServiceClientBuilder para criar um objeto BlobServiceClient usando DefaultAzureCredential e mostra como criar clientes de contêiner e blob, se necessário:

// 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>");

Para saber mais sobre como criar e gerenciar objetos clientes, confira Criar e gerenciar objetos clientes que interagem com recursos de dados.

Carregar dados em um blob de blocos

Para fazer o upload um blob de blocos a partir de um fluxo ou um objeto binário, use o seguinte método:

Para fazer o upload de um blob de blocos a partir de um caminho de arquivo, use o seguinte método:

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

Carregar um blob de blocos de um caminho de arquivo local

O seguinte exemplo carrega um arquivo em um blob de blocos usando um objeto 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());
    }
}

Carregar um blob de blocos de um fluxo

O seguinte exemplo faz o upload um blob de blocos criando um objeto ByteArrayInputStream e, em seguida, fazendo o upload 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();
    }
}

Fazer o upload de um blob de blocos a partir de um objeto BinaryData

O seguinte exemplo faz o upload de BinaryData em um blob de blocos usando um objeto 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));
}

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

Você pode definir opções de configuração da biblioteca de clientes ao carregar um blob. Essas opções podem ser ajustadas para melhorar o desempenho, melhorar 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 durante o upload

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

  • blockSize: o tamanho máximo do bloco a ser transferido para cada solicitação. Você pode definir este 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 entrada, em vez de divididos em partes. Se os dados forem carregados de uma só vez, o tamanho do bloco será ignorado. Você pode definir este valor usando o método setMaxSingleUploadSizeLong.
  • maxConcurrency: o número máximo de solicitações paralelas emitidas a qualquer momento como parte de uma única transferência paralela. Você pode definir este valor usando o método setMaxConcurrency.

Verifique se você tem a seguinte diretiva import para usar ParallelTransferOptions para um upload:

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 se destinam a ser uma recomendação. Para ajustar adequadamente 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, confira Ajuste de desempenho para uploads e downloads com Java.

Carregar um blob de blocos com marcas de índice

As marcas de índice de blob categorizam os dados na sua conta de armazenamento usando atributos de marca de chave-valor. Essas marcas são indexadas automaticamente e expostas como um índice multidimensional pesquisável para localizar dados com facilidade.

O seguinte exemplo faz o upload de um blob de blocos com marcas 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 durante o upload

Você pode definir a camada de acesso de um blob durante o 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 configuração da camada de acesso somente é permitida para blobs de blocos. Você pode definir a camada de acesso para um blob de blocos como Hot, Cool, Cold ou Archive. Para definir a camada de acesso como Cold, você deve usar uma versão mínima da biblioteca de clientes de 12.21.0.

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

Faça upload de um blob de blocos preparando os blocos e confirmando

Você pode ter maior controle sobre como dividir os uploads em blocos organizando manualmente os blocos individuais de dados. Quando todos os blocos que formam um blob estiverem preparados, você poderá fazer commit deles no Armazenamento de Blobs. Você pode usar essa abordagem para melhorar o desempenho fazendo upload de 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 clientes do Armazenamento de Blobs do Azure para Java, consulte os recursos a seguir.

Exemplos de código

Operações da API REST

O SDK do Azure para Java contém bibliotecas que criam sobre a API REST do Azure, permitindo a interação com as operações de API REST por meio de paradigmas conhecidos do Java. Os métodos da biblioteca de clientes para carregar blobs usam as seguintes operações da API REST:

Recursos da biblioteca de clientes

Confira também

Conteúdo relacionado

  • Este artigo faz parte do guia do desenvolvedor do Armazenamento de Blobs para Java. Para saber mais, veja a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo Java.