Carregar um blob de bloco com Java

  • Artigo

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

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 arquivo no editor de pom.xml 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), você precisa da função interna do RBAC do Azure RBAC 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 BlobServiceClientBuilder para criar um BlobServiceClient objeto usando DefaultAzureCredentialo , 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 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:

Para carregar um blob de bloco 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 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.

Amostras de código

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:

Recursos da biblioteca do cliente

Consulte também

Conteúdos relacionados

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