Partager via

Charger un objet blob de blocs avec Java

  • Article

Cet article explique comment charger un blob de blocs avec la bibliothèque de client du Stockage Azure pour Java. Vous pouvez charger des données dans un objet blob de blocs depuis un chemin d’accès de fichier, un flux, un objet binaire ou une chaîne de texte. Vous pouvez aussi charger des objets blob avec des balises d’index.

Prérequis

Paramétrer votre environnement

Si vous n’avez pas de projet existant, cette section vous montre comment configurer un projet pour qu’il fonctionne avec la bibliothèque de client Stockage Blob Azure pour Java. Pour plus d’informations, consultez Bien démarrer avec Stockage Blob Azure et Java.

Pour utiliser les exemples de code de cet article, effectuez les étapes suivantes pour configurer votre projet.

Remarque

Cet article utilise l’outil de génération Maven pour générer et exécuter l’exemple de code. D’autres outils de génération, comme Gradle, fonctionnent également avec le Kit de développement logiciel (SDK) Azure pour Java.

Installer des packages

Ouvrez le fichier pom.xml dans votre éditeur de texte. Installez les packages en incluant le fichier de marque d’ordre d’octet ou en incluant une dépendance directe.

Ajouter des instructions import

Ajoutez les instructions import suivantes :

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.*;

Autorisation

Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour charger un objet blob. Pour l’autorisation avec Microsoft Entra ID (recommandé), vous devez disposer au minimum du rôle RBAC Azure intégré Contributeur aux données Blob du stockage. Si vous souhaitez en savoir plus, consulter l’aide sur l’autorisation pour les opérations Put Blob (API REST) et Put Block (API REST).

Créer un objet client

Pour connecter une application au Stockage Blob, créez une instance de BlobServiceClient.

L’exemple suivant utilise BlobServiceClientBuilder pour générer un objet BlobServiceClient en utilisant DefaultAzureCredential, et montre comment créer si nécessaire des clients de conteneur et de blob :

// 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>");

Pour en savoir plus sur la création et la gestion d’objets clients, consultez Créer et gérer des objets clients qui interagissent avec des ressources de données.

Charger des données dans un blob de blocs

Pour charger un objet blob de blocs depuis un flux ou un objet binaire, utilisez la méthode suivante :

Pour charger un objet blob de blocs depuis un chemin d’accès, utilisez la méthode suivante :

Chacune de ces méthodes peut être appelée en utilisant un objet BlobClient ou un objet BlockBlobClient.

Charger un blob de blocs à partir d’un chemin de fichier local

L’exemple suivant charge un fichier dans un objet blob de blocs à l’aide d’un objet 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());
    }
}

Charger un blob de blocs à partir d’un flux

L’exemple suivant charge un objet blob de blocs en créant un objet ByteArrayInputStream, puis en chargeant cet objet de flux :

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

Charger un objet blob de blocs depuis un objet BinaryData

L’exemple suivant charge BinaryData dans un objet blob de blocs en utilisant un objet 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));
}

Charger un objet blob de blocs avec des options de configuration

Vous pouvez définir des options de configuration de bibliothèque de client lors du chargement d’un objet blob. Ces options peuvent être paramétrées pour améliorer les performances, améliorer la fiabilité et optimiser les coûts. Les exemples de code suivants montrent comment utiliser BlobUploadFromFileOptions pour définir des options de configuration lors de l’appel d’une méthode de chargement. Si vous n’effectuez pas de chargement à partir d’un fichier, vous pouvez définir des options similaires à l’aide de BlobParallelUploadOptions sur une méthode de chargement.

Spécifier les options de transfert de données lors du chargement

Vous pouvez configurer des valeurs dans ParallelTransferOptions pour améliorer le niveau de performance des opérations de transfert de données. Les valeurs suivantes peuvent être ajustées pour les chargements en fonction des besoins de votre application :

  • blockSize : taille de bloc maximale à transférer pour chaque requête. Vous pouvez définir cette valeur à l’aide de la méthode setBlockSizeLong.
  • maxSingleUploadSize : si la taille des données est inférieure ou égale à cette valeur, elles sont chargées en un seul PUT, au lieu de les diviser en blocs. Si les données sont chargées en une seule capture, la taille du bloc est ignorée. Vous pouvez définir cette valeur à l’aide de la méthode setMaxSingleUploadSizeLong.
  • maxConcurrency : nombre maximal de requêtes parallèles émises à un moment donné dans le cadre d’un transfert parallèle unique. Vous pouvez définir cette valeur à l’aide de la méthode setMaxConcurrency.

Vérifiez que vous disposez de la directive import suivante afin d’utiliser ParallelTransferOptions pour un chargement :

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

L’exemple de code suivant montre comment définir des valeurs pour ParallelTransferOptions et inclure les options dans le cadre d’une instance BlobUploadFromFileOptions. Les valeurs fournies dans cet exemple ne sont pas destinées à être une recommandation. Pour régler correctement ces valeurs, vous devez tenir compte des besoins spécifiques de votre application.

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

Pour en savoir plus sur le réglage des options de transfert de données, consultez Réglage des performances pour les chargements et les téléchargements avec Java.

Charger un blob de blocs avec des balises d’index

Les balises d’index de blob catégorisent les données de votre compte de stockage à l’aide d’attributs de balise clé-valeur. Ces balises sont automatiquement indexées et exposées en tant qu’index multidimensionnel pouvant faire l’objet d’une recherche pour trouver facilement des données.

L’exemple suivant charge un objet blob de blocs avec des balises d’index définies en utilisant 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());
    }
}

Définir le niveau d’accès d’un objet blob pendant le chargement

Vous pouvez définir le niveau d’accès d’un objet blob lors du chargement en utilisant la classe BlobUploadFromFileOptions. L’exemple de code suivant montre comment définir le niveau d’accès lors du chargement d’un objet 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());
    }
}

La définition du niveau d’accès est autorisée seulement sur les objets blob de blocs. Vous pouvez définir le niveau d’accès d’un objet blob de blocs sur Hot, Cool, Coldou Archive. Pour définir le niveau d’accès sur Cold, vous devez utiliser une version minimale de la bibliothèque cliente de la version 12.21.0.

Pour en savoir plus sur les niveaux d’accès, consultez Vue générale des niveaux d’accès .

Charger un objet blob de blocs en mettant en lots des blocs et en validant

Vous pouvez avoir un meilleur contrôle sur la répartition des chargements dans des blocs en indexant manuellement des blocs de données individuels. Quand tous les blocs qui composent un blob sont indexés, vous pouvez les valider dans le Stockage Blob. Vous pouvez utiliser cette approche pour améliorer les performances en chargeant des blocs en parallèle.

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

Ressources

Pour en savoir plus sur le chargement d’objets blob à l’aide de la bibliothèque de client Stockage Blob Azure pour Java, consultez les ressources suivantes.

Exemples de code

Opérations de l'API REST

Le Kit de développement logiciel (SDK) Azure pour Java contient des bibliothèques qui s'appuient sur l'API REST Azure, vous permettant d’interagir avec les opérations de l’API REST par le biais de paradigmes Java familiers. Les méthodes de bibliothèque de client pour le chargement d’objets blob utilisent les opérations d’API REST suivantes :

Ressources de bibliothèque cliente

Voir aussi

Contenu connexe

  • Cet article fait partie du guide pour les développeurs Stockage Blob pour Java. Pour découvrir plus d’informations, consultez la liste complète des articles du guide du développeur dans Générer votre application Java.