Caricare un BLOB in blocchi con Java

  • Articolo

Questo articolo illustra come caricare un BLOB in blocchi usando la libreria client Archiviazione di Azure per Java. È possibile caricare dati in un BLOB in blocchi da un percorso di file, un flusso, un oggetto binario o una stringa di testo. È anche possibile caricare BLOB con tag di indice.

Prerequisiti

  • Questo articolo presuppone che sia già stato configurato un progetto per l'uso con la libreria client Archiviazione BLOB di Azure per Java. Per informazioni sulla configurazione del progetto, tra cui l'installazione del pacchetto, l'aggiunta import di direttive e la creazione di un oggetto client autorizzato, vedere Introduzione a Archiviazione di Azure e Java.
  • Il meccanismo di autorizzazione deve disporre delle autorizzazioni per eseguire un'operazione di caricamento. Per altre informazioni, vedere le linee guida per l'autorizzazione per le operazioni API REST seguenti:

Caricare dati in un BLOB in blocchi

Per caricare un BLOB in blocchi da un flusso o da un oggetto binario, usare il metodo seguente:

Per caricare un BLOB in blocchi da un percorso di file, usare il metodo seguente:

Ognuno di questi metodi può essere chiamato usando un oggetto BlobClient o un oggetto BlockBlobClient .

Caricare un BLOB in blocchi da un percorso di file locale

L'esempio seguente carica un file in un BLOB in blocchi usando un BlobClient oggetto :

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

Caricare un BLOB in blocchi da un flusso

L'esempio seguente carica un BLOB in blocchi creando un ByteArrayInputStream oggetto e caricando l'oggetto flusso:

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

Caricare un BLOB in blocchi da un oggetto BinaryData

L'esempio seguente carica in BinaryData un BLOB in blocchi usando un BlobClient oggetto :

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

Caricare un BLOB in blocchi con opzioni di configurazione

È possibile definire le opzioni di configurazione della libreria client durante il caricamento di un BLOB. Queste opzioni possono essere ottimizzate per migliorare le prestazioni, migliorare l'affidabilità e ottimizzare i costi. Gli esempi di codice seguenti illustrano come usare BlobUploadFromFileOptions per definire le opzioni di configurazione quando si chiama un metodo di caricamento. Se non si esegue il caricamento da un file, è possibile impostare opzioni simili usando BlobParallelUploadOptions in un metodo di caricamento.

Specificare le opzioni di trasferimento dei dati al caricamento

È possibile configurare i valori in ParallelTransferOptions per migliorare le prestazioni per le operazioni di trasferimento dei dati. I valori seguenti possono essere ottimizzati per i caricamenti in base alle esigenze dell'app:

  • blockSize: dimensione massima del blocco da trasferire per ogni richiesta. È possibile impostare questo valore usando il metodo setBlockSizeLong .
  • maxSingleUploadSize: se le dimensioni dei dati sono minori o uguali a questo valore, vengono caricate in un'unica partizione anziché suddivise in blocchi. Se i dati vengono caricati in un singolo colpo, la dimensione del blocco viene ignorata. È possibile impostare questo valore usando il metodo setMaxSingleUploadSizeLong .
  • maxConcurrency: numero massimo di richieste parallele inviate in qualsiasi momento come parte di un singolo trasferimento parallelo. È possibile impostare questo valore usando il metodo setMaxConcurrency .

Assicurarsi di disporre della direttiva seguente import da usare ParallelTransferOptions per un caricamento:

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

Nell'esempio di codice seguente viene illustrato come impostare i valori per ParallelTransferOptions e includere le opzioni come parte di un'istanza blobUploadFromFileOptions . I valori forniti in questo esempio non devono essere consigliati. Per ottimizzare correttamente questi valori, è necessario considerare le esigenze specifiche dell'app.

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

Per altre informazioni sull'ottimizzazione delle opzioni di trasferimento dei dati, vedere Ottimizzazione delle prestazioni per caricamenti e download con Java.

Caricare un BLOB in blocchi con tag di indice

I tag di indice BLOB classificano i dati nell'account di archiviazione usando gli attributi dei tag chiave-valore. Questi tag vengono indicizzati e esposti automaticamente come indice multidimensionale ricercabile per trovare facilmente i dati.

L'esempio seguente carica un BLOB in blocchi con tag di indice impostati 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());
    }
}

Impostare il livello di accesso di un BLOB al caricamento

È possibile impostare il livello di accesso di un BLOB al caricamento usando la classe BlobUploadFromFileOptions . L'esempio di codice seguente illustra come impostare il livello di accesso durante il caricamento di 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());
    }
}

L'impostazione del livello di accesso è consentita solo per i BLOB in blocchi. È possibile impostare il livello di accesso per un BLOB in blocchi su Hot, Cool, Coldo Archive. Per impostare il livello di accesso su Cold, è necessario usare una versione minima della libreria client 12.21.0.

Per altre informazioni sui livelli di accesso, vedere Panoramica dei livelli di accesso.

Caricare un BLOB in blocchi tramite blocchi di staging e commit

È possibile avere un maggiore controllo su come dividere i caricamenti in blocchi eseguendo manualmente lo staging di singoli blocchi di dati. Quando tutti i blocchi che costituiscono un BLOB vengono gestiti in staging, è possibile eseguirne il commit nell'Archiviazione BLOB. È possibile usare questo approccio per migliorare le prestazioni caricando blocchi in parallelo.

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

Risorse

Per altre informazioni sul caricamento di BLOB usando la libreria client Archiviazione BLOB di Azure per Java, vedere le risorse seguenti.

Operazioni dell'API REST

Azure SDK per Java contiene librerie basate sull'API REST di Azure, che consentono di interagire con le operazioni dell'API REST tramite paradigmi Java noti. I metodi della libreria client per il caricamento di BLOB usano le operazioni API REST seguenti:

Esempi di codice

Risorse della libreria client

Vedi anche