Comenzar con Azure Blob Storage y Java

Artículo
01/19/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 conectado, el código puede funcionar en contenedores, blobs y características del servicio Blob Storage.

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 (SAS).

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 crear un objeto BlobServiceClient mediante DefaultAzureCredential:

public static BlobServiceClient GetBlobServiceClientTokenCredential() {
    TokenCredential credential = new DefaultAzureCredentialBuilder().build();

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

    return blobServiceClient;
}

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 para un contenedor con Java
Crear una SAS de servicio para un blob con Java
Creación de una SAS de delegación de usuarios para un contenedor con Java
Crear una SAS de delegación de usuarios para un blob con Java

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.

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
Creación de un contenedor	Cree contenedores.
Eliminación y restauración de contenedores	Elimine contenedores y, si está habilitada la eliminación temporal, restaure los contenedores eliminados.
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 (contenedores)	Obtenga y establezca las propiedades y los metadatos de los contenedores.
Creación y administración de concesiones de contenedores	Establezca y administre un bloqueo en un contenedor.
Creación y administración de concesiones de blobs	Establezca y administre un bloqueo en un blob.
Carga de blobs	Aprenda a cargar blobs mediante cadenas, secuencias, rutas de acceso de archivo y otros métodos.
Descarga de los blobs	Descargue blobs mediante cadenas, secuencias y rutas de acceso de archivo.
Copia de blobs	Copie un blob de una ubicación a otra.
Enumeración de blobs	Enumere los blobs de diferentes maneras.
Eliminar y restaurar	Elimine blobs y, si está habilitada la eliminación temporal, restaure los blobs eliminados.
Búsqueda de blobs mediante etiquetas	Establezca y recupere etiquetas, así como use etiquetas para buscar blobs.
Administración de propiedades y metadatos (blobs)	Obtenga y establezca las propiedades y los metadatos de los blobs.
Establecer o cambiar el nivel de acceso de un blob	Establezca o cambie el nivel de acceso de un blob en bloques.

Share via