Biblioteca cliente de Blob de Azure Storage para Java, versión 12.24.1

Artículo
10/26/2023

Azure Blob Storage es la solución de almacenamiento de objetos de Microsoft para la nube. Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados. Los datos no estructurados son datos que no cumplen un modelo de datos o definición concreta, como texto o datos binarios.

Código | fuenteDocumentación | de referencia de APIDocumentación | de la API REST | Documentación del producto Muestras

Introducción

Requisitos previos

Kit de desarrollo de Java (JDK) con la versión 8 o posterior
Suscripción de Azure
Crear cuenta de almacenamiento

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para que dependa de la versión de disponibilidad general de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte el archivo Léame bom del SDK de 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>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

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

Inclusión de dependencias directas

Si desea depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

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

Creación de una cuenta de almacenamiento

Para crear una cuenta de almacenamiento, puede usar Azure Portal o la CLI de Azure.

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

La dirección URL de la cuenta de almacenamiento, identificada posteriormente como <your-storage-account-url>, tendría el siguiente formato: http(s)://<storage-account-name>.blob.core.windows.net

Autenticar el cliente

Para interactuar con el servicio de almacenamiento (Blob, Queue, Message, MessageId, File), deberá crear una instancia de la clase Service Client. Para que esto sea posible, necesitará la cadena saS de cuenta (firma de acceso compartido) de la cuenta de almacenamiento. Obtenga más información en Token de SAS.

Obtener credenciales

Token de SAS

a. Use el fragmento de código de la CLI de Azure siguiente para obtener el token de SAS de la cuenta de almacenamiento.

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}

Ejemplo:

CONNECTION_STRING=<connection-string>

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

b. Como alternativa, obtenga el token de SAS de cuenta de Azure Portal.

Vaya a la cuenta de almacenamiento.
Seleccione Shared access signature en el menú de la izquierda.
Haga clic en Generate SAS and connection string (después de la instalación)

Credencial de clave compartida

a. Use nombre de cuenta y clave de cuenta. El nombre de la cuenta es el nombre de la cuenta de almacenamiento.

Vaya a la cuenta de almacenamiento.
Seleccione Access keys en el menú de la izquierda.
En key1/key2 Copiar el contenido del Key campo

b. Use el cadena de conexión.

Vaya a la cuenta de almacenamiento.
Seleccione Access keys en el menú de la izquierda.
En key1/key2 Copiar el contenido del Connection string campo

Conceptos clave

Blob Storage está diseñado para:

Servicio de imágenes o documentos directamente a un explorador
Almacenar archivos para el acceso distribuido.
Realizar streaming de audio y vídeo.
Escritura en archivos de registro
Almacenar datos para copia de seguridad y restauración, recuperación ante desastres y archivado.
Almacenar de datos para el análisis por un servicio local u hospedado por Azure.

Formato de dirección URL

Los blobs son direccionables con el siguiente formato de dirección URL: La dirección URL siguiente direcciona un blob:

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

Sintaxis del URI de recurso

Para la cuenta de almacenamiento, el URI base para las operaciones de blob incluye el nombre de la cuenta solo:

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

Para los contenedores, el URI base incluye el nombre de la cuenta y el nombre del contenedor:

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

Para un blob, el URI base incluye el nombre de la cuenta, el nombre del contenedor y el nombre del blob:

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

Tenga en cuenta que es posible que los URI anteriores no contengan escenarios más avanzados, como nombres de dominio personalizados.

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes de Azure Storage Blob, entre las que se incluyen:

Creación de una BlobServiceClient
Creación de una BlobContainerClient
Creación de una BlobClient
Creación de un contenedor
Carga de datos en un blob
Carga de un blob desde una secuencia
Carga de un blob desde la ruta de acceso local
Carga de un blob si aún no existe uno
Cargar un blob y sobrescribir si ya existe uno
Carga de un blob a través de OutputStream
Descarga de datos de un blob
Descarga de un blob en una secuencia
Descarga de un blob en la ruta de acceso local
Lectura de un blob a través de InputStream
Enumerar blobs
Copia de un blob
Generar un token de SAS
Autenticación con la identidad de Azure
Establecer un proxy al compilar un cliente

Creación de una clase `BlobServiceClient`

Cree un BlobServiceClient objeto mediante el sasToken elemento generado anteriormente.

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

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

Creación de una clase `BlobContainerClient`

Cree un BlobContainerClient objeto mediante .BlobServiceClient

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

Cree un a BlobContainerClient partir del generador sasToken generado anteriormente.

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

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

Creación de una clase `BlobClient`

Cree un BlobClient objeto mediante .BlobContainerClient

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

Cree un a BlobClient partir del generador sasToken generado anteriormente.

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

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

Crear un contenedor

Cree un contenedor mediante .BlobServiceClient

blobServiceClient.createBlobContainer("mycontainer");

Cree un contenedor mediante .BlobContainerClient

blobContainerClient.create();

Carga de datos en un blob

Cargue BinaryData en un blob mediante un BlobClient generado a partir de .BlobContainerClient

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

Carga de un blob desde una secuencia

Cargue de a InputStream un blob mediante un BlockBlobClient generado a partir de .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();
}

Carga de un blob desde la ruta de acceso local

Cargue un archivo en un blob mediante un BlobClient generado a partir de .BlobContainerClient

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

Carga de un blob si aún no existe uno

Cargue datos en un blob y produzca un error si ya existe uno.

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

Cargar un blob y sobrescribir si ya existe uno

Cargue los datos en un blob y sobrescriba los datos existentes en el destino.

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

Carga de un blob a través de `OutputStream`

Cargue un blob abriendo y BlobOutputStream escribiendo en él a través de las API de flujo estándar.

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

Descarga de datos de un blob

Descargue un blob en un OutputStream objeto mediante .BlobClient

BinaryData content = blobClient.downloadContent();

Descarga de un blob en una secuencia

Descargue un blob en un OutputStream objeto mediante .BlobClient

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

Descarga de un blob en la ruta de acceso local

Descargue el blob en un archivo local mediante .BlobClient

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

Lectura de un blob a través de `InputStream`

Descargue un blob abriendo y BlobInputStream leyendo desde él a través de las API de flujo estándar.

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

Enumerar blobs

Enumerar todos los blobs mediante .BlobContainerClient

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

Enumere todos los blobs y cree nuevos clientes que apunte a los elementos.

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

Copia de un blob

Copia de un blob. Consulte los javadocs en cada uno de estos métodos para obtener más información sobre los requisitos sobre el origen de copia y su autenticación.

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

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

Generar un token de SAS

Use una instancia de un cliente para generar un nuevo token de 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);

Autenticación con la identidad de Azure

La biblioteca de identidades de Azure proporciona compatibilidad con Azure Active Directory para la autenticación con Azure Storage.

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

Establecer un proxy al compilar un cliente

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

Permita que el generador de clientes determine el HttpClient tipo que se va a usar, pero con configuraciones pasadas.

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

Solución de problemas

Al interactuar con blobs mediante esta biblioteca cliente de Java, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST . Por ejemplo, si intenta recuperar un contenedor o un blob que no existe en la cuenta de almacenamiento, se devuelve un 404 error, que indica Not Found.

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca Boring SSL es un archivo uber-jar que contiene bibliotecas nativas para Linux, macOS o Windows, que proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

Hay varios ejemplos del SDK de Java de Blob storage disponibles en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con Key Vault:

Ejemplos de pasos siguientes

Los ejemplos se explican en detalle aquí.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Compartir a través de