Carga de un blob en bloques con Java

  • Artículo

En este artículo se muestra cómo cargar un blob en bloques con la biblioteca cliente de Azure Storage para Java. Puede cargar datos en un blob en bloques desde una ruta de acceso de archivo, una secuencia, un objeto binario o una cadena de texto. También puede cargar blobs con etiquetas de índice.

Requisitos previos

Configurar el entorno

Si no tiene un proyecto existente, en esta sección, se muestra cómo configurar un proyecto para que funcione con la biblioteca cliente de Azure Blob Storage para Java. Para más información, consulte Introducción a Azure Blob Storage y Java.

Para trabajar con los ejemplos de código de este artículo, siga los pasos siguientes a fin de configurar el proyecto.

Nota:

En este artículo, se usa la herramienta de compilación de Maven para compilar y ejecutar el código de ejemplo. Otras herramientas de compilación, como Gradle, también funcionan con Azure SDK para Java.

Instalar paquetes

Abra el archivo pom.xml en el editor de texto. Instale los paquetes mediante la inclusión del archivo BOM o la inclusión de una dependencia directa.

Adición de instrucciones import

Agregue las instrucciones siguientes 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.*;

Authorization

El mecanismo de autorización debe tener los permisos necesarios para actualizar un blob. Para la autorización con Microsoft Entra ID (recomendado) se necesita el rol integrado de RBAC de Azure de Colaborador de datos de Storage Blob o superior. Para más información, consulte la guía de autorización para Put Blob (API REST) y Put Block (API REST).

Creación de un objeto de cliente

Para conectar una aplicación a Blob Storage, cree una instancia de BlobServiceClient.

En el ejemplo siguiente, se usa BlobServiceClientBuilder para crear un objeto BlobServiceClient mediante DefaultAzureCredential, y se muestra cómo crear clientes de contenedores y blobs, si es necesario:

// 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 obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Carga de datos en un blob en bloques

Para cargar un blob en bloques desde una secuencia o un objeto binario, use el método siguiente:

Para cargar un blob en bloques desde una ruta de acceso de archivo, use el método siguiente:

Se puede llamar a cada uno de estos métodos mediante un objeto BlobClient o un objeto BlockBlobClient.

Carga de un blob en bloques desde una ruta de acceso de archivo local

En el ejemplo siguiente se carga un archivo a un blob en bloques mediante un 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());
    }
}

Carga de un blob en bloques desde una secuencia

En el ejemplo siguiente se carga un blob en bloques mediante la creación de un objeto ByteArrayInputStream y, a continuación, se carga ese objeto de secuencia:

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

Cargar un blob en bloques desde un objeto BinaryData

En el ejemplo siguiente se carga BinaryData en un blob en bloques mediante un 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));
}

Carga de un blob en bloques con opciones de configuración

Puede definir las opciones de configuración de la biblioteca cliente al cargar un blob. Estas opciones se pueden ajustar para mejorar el rendimiento, mejorar la confiabilidad y optimizar los costes. En los ejemplos de código siguientes se muestra cómo usar BlobUploadFromFileOptions para definir opciones de configuración al llamar a un método de carga. Si no carga desde un archivo, podrá establecer opciones similares mediante BlobParallelUploadOptions en un método de carga.

Especificación de opciones de transferencia de datos al cargar

Puede configurar valores en ParallelTransferOptions para mejorar el rendimiento de las operaciones de transferencia de datos. Los siguientes valores se pueden ajustar para cargas según las necesidades de su aplicación:

  • blockSize: el tamaño máximo de bloque a transferir para cada solicitud. Puede establecer este valor utilizando el método setBlockSizeLong.
  • maxSingleUploadSize: si el tamaño de los datos fuera menor o igual que este valor, se cargará en una sola colocación en lugar de dividirse en fragmentos. Si los datos se cargasen en una sola captura, se omitirá el tamaño del bloque. Puede establecer este valor utilizando el método setMaxSingleUploadSizeLong.
  • maxConcurrency: el número máximo de solicitudes paralelas emitidas en un momento dado como parte de una única transferencia paralela. Puede establecer este valor utilizando el método setMaxConcurrency.

Asegúrese de tener la siguiente directiva import para usar ParallelTransferOptions para una carga:

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

En el ejemplo de código siguiente, se muestra cómo establecer valores para ParallelTransferOptions e incluir las opciones como parte de una instancia de BlobUploadFromFileOptions. Los valores proporcionados en este ejemplo no están diseñados para ser una recomendación. Para ajustar correctamente estos valores, debe tener en cuenta las necesidades específicas de la aplicación.

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 más información sobre cómo ajustar las opciones de transferencia de datos, consulte Ajuste del rendimiento para cargas y descargas con Java.

Carga de un blob en bloques con etiquetas de índice

Las etiquetas de índice de blobs clasifican los datos de la cuenta de almacenamiento mediante atributos de etiqueta clave-valor. Estas etiquetas se indexan y se exponen automáticamente como un índice multidimensional que se puede buscar para encontrar fácilmente los datos.

En el ejemplo siguiente, se carga un blob en bloques con etiquetas de índice establecidas mediante 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());
    }
}

Establecimiento del nivel de acceso de un blob durante la carga

Puede establecer el nivel de acceso de un blob en la carga mediante la clase BlobUploadFromFileOptions. En el ejemplo de código siguiente se muestra cómo establecer el nivel de acceso al cargar un 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());
    }
}

Solo se permite establecer el nivel de acceso en los blobs en bloques. Puede establecer el nivel de acceso de un blob en bloques en Hot, Cool, Cold o Archive. Para establecer el nivel de acceso en Cold, debe usar la versión mínima de la biblioteca cliente 12.21.0.

Si desea obtener más información sobre los niveles de acceso, consulte Información general sobre los niveles de acceso.

Cargar un blob en bloques mediante la preparación de bloques y la confirmación

Puede tener un mayor control sobre cómo dividir las cargas en bloques si pone en escena manualmente bloques individuales de datos. Cuando todos los bloques que son un blob se han almacenado de manera provisional, puede confirmarlos en Blob Storage. Puede usar este método para mejorar el rendimiento cargando bloques en 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 más información sobre cómo cargar listas de blobs con la biblioteca cliente de Azure Blob Storage para Java, consulte los recursos siguientes.

Ejemplos de código

Operaciones de API REST

El SDK de Azure para Java contiene bibliotecas que se crean a partir de la API REST de Azure, lo que le permite interactuar con las operaciones de API REST a través de paradigmas conocidos de Java. Los métodos de la biblioteca cliente para cargar blobs usan las siguientes operaciones de API REST:

Recursos de la biblioteca cliente

Consulte también

Contenido relacionado

  • Este artículo forma parte de la guía para desarrolladores de Blob Storage para Java. Para más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación Java.