Carregar um blob de bloco usando Java

Este artigo mostra como carregar um blob de bloco usando a biblioteca de cliente do Armazenamento 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

Subscrição do Azure - crie uma gratuitamente
Conta de armazenamento do Azure - criar uma conta de armazenamento
Java Development Kit (JDK) versão 8 ou posterior (recomendamos a versão 17 para a melhor experiência)
O Apache Maven é usado para gerenciamento de projetos neste exemplo

Configurar o ambiente

Se você não tiver um projeto existente, esta seção mostra como configurar um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para Java. Para obter mais informações, consulte Introdução ao Armazenamento de Blobs do Azure e Java.

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

Nota

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

Instalar pacotes

Abra o ficheiro 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 instruções 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 deve ter as permissões necessárias para carregar um blob. Para autorização com o Microsoft Entra ID (recomendado), necessita da função incorporada do RBAC do Azure Storage Blob Data Contributor ou superior. 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 Blob, crie uma instância de BlobServiceClient.

O exemplo a seguir usa o BlobServiceClientBuilder para construir um objeto BlobServiceClient utilizando DefaultAzureCredential, e mostra como criar clientes de contentor e de 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 de cliente, consulte Criar e gerenciar objetos de cliente que interagem com recursos de dados.

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:

carregarDoFicheiro

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

Nota

As bibliotecas de cliente do Armazenamento do Azure não oferecem suporte a gravações simultâneas no mesmo blob. Se seu aplicativo exigir vários processos gravando no mesmo blob, você deverá implementar uma estratégia de controle de simultaneidade para fornecer uma experiência previsível. Para saber mais sobre estratégias de simultaneidade, consulte Gerenciar simultaneidade no Blob Storage.

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 bloco blob criando um objeto ByteArrayInputStream e depois 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 a partir de um objeto de dados binários

O exemplo a seguir carrega BinaryData para um blob de bloco 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 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 não estiveres a carregar de um ficheiro, podes definir opções semelhantes usando BlobParallelUploadOptions num método de carregamento.

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 do tipo 'block' com tags de índice

As tags de índice do Blob categorizam os dados na 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 faz upload de um blob de bloco definindo tags de índice 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.

Suba um blob de bloco agendando blocos e guardando

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 estão preparados, pode-se comprometê-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.

Amostras de código

Exibir exemplos de código deste artigo (GitHub)

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:

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

Recursos da biblioteca do cliente

Consulte também

Este artigo faz parte do guia para desenvolvedores do Armazenamento de Blobs para Java. Para saber mais, consulte a lista completa de artigos do guia do desenvolvedor em Build your Java app.

Comentários

Esta página foi útil?

Last updated on 2025-04-01