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

  • En este artículo se supone que ya tiene un proyecto configurado para trabajar con la biblioteca cliente de Azure Blob Storage para Java. Para obtener información sobre cómo configurar el proyecto, incluida la instalación de paquetes, la adición de directivas de import y la autorización de un objeto de cliente, consulte Introducción a Azure Storage y Java.
  • El mecanismo de autorización debe tener permisos para realizar una operación de carga. Para obtener más información, consulte la guía de autorización para las siguientes operaciones de la API de REST:

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.

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:

Ejemplos de código

Recursos de la biblioteca cliente

Consulte también