Bibliothèque cliente d’objets blob stockage Azure pour Java - version 12.24.1

  • Article

Le Stockage Blob Azure est la solution de stockage d’objets de Microsoft pour le cloud. Stockage Blob est optimisé pour stocker des quantités massives de données non structurées. Les données non structurées sont des données qui n’obéissent pas à un modèle ou une définition de données en particulier, comme des données texte ou binaires.

| Code sourceDocumentation de référence sur les | APIDocumentation | sur l’API REST | Documentation produitÉchantillons

Prise en main

Prérequis

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version ga de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
  </dependency>
</dependencies>

Inclure une dépendance directe

Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.24.1</version>
</dependency>

Créer un compte de stockage

Pour créer un compte de stockage, vous pouvez utiliser le portail Azure ou Azure CLI.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

L’URL de votre compte de stockage, identifiée par la suite comme <your-storage-account-url>, serait mise en forme comme suit : http(s)://<storage-account-name>.blob.core.windows.net

Authentifier le client

Pour interagir avec le service de stockage (Blob, File d’attente, Message, MessageId, Fichier), vous devez créer un instance de la classe Client de service. Pour ce faire, vous avez besoin de la chaîne SAS de compte (signature d’accès partagé) du compte de stockage. Pour plus d’informations , consultez Jeton SAS.

Récupérer les informations d’identification

Jeton SAP

a. Utilisez l’extrait de code Azure CLI ci-dessous pour obtenir le jeton SAS à partir du compte de stockage.

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

Exemple :

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. Vous pouvez également obtenir le jeton SAP du compte à partir du portail Azure.

  1. Accédez à votre compte de stockage
  2. Sélectionnez Shared access signature dans le menu de gauche
  3. Cliquez sur Generate SAS and connection string (après l’installation)
Informations d’identification de clé partagée

a. Utilisez Le nom du compte et la clé de compte. Nom du compte est le nom de votre compte de stockage.

  1. Accédez à votre compte de stockage
  2. Sélectionnez Access keys dans le menu de gauche
  3. Sous key1/key2 copier le contenu du Key champ

ou

b. Utilisez le chaîne de connexion.

  1. Accédez à votre compte de stockage
  2. Sélectionnez Access keys dans le menu de gauche
  3. Sous key1/key2 copier le contenu du Connection string champ

Concepts clés

Stockage Blob est conçu pour :

  • Mise à disposition d’images ou de documents directement dans un navigateur
  • Stockage de fichiers pour un accès distribué
  • Streaming de contenu vidéo et audio
  • Écriture dans des fichiers journaux
  • Stockage de données pour la sauvegarde et la restauration, la reprise d’activité après sinistre et l’archivage
  • Stockage des données pour l’analyse par un service local ou hébergé par Azure

Format d’URL

Les objets blob sont adressables au format d’URL suivant : L’URL suivante adresse un objet blob :

https://myaccount.blob.core.windows.net/mycontainer/myblob

Syntaxe d'URI de ressource

Pour le compte de stockage, l’URI de base pour les opérations d’objet blob inclut uniquement le nom du compte :

https://myaccount.blob.core.windows.net

Pour un conteneur, l'URI de base inclut le nom du compte et celui du conteneur :

https://myaccount.blob.core.windows.net/mycontainer

Pour un objet blob, l’URI de base inclut le nom du compte, le nom du conteneur et le nom de l’objet blob :

https://myaccount.blob.core.windows.net/mycontainer/myblob

Notez que les URI ci-dessus peuvent ne pas tenir pour les scénarios plus avancés, tels que les noms de domaine personnalisés.

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches d’objets blob de stockage Azure les plus courantes, notamment :

Créez une classe BlobServiceClient

Créez un en BlobServiceClient utilisant le sasToken généré ci-dessus.

BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

ou

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

Créez une classe BlobContainerClient

Créez un à BlobContainerClient l’aide d’un BlobServiceClient.

BlobContainerClient blobContainerClient = blobServiceClient.getBlobContainerClient("mycontainer");

Créez un BlobContainerClient à partir du générateur sasToken généré ci-dessus.

BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .containerName("mycontainer")
    .buildClient();

ou

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "mycontainer" + "?" + "<your-sasToken>")
    .buildClient();

Créez une classe BlobClient

Créez un à BlobClient l’aide d’un BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblob");

ou

Créez un BlobClient à partir du générateur sasToken généré ci-dessus.

BlobClient blobClient = new BlobClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .containerName("mycontainer")
    .blobName("myblob")
    .buildClient();

ou

// Only one "?" is needed here. If the SAS token starts with "?", please removing one "?".
BlobClient blobClient = new BlobClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "mycontainer" + "/" + "myblob" + "?" + "<your-sasToken>")
    .buildClient();

Créez un conteneur.

Créez un conteneur à l’aide d’un BlobServiceClient.

blobServiceClient.createBlobContainer("mycontainer");

ou

Créez un conteneur à l’aide d’un BlobContainerClient.

blobContainerClient.create();

Charger des données dans un objet blob

Charger BinaryData dans un objet blob à l’aide d’un BlobClient généré à partir d’un BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
String dataSample = "samples";
blobClient.upload(BinaryData.fromString(dataSample));

Charger un objet blob à partir d’un flux

Charger à partir d’un InputStream vers un objet blob à l’aide d’un BlockBlobClient généré à partir d’un BlobContainerClient.

BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("myblockblob").getBlockBlobClient();
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blockBlobClient.upload(dataStream, dataSample.length());
} catch (IOException e) {
    e.printStackTrace();
}

Charger un objet blob à partir du chemin d’accès local

Chargez un fichier dans un objet blob à l’aide d’un BlobClient généré à partir d’un BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
blobClient.uploadFromFile("local-file.jpg");

Charger un objet blob s’il n’en existe pas déjà un

Charger des données dans un objet blob et échouer s’il en existe déjà un.

/*
 * Rather than use an if block conditioned on an exists call, there are three ways to upload-if-not-exists using
 * one network call instead of two. Equivalent options are present on all upload methods.
 */
// 1. The minimal upload method defaults to no overwriting
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length());
} catch (IOException e) {
    e.printStackTrace();
}

// 2. The overwrite flag can explicitly be set to false to make intention clear
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length(), false /* overwrite */);
} catch (IOException e) {
    e.printStackTrace();
}

// 3. If the max overload is needed, access conditions must be used to prevent overwriting
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    // Setting IfNoneMatch="*" ensures the upload will fail if there is already a blob at the destination.
    options.setRequestConditions(new BlobRequestConditions().setIfNoneMatch("*"));
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

Charger un objet blob et remplacer s’il en existe déjà un

Chargez des données dans un objet blob et remplacez toutes les données existantes à la destination.

/*
 * Rather than use an if block conditioned on an exists call, there are three ways to upload-if-exists in one
 * network call instead of two. Equivalent options are present on all upload methods.
 */
String dataSample = "samples";

// 1. The overwrite flag can explicitly be set to true. This will succeed as a create and overwrite.
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blobClient.upload(dataStream, dataSample.length(), true /* overwrite */);
} catch (IOException e) {
    e.printStackTrace();
}

/*
 * 2. If the max overload is needed and no access conditions are passed, the upload will succeed as both a
 * create and overwrite.
 */
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

/*
 * 3. If the max overload is needed, access conditions may be used to assert that the upload is an overwrite and
 * not simply a create.
 */
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    BlobParallelUploadOptions options =
        new BlobParallelUploadOptions(dataStream, dataSample.length());
    // Setting IfMatch="*" ensures the upload will succeed only if there is already a blob at the destination.
    options.setRequestConditions(new BlobRequestConditions().setIfMatch("*"));
    blobClient.uploadWithResponse(options, null, Context.NONE);
} catch (IOException e) {
    e.printStackTrace();
}

Charger un objet blob via un OutputStream

Chargez un objet blob en ouvrant un BlobOutputStream objet blob et en y écrivant via les API de flux standard.

/*
 * Opening a blob input stream allows you to write to a blob through a normal stream interface. It will not be
 * committed until the stream is closed.
 * This option is convenient when the length of the data is unknown.
 * This can only be done for block blobs. If the target blob already exists as another type of blob, it will
 * fail.
 */
try (BlobOutputStream blobOS = blobClient.getBlockBlobClient().getBlobOutputStream()) {
    blobOS.write(new byte[0]);
} catch (IOException e) {
    e.printStackTrace();
}

Télécharger des données à partir d’un objet blob

Téléchargez un objet blob sur un à l’aide d’un OutputStreamBlobClient.

BinaryData content = blobClient.downloadContent();

Télécharger un objet blob dans un flux

Téléchargez un objet blob sur un à l’aide d’un OutputStreamBlobClient.

try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
    blobClient.downloadStream(outputStream);
} catch (IOException e) {
    e.printStackTrace();
}

Télécharger un objet blob vers le chemin d’accès local

Téléchargez l’objet blob dans un fichier local à l’aide d’un BlobClient.

blobClient.downloadToFile("downloaded-file.jpg");

Lire un objet blob via un InputStream

Téléchargez un objet blob en ouvrant un BlobInputStream objet blob et en le lisant via les API de flux standard.

/*
 * Opening a blob input stream allows you to read from a blob through a normal stream interface. It is also
 * mark-able.
*/
try (BlobInputStream blobIS = blobClient.openInputStream()) {
    blobIS.read();
} catch (IOException e) {
    e.printStackTrace();
}

Énumérer des objets blob

Énumération de tous les objets blob à l’aide d’un BlobContainerClient.

for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("This is the blob name: " + blobItem.getName());
}

ou

Énumérez tous les objets blob et créez des clients pointant vers les éléments.

for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    BlobClient blobClient;
    if (blobItem.getSnapshot() != null) {
        blobClient = blobContainerClient.getBlobClient(blobItem.getName(), blobItem.getSnapshot());
    } else {
        blobClient = blobContainerClient.getBlobClient(blobItem.getName());
    }
    System.out.println("This is the new blob uri: " + blobClient.getBlobUrl());
}

Copier un objet blob

Copie d’un objet blob. Reportez-vous aux javadocs sur chacune de ces méthodes pour plus d’informations sur les exigences relatives à la source de copie et à son authentification.

SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<url-to-blob>", Duration.ofSeconds(1));
poller.waitForCompletion();

ou

blobClient.copyFromUrl("url-to-blob");

Générer un jeton SAS

Utilisez un instance d’un client pour générer un nouveau jeton SAS.

/*
 * Generate an account sas. Other samples in this file will demonstrate how to create a client with the sas
 * token.
 */
// Configure the sas parameters. This is the minimal set.
OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);
AccountSasPermission accountSasPermission = new AccountSasPermission().setReadPermission(true);
AccountSasService services = new AccountSasService().setBlobAccess(true);
AccountSasResourceType resourceTypes = new AccountSasResourceType().setObject(true);

// Generate the account sas.
AccountSasSignatureValues accountSasValues =
    new AccountSasSignatureValues(expiryTime, accountSasPermission, services, resourceTypes);
String sasToken = blobServiceClient.generateAccountSas(accountSasValues);

// Generate a sas using a container client
BlobContainerSasPermission containerSasPermission = new BlobContainerSasPermission().setCreatePermission(true);
BlobServiceSasSignatureValues serviceSasValues =
    new BlobServiceSasSignatureValues(expiryTime, containerSasPermission);
blobContainerClient.generateSas(serviceSasValues);

// Generate a sas using a blob client
BlobSasPermission blobSasPermission = new BlobSasPermission().setReadPermission(true);
serviceSasValues = new BlobServiceSasSignatureValues(expiryTime, blobSasPermission);
blobClient.generateSas(serviceSasValues);

S’authentifier avec l’identité Azure

La bibliothèque d’identités Azure prend en charge Azure Active Directory pour l’authentification auprès du Stockage Azure.

BlobServiceClient blobStorageClient = new BlobServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Définir un proxy lors de la création d’un client

ProxyOptions options = new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 888));
BlobServiceClient client = new BlobServiceClientBuilder()
    .httpClient(new NettyAsyncHttpClientBuilder().proxy(options).build())
    .buildClient();

ou

Autorisez le générateur de client à déterminer le type à utiliser, mais construisez-le HttpClient avec des configurations passées.

HttpClientOptions clientOptions = new HttpClientOptions()
    .setProxyOptions(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("localhost", 888)));
BlobServiceClient client = new BlobServiceClientBuilder()
    .clientOptions(clientOptions)
    .buildClient();

Dépannage

Lorsque vous interagissez avec des objets blob à l’aide de cette bibliothèque cliente Java, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST. Par exemple, si vous essayez de récupérer un conteneur ou un objet blob qui n’existe pas dans votre compte de stockage, une 404 erreur est retournée, indiquant Not Found.

Client HTTP par défaut

Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.

Bibliothèque SSL par défaut

Toutes les bibliothèques de client utilisent par défaut la bibliothèque BoringSSL Tomcat native pour permettre des performances de niveau natif pour les opérations SSL. La bibliothèque BoringSSL est un fichier uber jar contenant des bibliothèques natives pour Linux/macOS/Windows. Elle offre de meilleures performances que l’implémentation SSL par défaut au sein du JDK. Pour plus d’informations, notamment sur la réduction de la taille des dépendances, consultez la section du wiki consacrée à l’optimisation des performances.

Étapes suivantes

Plusieurs exemples de SDK Java d’objets blob de stockage sont disponibles dans le dépôt GitHub du SDK. Ces exemples fournissent un exemple de code pour des scénarios supplémentaires couramment rencontrés lors de l’utilisation de Key Vault :

Étapes suivantes - Exemples

Les exemples sont expliqués en détail ici.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions