Comenzar con Azure Blob Storage y Java

Artigo
10/18/2024

En este artículo se muestra cómo conectarse a Azure Blob Storage mediante la biblioteca cliente Azure Blob Storage para Java. Una vez que se haya conectado, use las guías para desarrolladores para obtener información sobre cómo su código puede operar con contenedores, blobs y funciones del servicio Blob Storage.

Si desea empezar con un ejemplo completo, consulte Inicio rápido: Biblioteca cliente de Azure Blob Storage para Java.

Referencia de API | Paquete (Maven) | Código fuente de la biblioteca | Muestras | Enviar comentarios

Prerrequisitos

Una suscripción a Azure: cree una cuenta gratuita
Una cuenta de Azure Storage: cree una cuenta de almacenamiento
Kit de desarrollo de Java (JDK), versión 8 o posterior
Apache Maven se usa para la administración de proyectos en este ejemplo.

Configuración del proyecto

Nota

En este artículo se usa la herramienta de compilación Maven para compilar y ejecutar el código de ejemplo. Otras herramientas de compilación, como Gradle, también funcionan con Azure SDK para Java.

Use Maven para crear una nueva aplicación de consola o abrir un proyecto existente. Siga estos pasos para instalar paquetes y agregar las directivas necesarias import.

Instalar paquetes

Abra el archivo pom.xml en el editor de texto. Instale los paquetes mediante la inclusión del archivo BOM o la inclusión de una dependencia directa.

Inclusión del archivo BOM

Agregue azure-sdk-bom para tomar una dependencia de la versión más reciente 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. El uso de azure-sdk-bom le impide especificar la versión de cada dependencia individual. Para más información sobre el BOM, consulte el archivo LÉAME de 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>

Agregue los siguientes elementos de dependencia al grupo de dependencias. La dependencia de azure-identity es necesaria para las conexiones sin contraseña a los servicios de Azure.

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

Inclusión de una dependencia directas

Para tomar dependencia de una versión determinada de la biblioteca, agregue la dependencia directa al proyecto:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>{package_version_to_target}</version>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
      <version>{package_version_to_target}</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{package_version_to_target}</version>
</dependency>

Inclusión de directivas de importación

A continuación, abra el archivo de código y agregue las directivas import necesarias. En este ejemplo, agregamos las siguientes directivas en el archivo App.java:

import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.specialized.*;
import com.azure.storage.common.*;

Información de la biblioteca cliente de blobs:

com.azure.storage.blob: contiene las clases principales (objetos de cliente) que puede usar para operar en el servicio, los contenedores y los blobs.
com.azure.storage.blob.models: todas las demás clases de utilidad, estructuras y tipos de enumeración.
com.azure.storage.blob.specialized: contiene clases que puede usar para llevar a cabo operaciones específicas de un tipo de blob (por ejemplo: anexar blobs).

Autorización del acceso y conexión a Blob Storage

Para conectar una aplicación a Blob Storage, cree una instancia de la clase BlobServiceClient. También puede usar la clase BlobServiceAsyncClient para la programación asincrónica. Este objeto es el punto inicial para interactuar con los recursos de datos en el nivel de cuenta de almacenamiento. Puede usarlo para operar en la cuenta de almacenamiento y sus contenedores. También puede usar el cliente de servicio para crear clientes de contenedor o clientes de blobs, en función del recurso con el que necesite trabajar.

Para obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Puede autorizar un objeto BlobServiceClient mediante un token de autorización de Microsoft Entra, una clave de acceso de cuenta o una firma de acceso compartido. Para una seguridad óptima, Microsoft recomienda usar Microsoft Entra ID con identidades administradas para autorizar solicitudes contra datos de blobs. Para más información, vea Autorización del acceso a blobs mediante Microsoft Entra ID.

Para autorizar con Microsoft Entra ID, deberá usar una entidad de seguridad. El tipo de entidad de seguridad que necesita depende de dónde se ejecute la aplicación. Use la siguiente tabla como guía:

Dónde se ejecuta la aplicación	Entidad de seguridad	Guía
Máquina local (desarrollo y pruebas)	Entidad de servicio	A fin de descubrir cómo registrar la aplicación, configurar un grupo de Microsoft Entra, asignar roles y configurar variables de entorno, vea Autorización del acceso mediante entidades de servicio para desarrolladores.
Máquina local (desarrollo y pruebas)	Identidad del usuario	Para obtener información sobre cómo configurar un grupo de Microsoft Entra, asignar roles e iniciar sesión en Azure, vea Autorización del acceso mediante credenciales de desarrollador.
Hospedado en Azure	Identidad administrada	Para más información sobre cómo habilitar la identidad administrada y asignar roles, consulte Autorización del acceso desde aplicaciones hospedadas en Azure mediante una identidad administrada.
Hospedado fuera de Azure (por ejemplo, aplicaciones locales)	Entidad de servicio	Para descubrir cómo registrar la aplicación, asignar roles y configurar variables de entorno, vea Autorización del acceso desde aplicaciones locales mediante una entidad de servicio de aplicación.

Autorización del acceso mediante DefaultAzureCredential

Una manera fácil y segura de autorizar el acceso y conectarse a Blob Storage es obtener un token de OAuth mediante la creación de una instancia de DefaultAzureCredential. Después, puede usar esa credencial para crear un objeto BlobServiceClient.

Asegúrese de dispone de las dependencias correctas en pom.xml y las directivas necesarias, tal como se describe en la configuración del proyecto.

En el ejemplo siguiente, se usa BlobServiceClientBuilder para compilar un objeto BlobServiceClient mediante DefaultAzureCredential, y se muestra cómo crear clientes de contenedor y blobs, si es necesario:

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

Use BlobServiceClientBuilder para crear un objeto BlobServiceClient mediante un token de SAS:

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .sasToken(sasToken)
            .buildClient();

    return blobServiceClient;
}

Para obtener más información sobre cómo generar y administrar los tokens de SAS, consulte los artículos siguientes:

Grant limited access to Azure Storage resources using shared access signatures (SAS) (Otorgar acceso limitado a recursos de Azure Storage con firmas de acceso compartido [SAS])
Creación de una SAS de cuenta con Java
Creación de una SAS de servicio con Java
Creación de una SAS de delegación de usuarios con Java

Nota:

Para escenarios en los que se utilizan firmas de acceso compartido (SAS), Microsoft recomienda usar un SAS de delegación de usuario. Una SAS de delegación de usuarios está protegida con credenciales de Microsoft Entra en lugar de la clave de cuenta.

Cree una StorageSharedKeyCredential con el nombre de la cuenta de almacenamiento y la clave de la cuenta. Después, use ese objeto para inicializar un objeto BlobServiceClient.

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Azure SDK client builders accept the credential as a parameter
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))
            .credential(credential)
            .buildClient();

    return blobServiceClient;        
}

También puede crear un objeto BlobServiceClient mediante una cadena de conexión.

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {
    // 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/")
            .connectionString(connectionString)
            .buildClient();

    return blobServiceClient;        
}

Para obtener información sobre cómo obtener claves de cuenta y directrices de procedimientos recomendados para administrar y proteger correctamente las claves, consulte Administración de claves de acceso de la cuenta de almacenamiento.

Importante

La clave de acceso de la cuenta debe usarse con precaución. Si la clave de acceso de la cuenta se pierde o se coloca por accidente en una ubicación no segura, el servicio puede volverse vulnerable. Cualquier persona que tenga la clave de acceso puede autorizar las solicitudes en la cuenta de almacenamiento y tiene acceso eficaz a todos los datos. DefaultAzureCredential proporciona características y ventajas de seguridad mejoradas y es el enfoque recomendado para administrar la autorización en los servicios de Azure.

Configuración del TTL de JVM para búsquedas de nombres DNS

La Máquina virtual Java (JVM) almacena en caché las respuestas de las búsquedas de nombres DNS correctas durante un período de tiempo específico, conocido como "período de vida" (TTL). El valor de TTL predeterminado para muchas JVM es -1, lo que significa que la JVM almacena en caché la respuesta indefinidamente o hasta que se reinicie la JVM.

Dado que los recursos de Azure usan entradas de nombre DNS que pueden cambiar, se recomienda establecer el valor de TTL de JVM en 10 segundos. Esta configuración garantiza que se devuelva una dirección IP actualizada para un recurso con la siguiente consulta de DNS.

Para cambiar el valor de TTL globalmente para todas las aplicaciones que usan JVM, establezca la propiedad networkaddress.cache.ttl en el archivo java.security.

networkaddress.cache.ttl=10

Para Java 8, el archivo java.security se encuentra en el directorio $JAVA_HOME/jre/lib/security. Para Java 11 y versiones posteriores, el archivo se encuentra en el directorio $JAVA_HOME/conf/security.

Compilación de la aplicación

A medida que compila aplicaciones para trabajar con recursos de datos en Azure Blob Storage, el código interactúa principalmente con tres tipos de recursos: cuentas de almacenamiento, contenedores y blobs. Para más información sobre estos tipos de recursos, cómo se relacionan entre sí y cómo interactúan las aplicaciones con los recursos, consulte Descripción de cómo interactúan las aplicaciones con los recursos de datos de Blob Storage.

En las guías siguientes se muestra cómo trabajar con recursos de datos y realizar acciones específicas mediante la biblioteca cliente de Azure Storage para Java:

Guía	Descripción
Configuración de una directiva de reintentos	Implemente directivas de reintento para las operaciones de cliente.
Copia de blobs	Copie un blob de una ubicación a otra.
Creación de un contenedor	Cree contenedores de blobs.
Creación de una SAS de delegación de usuario	Creación de una SAS de delegación de usuarios para un contenedor o blob.
Creación y administración de concesiones de blobs	Establezca y administre un bloqueo en un blob.
Creación y administración de concesiones de contenedores	Establezca y administre un bloqueo en un contenedor.
Eliminación y restauración de blobs	Elimine blobs y, si está habilitada la eliminación temporal, restaure los blobs eliminados.
Eliminación y restauración de contenedores	Elimine contenedores y, si está habilitada la eliminación temporal, restaure los contenedores eliminados.
Descarga de los blobs	Descargue blobs mediante cadenas, secuencias y rutas de acceso de archivo.
Búsqueda de blobs mediante etiquetas	Establezca y recupere etiquetas, así como use etiquetas para buscar blobs.
Enumeración de blobs	Enumere los blobs de diferentes maneras.
Enumeración de contenedores	Enumere los contenedores de una cuenta y las distintas opciones disponibles para personalizar una lista.
Administración de propiedades y metadatos (blobs)	Obtenga y establezca las propiedades y los metadatos de los blobs.
Administración de propiedades y metadatos (contenedores)	Obtenga y establezca las propiedades y los metadatos de los contenedores.
Optimización del rendimiento de las transferencias de datos	Optimice el rendimiento de las transferencias de datos.
Establecer o cambiar el nivel de acceso de un blob	Establezca o cambie el nivel de acceso de un blob en bloques.
Carga de blobs	Aprenda a cargar blobs mediante cadenas, secuencias, rutas de acceso de archivo y otros métodos.

Compartir por