Bibliotecas de Azure Storage para Java
Las bibliotecas de Azure Storage para Java proporcionan clases para trabajar con datos en su cuenta de Almacenamiento de Azure y con la propia cuenta de almacenamiento. Para más información sobre Azure Storage, consulte Introducción a Azure Storage.
Biblioteca cliente para el acceso a datos
La biblioteca cliente de Azure Storage para Java admite Blob Storage, Queue Storage, Azure Files y Azure Data Lake Storage Gen2 (biblioteca de versión preliminar).
Agregar el paquete al proyecto
Agregue las siguientes dependencias al archivo de Maven pom.xml según corresponda:
<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>
Para obtener más información sobre cómo agregar una dependencia en Java, consulte Adición de una dependencia.
Ejemplo de uso
En el ejemplo siguiente se crea un contenedor de almacenamiento y se carga un archivo local en el contenedor de almacenamiento.
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");
Para obtener más ejemplos, revise el archivo Léame de la biblioteca cliente.
Paquetes disponibles
En la tabla siguiente se describen las versiones recomendadas de la biblioteca cliente de almacenamiento para Java.
| Versión de la biblioteca | Servicios admitidos | Maven | Referencia/Javadoc | Source, Readme, Examples |
|---|---|---|---|---|
| Versión 12 | Blob, Queue, File y Data Lake | Blob Cola Archivo Data Lake |
Blob Cola Archivo Data Lake |
Blob (inicio rápido) Cola Archivo Data Lake |
| Versión 8 | Blob, Queue, File y Table | Todos los servicios | Referencia de la versión 8 | Todos los servicios (inicio rápido) |
Consulte la página Versiones del SDK de Azure para obtener más información sobre cómo instalar y usar los paquetes en versión preliminar.
Biblioteca cliente para la administración de recursos
Use el proveedor de recursos de Azure Storage para administrar cuentas de almacenamiento, claves de cuenta, niveles de acceso, etc. Para usar la biblioteca del proveedor de recursos, agregue una dependencia al archivo de Maven pom.xml . La versión más reciente de la biblioteca del proveedor de recursos está disponible en Maven.
Para obtener más información sobre la biblioteca del proveedor de recursos, consulte la referencia de administración . El código fuente de la biblioteca del proveedor de recursos está disponible en el repositorio del SDK de Java de Azure.
En el ejemplo siguiente se crea una nueva cuenta de almacenamiento en la suscripción y se recuperan sus claves de acceso.
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());
}
Problemas conocidos
Las versiones anteriores del SDK de Azure Storage para Java (v12) tienen uno o varios problemas críticos conocidos, que se detallan a continuación. Estos problemas pueden afectar a la escritura o lectura de datos de la cuenta de Azure Storage. Si usa una versión anterior de una biblioteca cliente, se recomienda actualizar a la versión más reciente.
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Blob de Azure Storage | De 12.0 a 12.10.0, de 12.19.0 a 12.22.0 | 12.22.1 | Actualización a la versión más reciente |
| Azure File Data Lake | De 12.0 a 12.7.0 | 12.8.0 | Actualización a la versión más reciente |
| Recurso compartido de archivos de Azure | 12.0 a 12.4.1 | 12.5.0 | Actualización a la versión más reciente |
| Cola de Azure Storage | 12.0 a 12.6.0 | 12.7.0 | Actualización a la versión más reciente |
| criptografía de Azure Blob Storage | 12.0 a 12.16.1 | 12.17.0 | Actualización a la versión más reciente |
Si tiene alguna pregunta o necesita ayuda adicional, cree una incidencia de soporte técnico con las siguientes opciones:
- Tipo de problema: Requisitos previos técnicos
- Tipo de servicio: Blob Storage
- Resumen: #JavaSDKv12
- Tipo de problema: desarrollo
- Subtipo de problema: biblioteca cliente o SDK
Lista de problemas conocidos
- Problema de sobrescritura del búfer con
BlobOutputStream - Datos no válidos cargados durante los reintentos
- Carga que se devuelve incorrectamente como correcta cuando
IOExceptionse produce - Datos incorrectos que se descargan con
downloadToFile - No se respeta el parámetro overwrite al cargar un archivo grande, lo que da lugar a una sobrescritura incorrecta.
- Operación de sobrescritura invertida para el parámetro de sobrescritura, lo que da lugar a una sobrescritura incorrecta
- El contenido del mensaje se borra incorrectamente cuando solo se establece el tiempo de espera de visibilidad
- Cifrado del lado cliente actualizado para usar AES-GCM debido a vulnerabilidades de seguridad en modo CBC
- Datos incorrectos que se descargan con downloadToFile() cuando se reintentan las solicitudes REST subyacentes
- Mensaje de error InvalidHeaderValue al usar la versión beta del SDK
1. Problema de sobrescritura del búfer con BlobOutputStream
Descripción del problema
Si se usa un BlobOutputStream objeto para cargar blobs, en algunos escenarios, este uso puede dar lugar a que un objeto no válido se escriba en Azure Blob Storage. BlobOutputStream el objeto se puede obtener a través de BlockBlobClient.getBlobOutputStream().
Cargar un archivo mayor que el valor de MaxSingleUploadSize usar el write() método de la BlobOutputStream clase da como resultado que un objeto no válido se escriba en Azure Blob Storage. El valor predeterminado de MaxSingleUploadSize es 256 MiB. Puede cambiar este valor llamando al setMaxSingleUploadSizeLong() método de la ParallelTransferOptions clase .
Una vez que el tamaño de los datos de entrada cruza MaxSingleUploadSize, el write() método de BlobOutputStream vuelve antes de realizar una copia profunda de los datos de entrada. Si la aplicación que invoca sobrescribe la matriz de bytes de datos de entrada con otros datos antes de que se produzca la copia en profundidad, los datos no válidos se pueden escribir en el blob.
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Blob de Azure Storage | 12.0 a 12.10.0 | 12.10.1 | Actualización a la versión más reciente o al mínimo 12.22.1 |
Pasos recomendados
- Actualice las versiones de la biblioteca cliente según la tabla anterior.
- Compruebe si el código de la aplicación llama a
BlockBlobClient.getBlobOutputStream(). Si lo encuentra, la aplicación se ve afectada.
Además, puede identificar los blobs potencialmente afectados debido a este problema en la cuenta de Azure Storage. Siga estos pasos para identificar los blobs potencialmente afectados:
- Compruebe si la aplicación usa
BlobOutputStreampara cargar blobs (obtenidos a través deBlockBlobClient.getBlobOutputStream()). Si no es así, este problema no afecta a la aplicación. Sin embargo, se recomienda actualizar la aplicación para que use la versión 12.22.1 o posterior. - Obtenga el valor de la
MaxSingleUploadSizeaplicación (256 MiB de forma predeterminada). Examine el código para obtenersetMaxSingleUploadSizeLong()el método de laParallelTransferOptionsclase y obtenga el valor que proporcionó para esta propiedad. - Identifique el período de tiempo en el que la aplicación usó la versión de la biblioteca cliente con este problema (de 12.0 a 12.10.0)
- Identifique todos los blobs cargados en esta ventana de tiempo. Puede obtener una lista de blobs mediante una llamada a la
List Blobsoperación con PowerShell PowerShell, la CLI de Azure u otra herramienta. También puede aprovechar la característica de inventario de blobs.
Siguiendo estos pasos indicará blobs que podrían verse afectados por el problema crítico y que pueden no ser válidos. Inspeccione estos blobs para determinar cuáles pueden ser no válidos.
Volver a la lista de problemas conocidos
2. Datos no válidos cargados durante los reintentos
Descripción del problema
Las bibliotecas cliente que se enumeran a continuación tienen un error que puede cargar datos incorrectos durante los reintentos después de una solicitud de servicio con errores (por ejemplo, un reintento causado por una respuesta HTTP 500).
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Blob de Azure Storage | De 12.0 a 12.6.1 | 12.7.0 | Actualización a la versión más reciente o al mínimo 12.22.1 |
| Azure File Data Lake | De 12.0 a 12.1.2 | 12.2.0 | Actualización a la versión más reciente o al mínimo 12.8.0 |
| Recurso compartido de archivos de Azure | 12.0 a 12.4.1 | 12.5.0 | Actualización a la versión más reciente o al mínimo 12.5.0 |
Pasos recomendados
- Actualice las versiones de la biblioteca cliente según la tabla anterior.
Nota: Azure no tiene la capacidad de recuperar objetos escritos incorrectamente. Como cualquier posible impacto se produce antes de la carga, Azure no tiene una copia válida de ningún objeto afectado. Si tiene el archivo original, se puede volver a cargar en la cuenta de almacenamiento.
Volver a la lista de problemas conocidos
3. Cargar la devolución incorrecta como correcta cuando IOException se produce
Descripción del problema
Todas las sobrecargas de void BlobClient.upload() y void BlobClient.uploadWithResponse() detectan silenciosamente las respuestas de error del servicio de almacenamiento. El método debe devolver o iniciarse como su indicador de éxito o error. La excepción, que debería haberse registrado y propagado, en su lugar, se escribiría directamente en el error estándar y, a continuación, se tragó, a pesar de haber producido el único indicador de error para la API. Por lo tanto, el método devuelve correctamente, lo que hace que el autor de la llamada piense que la operación se completó. Esto da como resultado que el blob no se haya escrito en el almacenamiento, a pesar de que la biblioteca indica que se ha realizado correctamente.
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Blob de Azure Storage | De 12.0 a 12.4.0 | 12.5.0 | Actualización a la versión más reciente o al mínimo 12.22.1 |
Pasos recomendados
Actualice las versiones de la biblioteca cliente según la tabla anterior.
Volver a la lista de problemas conocidos
4. Datos incorrectos descargados con downloadToFile
Descripción del problema
La escritura asincrónica de búfer tiene una condición de carrera en la que el búfer entre la secuencia de red y la secuencia de archivos se podría reutilizar para los datos entrantes antes de vaciarse en el archivo. Esto hace que el archivo descargado esté dañado, donde algunos datos se repiten inmediatamente, sobrescribiendo los datos válidos en su lugar. El objeto de Storage sigue siendo correcto.
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Blob de Azure Storage | De 12.0 a 12.2.0 | 12.3.0 | Actualización a la versión más reciente o al mínimo 12.22.1 |
Pasos recomendados
Actualice las versiones de la biblioteca cliente según la tabla anterior.
Volver a la lista de problemas conocidos
5. No se respeta el parámetro overwrite al cargar un archivo grande, lo que da lugar a una sobrescritura incorrecta.
Descripción del problema
La marca de sobrescritura no se respeta en los casos en los que hay otro trabajo de carga paralelo en curso. Esto produce que no sobrescriba un objeto en Storage cuando se pretende.
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Blob de Azure Storage | 12.0 | 12.1.0 | Actualización a la versión más reciente o al mínimo 12.22.1 |
Pasos recomendados
Actualice las versiones de la biblioteca cliente según la tabla anterior.
Volver a la lista de problemas conocidos
6. Operación de sobrescritura invertida para el parámetro de sobrescritura, lo que da lugar a una sobrescritura incorrecta
Descripción del problema
El parámetro overwrite y la operación de sobrescritura se invierten en DataLakeFileClient.flush(long) las funciones y DataLakeFileClient.flush(long, bool) . Ningún otro comportamiento de la biblioteca llama a estos métodos. Esto da como resultado sobrescribir un objeto en Storage cuando el usuario no tenía intención de sobrescribirlo cuando se pretende.
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Azure File Data Lake | De 12.0 a 12.7.0 | 12.8.0 | Actualización a la versión más reciente o al mínimo 12.8.0 |
Pasos recomendados
Actualice las versiones de la biblioteca cliente según la tabla anterior.
Volver a la lista de problemas conocidos
7. El contenido del mensaje se borra incorrectamente cuando solo se establece el tiempo de espera de visibilidad
Descripción del problema
El contenido del mensaje de cola se borra en error cuando solo se estableció o actualizó el tiempo de espera de visibilidad.
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Cola de Azure Storage | 12.0 a 12.6.0 | 12.7.0 | Actualización a la versión más reciente o al mínimo 12.7.0 |
Pasos recomendados
Actualice las versiones de la biblioteca cliente según la tabla anterior.
Volver a la lista de problemas conocidos
8. Cifrado del lado cliente actualizado para usar AES-GCM debido a vulnerabilidades de seguridad en modo CBC
Descripción del problema
Para mitigar una vulnerabilidad de seguridad que se encuentra en el modo CBC, el SDK de Java v12 ha publicado una nueva versión del cifrado del lado cliente denominada v2, que usa AES-GCM para el cifrado del lado cliente en lugar del modo CBC. Los SDK actualizados son compatibles con versiones anteriores y proporcionan la capacidad de leer y escribir datos cifrados con la versión v1 . Para obtener información completa, lea Actualización del cifrado del lado cliente en el SDK para solucionar la vulnerabilidad de seguridad. En la sección 2 de la entrada de blog se describen los pasos que se deben seguir para ver si este problema le afecta.
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| criptografía de Azure Blob Storage | 12.0 a 12.16.1 | 12.17.0 | Actualización a la versión más reciente |
Pasos recomendados
Actualice las versiones de la biblioteca cliente según la tabla anterior. Lea Actualización del cifrado del lado cliente en el SDK para solucionar la vulnerabilidad de seguridad para la acción recomendada.
Volver a la lista de problemas conocidos
9. Datos incorrectos que se descargan con downloadToFile() cuando se reintentan las solicitudes REST subyacentes
Descripción del problema
La biblioteca de Azure SDK para Java Storage tenía un error en el que los datos incorrectos se podían escribir en un archivo con el downloadToFile() método cuando algunas de las solicitudes REST de almacenamiento subyacentes experimentaron un error de red a mitad de camino. Este error se introdujo originalmente en el verano de 2022 y fue revisado en mayo de 2023 volviendo al comportamiento anterior. Las versiones afectadas son 12.19.0 a 12.22.0. La revisión está en la versión 12.22.1.
Detalles del problema
| Biblioteca de cliente | Versiones afectadas | Versión mínima con seguridad demostrada | Acción recomendada |
|---|---|---|---|
| Blob de Azure Storage | De 12.19.0 a 12.22.0 | 12.22.1 | Actualización a la versión más reciente o al mínimo 12.22.1 |
Pasos recomendados
Actualice las versiones de la biblioteca cliente según la tabla anterior.
Volver a la lista de problemas conocidos
10. Mensaje de error InvalidHeaderValue al usar la versión beta del SDK
En escenarios poco frecuentes, las aplicaciones que se han actualizado a la versión beta más reciente o disponible con carácter general del SDK pueden recibir un InvalidHeaderValue mensaje de error. Este problema puede producirse al usar cualquiera de las bibliotecas de Storage. El mensaje de error es similar al ejemplo siguiente:
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 ha actualizado a la versión beta más reciente o disponible con carácter general del SDK y experimenta este error, se recomienda cambiar a la versión anterior disponible con carácter general del SDK para ver si el problema se resuelve. Si el problema persiste o si la recomendación no es factible, abra una incidencia de soporte técnico para explorar más opciones.
Azure SDK for Java
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de