Bibliothèques de stockage Azure pour Java
Les bibliothèques stockage Azure pour Java fournissent des classes permettant d’utiliser des données dans votre compte de stockage Azure et avec le compte de stockage lui-même. Pour plus d’informations sur stockage Azure, consultez Présentation du stockage Azure.
Bibliothèque cliente pour l’accès aux données
La bibliothèque cliente stockage Azure pour Java prend en charge le stockage Blob, le stockage file d’attente, la Azure Files et la Azure Data Lake Storage Gen2 (bibliothèque en préversion).
Ajouter le package à votre projet
Ajoutez les dépendances suivantes à votre fichier Maven pom.xml comme il convient :
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-blob</artifactId>
<version>12.4.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-queue</artifactId>
<version>12.3.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-file-share</artifactId>
<version>12.2.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-file-datalake</artifactId>
<version>12.0.0-preview.6</version>
</dependency>
Pour plus d’informations sur l’ajout d’une dépendance dans Java, consultez Ajouter une dépendance.
Exemple d’utilisation
L’exemple suivant crée un conteneur de stockage et charge un fichier local dans le conteneur de stockage.
String yourSasToken = "<insert-your-sas-token>";
/* Create a new BlobServiceClient with a SAS Token */
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
.endpoint("https://your-storage-account-url.storage.windows.net")
.sasToken(yourSasToken)
.buildClient();
/* Create a new container client */
try {
containerClient = blobServiceClient.createBlobContainer("my-container-name");
} catch (BlobStorageException ex) {
// The container may already exist, so don't throw an error
if (!ex.getErrorCode().equals(BlobErrorCode.CONTAINER_ALREADY_EXISTS)) {
throw ex;
}
}
/* Upload the file to the container */
BlobClient blobClient = containerClient.getBlobClient("my-remote-file.jpg");
blobClient.uploadFromFile("my-local-file.jpg");
Pour obtenir d’autres exemples, consultez le fichier LISEZ-moi de la bibliothèque cliente.
Packages disponibles
Le tableau suivant décrit les versions recommandées de la bibliothèque cliente de stockage pour Java.
| Version de la bibliothèque | Services pris en charge | Maven | Référence / Javadoc | Source, Lisez-moi, Exemples |
|---|---|---|---|---|
| Version 12 | Blob, File d’attente, Fichier et Data Lake |
Objet blob File d'attente Fichier Data Lake |
Objet blob File d'attente Fichier Data Lake |
Blob (démarrage rapide) File d'attente Fichier Data Lake |
| Version 8 | Objet blob, file d’attente, fichier et table | Tous les services | Informations de référence sur la version 8 | Tous les services (démarrage rapide) |
Pour plus d’informations sur l’installation et l’utilisation des packages en préversion, consultez la page Versions du Kit de développement logiciel (SDK) Azure .
Bibliothèque cliente pour la gestion des ressources
Utilisez le fournisseur de ressources Stockage Azure pour gérer les comptes de stockage, les clés de compte, les niveaux d’accès, etc. Pour utiliser la bibliothèque de fournisseur de ressources, ajoutez une dépendance à votre fichier Maven pom.xml . La dernière version de la bibliothèque de fournisseurs de ressources est disponible sur Maven.
Pour plus d’informations sur la bibliothèque de fournisseurs de ressources, consultez les informations de référence sur la gestion . Le code source de la bibliothèque de fournisseur de ressources est disponible dans le référentiel du Kit de développement logiciel (SDK) Java Azure.
L’exemple suivant crée un compte de stockage dans votre abonnement et récupère ses clés d’accès.
StorageAccount storageAccount = azureResourceManager.storageAccounts().define(storageAccountName)
.withRegion(Region.US_EAST)
.withNewResourceGroup(rgName)
.create();
// get a list of storage account keys related to the account
List<StorageAccountKey> storageAccountKeys = storageAccount.getKeys();
for (StorageAccountKey key : storageAccountKeys) {
System.out.println("Key name: " + key.keyName() + " with value "+ key.value());
}
Problèmes connus
Les versions antérieures du Kit de développement logiciel (SDK) Stockage Azure pour Java (v12) présentent un ou plusieurs problèmes critiques connus, qui sont détaillés ci-dessous. Ces problèmes peuvent avoir un impact sur l’écriture ou la lecture de données à partir de votre compte de stockage Azure. Si vous utilisez une version antérieure d’une bibliothèque cliente, nous vous recommandons d’effectuer une mise à jour vers la dernière version.
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| Azure Storage Blob | 12.0 à 12.10.0, 12.19.0 à 12.22.0 | 12.22.1 | Mettre à jour avec la dernière version |
| Azure File Data Lake | 12.0 à 12.7.0 | 12.8.0 | Mettre à jour avec la dernière version |
| Partage de fichiers Azure | 12.0 à 12.4.1 | 12.5.0 | Mettre à jour avec la dernière version |
| File d’attente de stockage Azure | 12.0 à 12.6.0 | 12.7.0 | Mettre à jour avec la dernière version |
| chiffrement Stockage Blob Azure | 12.0 à 12.16.1 | 12.17.0 | Mettre à jour avec la dernière version |
Si vous avez des questions ou si vous avez besoin d’aide supplémentaire, créez un ticket de support à l’aide des options suivantes :
- Type de problème : technique
- Type de service : Stockage Blob
- Résumé : #JavaSDKv12
- Type de problème : développement
- Sous-type de problème : Bibliothèque cliente ou SDK
Liste des problèmes connus
-
Problème de remplacement de la mémoire tampon avec
BlobOutputStream - Données non valides chargées pendant les nouvelles tentatives
-
Chargement incorrect en retournant comme réussi quand
IOExceptionse produit -
Données incorrectes téléchargées avec
downloadToFile - Paramètre de remplacement non respecté lors du chargement d’un fichier volumineux, ce qui entraîne un remplacement incorrect
- Opération de remplacement inversée pour le paramètre de remplacement, ce qui entraîne un remplacement incorrect
- Contenu du message incorrectement effacé lorsque seul le délai d’expiration de la visibilité est défini
- Chiffrement côté client mis à jour pour utiliser AES-GCM en raison de failles de sécurité en mode CBC
- Données incorrectes téléchargées avec downloadToFile() lorsque les requêtes REST sous-jacentes sont retentées
- Message d’erreur InvalidHeaderValue lors de l’utilisation de la version bêta du SDK
1. Problème de remplacement de la mémoire tampon avec BlobOutputStream
Description du problème
Si un BlobOutputStream objet est utilisé pour charger des objets blob, dans certains scénarios, cette utilisation peut entraîner l’écriture d’un objet non valide dans Stockage Blob Azure.
BlobOutputStream l’objet peut être obtenu via BlockBlobClient.getBlobOutputStream().
Le chargement d’un fichier supérieur à la valeur de MaxSingleUploadSize à l’aide de la write() méthode de la classe entraîne l’écriture BlobOutputStream d’un objet non valide dans Stockage Blob Azure. La valeur par défaut de MaxSingleUploadSize est 256 Mio. Vous pouvez modifier cette valeur en appelant la setMaxSingleUploadSizeLong() méthode de la ParallelTransferOptions classe .
Une fois que la taille des données d’entrée a traversé la MaxSingleUploadSize, la write() méthode de BlobOutputStream retourne avant d’effectuer une copie approfondie des données d’entrée. Si l’application appelante remplace le tableau d’octets de données d’entrée par d’autres données avant la copie approfondie, des données non valides peuvent être écrites dans l’objet blob.
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| Azure Storage Blob | 12.0 à 12.10.0 | 12.10.1 | Mettre à jour vers la dernière version ou la version minimale 12.22.1 |
Étapes recommandées
- Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus.
- Vérifiez si le code de votre application appelle
BlockBlobClient.getBlobOutputStream(). Si vous le trouvez, votre application est affectée.
En outre, vous pouvez identifier tous les objets blob potentiellement affectés en raison de ce problème dans votre compte stockage Azure. Suivez les étapes ci-dessous pour identifier les objets blob potentiellement affectés :
- Vérifiez si votre application utilise
BlobOutputStreampour charger des objets blob (obtenus viaBlockBlobClient.getBlobOutputStream()). Si ce n’est pas le cas, ce problème n’affecte pas votre application. Toutefois, nous vous recommandons toujours de mettre à niveau votre application pour utiliser la version 12.22.1 ou ultérieure. - Obtenez la
MaxSingleUploadSizevaleur de votre application (256 Mio par défaut). Analysez votre code pour lasetMaxSingleUploadSizeLong()méthode de la classe et obtenez laParallelTransferOptionsvaleur que vous avez fournie pour cette propriété. - Identifiez la fenêtre de temps lorsque votre application a utilisé la version de la bibliothèque cliente avec ce problème (12.0 à 12.10.0)
- Identifiez tous les objets blob chargés dans cette fenêtre de temps. Vous pouvez obtenir une liste d’objets blob en appelant l’opération
List Blobsavec PowerShell PowerShell, Azure CLI ou un autre outil. Vous pouvez également tirer parti de la fonctionnalité d’inventaire d’objets blob.
En suivant ces étapes, vous indiquez les objets blob qui sont potentiellement affectés par le problème critique et qui peuvent ne pas être valides. Inspectez ces objets blob pour déterminer ceux qui peuvent être non valides.
Retour à la liste des problèmes connus
2. Données non valides chargées pendant les nouvelles tentatives
Description du problème
Les bibliothèques clientes répertoriées ci-dessous présentent un bogue qui peut charger des données incorrectes pendant les nouvelles tentatives suite à un échec de demande de service (par exemple, une nouvelle tentative provoquée par une réponse HTTP 500).
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| Azure Storage Blob | 12.0 à 12.6.1 | 12.7.0 | Mettre à jour vers la dernière version ou la version minimale 12.22.1 |
| Azure File Data Lake | 12.0 à 12.1.2 | 12.2.0 | Mettre à jour vers la dernière version ou la version minimale 12.8.0 |
| Partage de fichiers Azure | 12.0 à 12.4.1 | 12.5.0 | Mettre à jour vers la dernière version ou la version minimale 12.5.0 |
Étapes recommandées
- Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus.
Remarque : Azure n’a pas la possibilité de récupérer des objets écrits de manière incorrecte. Comme tout impact potentiel se produit avant le chargement, Azure ne dispose pas d’une copie valide d’un objet affecté. Si vous avez le fichier d’origine, il peut être rechargé sur votre compte de stockage.
Retour à la liste des problèmes connus
3. Chargement retourné incorrectement comme ayant réussi quand IOException se produit
Description du problème
Toutes les surcharges et void BlobClient.upload()void BlobClient.uploadWithResponse() interceptent silencieusement les réponses d’erreur du service de stockage. La méthode doit retourner ou lever comme indicateur de réussite/erreur. L’exception, qui aurait dû être journalisée et propagée, serait au lieu de cela directement écrite dans l’erreur standard, puis avalée, bien qu’elle soit le seul indicateur d’échec pour l’API. La méthode retourne donc correctement, ce qui permet à l’appelant de penser que l’opération est terminée. Cela signifie que l’objet blob n’a pas été écrit dans le stockage, bien que la bibliothèque indique la réussite.
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| Azure Storage Blob | 12.0 à 12.4.0 | 12.5.0 | Mettre à jour vers la dernière version ou la version minimale 12.22.1 |
Étapes recommandées
Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus.
Retour à la liste des problèmes connus
4. Données incorrectes téléchargées avec downloadToFile
Description du problème
L’écriture de mémoire tampon asynchrone a une condition de concurrence où la mémoire tampon entre le flux réseau et le flux de fichiers peut être réutilisée pour les données entrantes avant d’être vidée dans le fichier. Cela entraîne l’endommagement du fichier téléchargé, où certaines données se répètent immédiatement, remplaçant les données valides à leur place. L’objet dans Stockage est toujours correct.
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| Azure Storage Blob | 12.0 à 12.2.0 | 12.3.0 | Mettre à jour vers la dernière version ou la version minimale 12.22.1 |
Étapes recommandées
Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus.
Retour à la liste des problèmes connus
5. Paramètre de remplacement non respecté lors du chargement d’un fichier volumineux, ce qui entraîne un remplacement incorrect
Description du problème
L’indicateur de remplacement n’est pas respecté dans les cas où un autre travail de chargement parallèle est en cours. Cela se traduit par le non-remplacement d’un objet dans Storage quand il est prévu.
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| Azure Storage Blob | 12.0 | 12.1.0 | Mettre à jour vers la dernière version ou la version minimale 12.22.1 |
Étapes recommandées
Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus.
Retour à la liste des problèmes connus
6. Opération de remplacement inversée pour le paramètre de remplacement, entraînant un remplacement incorrect
Description du problème
Le paramètre de remplacement et l’opération de remplacement sont inversés dans DataLakeFileClient.flush(long) les fonctions et DataLakeFileClient.flush(long, bool) . Aucun autre comportement de la bibliothèque n’appelle ces méthodes. Cela entraîne le remplacement d’un objet dans Le stockage lorsque l’utilisateur n’avait pas l’intention de le faire et l’échec du remplacement quand cela est prévu.
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| Azure File Data Lake | 12.0 à 12.7.0 | 12.8.0 | Mettre à jour vers la dernière version ou la version minimale 12.8.0 |
Étapes recommandées
Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus.
Retour à la liste des problèmes connus
7. Contenu du message incorrectement effacé lorsque seul le délai d’expiration de la visibilité est défini
Description du problème
Le contenu des messages de file d’attente est effacé par erreur lorsque seul le délai d’expiration de la visibilité a été défini ou mis à jour.
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| File d’attente de stockage Azure | 12.0 à 12.6.0 | 12.7.0 | Mettre à jour vers la dernière version ou la version minimale 12.7.0 |
Étapes recommandées
Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus.
Retour à la liste des problèmes connus
8. Chiffrement côté client mis à jour pour utiliser AES-GCM en raison de vulnérabilités de sécurité en mode CBC
Description du problème
Pour atténuer une vulnérabilité de sécurité détectée en mode CBC, le Kit de développement logiciel (SDK) Java v12 a publié une nouvelle version du chiffrement côté client appelée v2, qui utilise AES-GCM pour le chiffrement côté client au lieu du mode CBC. Les sdk mis à jour sont rétrocompatibles et vous permettent de lire et d’écrire des données chiffrées avec la version v1 . Pour plus d’informations, consultez Mise à jour du chiffrement côté client dans le Kit de développement logiciel (SDK) du Stockage Azure pour résoudre les vulnérabilités de sécurité. La section 2 du billet de blog décrit les étapes à suivre pour voir si ce problème vous affecte.
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| chiffrement Stockage Blob Azure | 12.0 à 12.16.1 | 12.17.0 | Mettre à jour avec la dernière version |
Étapes recommandées
Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus. Pour l’action recommandée, consultez Mise à jour du chiffrement côté client du Stockage Azure dans le KIT de développement logiciel (SDK ).
Retour à la liste des problèmes connus
9. Données incorrectes téléchargées avec downloadToFile() lorsque les requêtes REST sous-jacentes sont retentées
Description du problème
Le Kit de développement logiciel (SDK) Azure pour la bibliothèque de stockage Java présentait un bogue dans lequel des données incorrectes pouvaient être écrites dans un fichier avec la downloadToFile() méthode lorsque certaines des demandes REST de stockage sous-jacentes ont rencontré une défaillance réseau à mi-chemin. Ce bogue a été introduit à l’origine à l’été 2022 et a été corrigé en mai 2023 en revenant au comportement précédent. Les versions concernées sont 12.19.0 à 12.22.0. Le correctif est dans la version 12.22.1.
Publication des détails
| Bibliothèque cliente | Versions impactées | Version minimale sécurisée | Action recommandée |
|---|---|---|---|
| Azure Storage Blob | 12.19.0 à 12.22.0 | 12.22.1 | Mettre à jour vers la dernière version ou la version minimale 12.22.1 |
Étapes recommandées
Mettez à jour les versions de la bibliothèque cliente en fonction du tableau ci-dessus.
Retour à la liste des problèmes connus
10. Message d’erreur InvalidHeaderValue lors de l’utilisation de la version bêta du SDK
Dans de rares scénarios, les applications qui ont effectué une mise à niveau vers la dernière version bêta ou la version généralement disponible du KIT de développement logiciel (SDK) peuvent recevoir un InvalidHeaderValue message d’erreur. Ce problème peut se produire lors de l’utilisation de l’une des bibliothèques de stockage. Le message d’erreur ressemble à l’exemple suivant :
HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>
Si vous avez effectué une mise à niveau vers la dernière version bêta ou la version en disponibilité générale du KIT de développement logiciel (SDK) et que vous rencontrez cette erreur, il est recommandé de passer à la version précédente en disponibilité générale du Kit de développement logiciel (SDK) pour voir si le problème est résolu. Si le problème persiste ou si la recommandation n’est pas possible, ouvrez un ticket de support pour explorer d’autres options.
Azure SDK for Java