Compartir vía

Inicio rápido: Biblioteca cliente de Azure Blob Storage para Java

  • Artículo

Nota:

La opción Compilar desde cero le guía paso a paso por el proceso de crear un nuevo proyecto, instalar los paquetes, escribir el código y ejecutar una aplicación de consola básica. Este enfoque se recomienda si quiere comprender todos los detalles implicados en la creación de una aplicación que se conecta a Azure Blob Storage. Si prefiere automatizar las tareas de implementación y empezar con un proyecto completado, elija Iniciar con una plantilla.

Nota:

La opción Iniciar con una plantilla usa Azure Developer CLI para automatizar las tareas de implementación y comienza con un proyecto completado. Este enfoque se recomienda si quiere explorar el código lo más rápido posible sin pasar por las tareas de configuración. Si prefiere instrucciones paso a paso para compilar la aplicación, elija Compilar desde cero.

Introducción a la biblioteca cliente de Azure Blob Storage para que Java gestione blobs y contenedores.

En este artículo, siga los pasos para instalar el paquete y probar el código de ejemplo para tareas básicas.

En este artículo, se usa Azure Developer CLI para implementar recursos de Azure y ejecutar una aplicación de consola completa con solo unos cuantos comandos.

Sugerencia

Si trabaja con recursos de Azure Storage en una aplicación de Spring, se recomienda considerar el uso de Spring Cloud Azure como alternativa. Spring Cloud Azure es un proyecto de código abierto que proporciona una integración perfecta de Spring con los servicios de Azure. Para más información sobre Spring Cloud Azure y para ver un ejemplo con Blob Storage, vea Carga de un archivo en un blob de Azure Storage.

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (Maven) | Ejemplos

Requisitos previos

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con la biblioteca cliente de Azure Blob Storage para Java.

Creación del proyecto

Cree una aplicación de Java llamada blob-quickstart.

  1. En una ventana de consola (por ejemplo, PowerShell o Bash), use Maven para crear una nueva aplicación de consola con el nombre blob-quickstart. Escriba el siguiente comando mvn para crear un proyecto de Java "Hello world!":

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.blobs.quickstart `
    --define artifactId=blob-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. La salida a partir de la generación del proyecto debe ser similar a la siguiente:

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.056 s
[INFO] Finished at: 2019-10-23T11:09:21-07:00
[INFO] ------------------------------------------------------------------------
    ```

  3. Cambie a la carpeta blob-quickstart recién creada.

    cd blob-quickstart

  4. En el directorio blob-quickstart, cree otro directorio denominado datos. En esta carpeta es donde se crearán y almacenarán los archivos de datos de blobs.

    mkdir data

Instalación de los paquetes

Abra el archivo pom.xml en el editor de texto.

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>

A continuación, 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-identity</artifactId>
</dependency>

Instalación del marco de la aplicación

En el directorio del proyecto, siga los pasos para crear la estructura básica de la aplicación:

  1. Navegue al directorio /src/main/java/com/blobs/quickstart.
  2. Abra el archivo App.java en un editor.
  3. Elimine la línea System.out.println("Hello world!");
  4. Agregue las directivas import necesarias

El código debe ser similar a este marco:

package com.blobs.quickstart;

/**
 * Azure Blob Storage quickstart
 */
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Con Azure Developer CLI instalado, puede crear una cuenta de almacenamiento y ejecutar el código de ejemplo con solo unos cuantos comandos. Puede ejecutar el proyecto en el entorno de desarrollo local o en DevContainer.

Inicialización de la plantilla de Azure Developer CLI e implementación de recursos

En un directorio vacío, siga estos pasos para inicializar la plantilla azd, aprovisionar recursos de Azure y empezar a trabajar con el código:

  • Clone los recursos del repositorio de inicio rápido de GitHub e inicialice la plantilla localmente:

    azd init --template blob-storage-quickstart-java

    Se le pedirá la siguiente información:

    • Nombre del entorno: este valor se usa como prefijo para todos los recursos de Azure creados por Azure Developer CLI. El nombre debe ser único en todas las suscripciones de Azure y tener entre 3 y 24 caracteres. El nombre solo puede contener números y letras minúsculas.

  • Inicie sesión en Azure:

    azd auth login

  • Aprovisione e implemente los recursos en Azure:

    azd up

    Se le pedirá la siguiente información:

    • Suscripción: la suscripción de Azure en la que se implementan los recursos.
    • Ubicación: la región de Azure donde se implementan los recursos.

    La implementación puede tardar unos minutos en finalizar. La salida del comando azd upincluye el nombre de la cuenta de almacenamiento recién creada, que necesitará más adelante para ejecutar el código.

Ejecución del código de ejemplo

En este punto, los recursos se implementan en Azure y el código está casi listo para ejecutarse. Siga estos pasos para actualizar el nombre de la cuenta de almacenamiento en el código y ejecute la aplicación de consola de ejemplo:

  • Actualizar el nombre de la cuenta de almacenamiento:
    1. En el directorio local, vaya al directorio blob-quickstart/src/main/java/com/blobs/quickstart.
    2. Abra el archivo App.java en su editor. Busque el marcador de posición <storage-account-name> y reemplácelo por el nombre real de la cuenta de almacenamiento creada por el comando azd up.
    3. Guarde los cambios.
  • Ejecute el proyecto:
    1. Navegue hasta el directorio blob-quickstart que contiene el archivo pom.xml. Compile el proyecto utilizando el siguiente comando mvn: 
      mvn compile
    2. Empaquete el código compilado en su formato distribuible: 
      mvn package
    3. Ejecute el siguiente comando mvn para ejecutar la aplicación: 
      mvn exec:java
  • Observar la salida: esta aplicación crea un archivo de prueba en la carpeta de datos local y lo carga en un contenedor de la cuenta de almacenamiento. Después, en el ejemplo se enumeran los blobs del contenedor y se descarga el archivo con un nombre nuevo para que pueda comparar los archivos antiguo y nuevo.

Para más información sobre cómo funciona el código de ejemplo, consulte Ejemplos de código.

Cuando haya terminado de probar el código, consulte la sección Limpieza de recursos para eliminar los recursos creados por el comando azd up.

Modelo de objetos

Azure Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados. Los datos no estructurados no se ciñen a ningún un modelo de datos o definición concretos, como texto o datos binarios. Blob Storage ofrece tres tipos de recursos:

  • La cuenta de almacenamiento
  • Un contenedor en la cuenta de almacenamiento
  • Un blob en el contenedor

En el siguiente diagrama se muestra la relación entre estos recursos.

Diagrama de arquitectura de Blob Storage

Use las siguientes clases de Java para interactuar con estos recursos:

Ejemplos de código

Estos fragmentos de código de ejemplo muestran cómo realizar las siguientes acciones con la biblioteca cliente de Azure Blob Storage para Java:

Importante

Asegúrese de dispone de las dependencias correctas en pom.xml y las directivas necesarias para que los códigos de ejemplo funcionen, tal y como se describe en la sección de configuración.

Nota:

La plantilla de Azure Developer CLI incluye un archivo con código de ejemplo ya implementado. En los ejemplos siguientes se proporcionan detalles para cada parte del código de ejemplo. La plantilla implementa el método de autenticación sin contraseña recomendado, como se describe en la sección Autenticación en Azure. El método de cadena de conexión se muestra como una alternativa, pero no se usa en la plantilla y no se recomienda para el código de producción.

Autenticación en Azure y autorización del acceso a datos de blobs

Las solicitudes de aplicación a Azure Blob Storage deben estar autorizadas. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure.Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código, incluido Blob Storage.

También puede autorizar las solicitudes a Azure Blob Storage mediante la clave de acceso de la cuenta. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser diligentes para no exponer nunca las claves de acceso en una ubicación que no sea segura. 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 ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

DefaultAzureCredential es una clase proporcionada por la biblioteca cliente de Azure Identity para Java. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

El orden y las ubicaciones en las que DefaultAzureCredential busca credenciales se pueden encontrar en la información general de la biblioteca de Azure Identity.

Por ejemplo, la aplicación puede autenticarse con las credenciales de inicio de sesión de Visual Studio Code cuando se desarrolla localmente. A continuación, la aplicación puede usar una identidad administrada una vez se haya implementado en Azure. No se necesitan cambios de código para esta transición.

Asignación de roles a la cuenta de usuario de Microsoft Entra

Al desarrollar localmente, asegúrese de que la cuenta de usuario que accede a los datos de blob tenga los permisos correctos. Necesitará el Colaborador de datos de blobs de almacenamiento para leer y escribir datos de blob. Para asignarse este rol a sí mismo, necesitará que se le asigne el rol Administrador de acceso de usuario u otro rol que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En este escenario, asignará permisos a la cuenta de usuario, cuyo ámbito es la cuenta de almacenamiento, a fin de seguir el principio de privilegios mínimos. Esta práctica solo proporciona a los usuarios los permisos mínimos necesarios y crea entornos de producción más seguros.

En el ejemplo siguiente se asignará el rol Colaborador de datos de blobs de almacenamiento a la cuenta de usuario, que proporciona acceso de lectura y escritura a los datos de blobs de la cuenta de almacenamiento.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure, pero en casos excepcionales puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

    Una captura de pantalla que muestra cómo asignar un rol.

  5. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Colaborador de datos de blobs de almacenamiento y seleccione el resultado coincidente y, a continuación, elija Siguiente.

  6. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  7. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  8. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Inicio de sesión y conexión del código de la aplicación a Azure mediante DefaultAzureCredential

Puede autorizar el acceso a los datos de la cuenta de almacenamiento mediante los siguientes pasos:

  1. Asegúrese de que esté autenticado con la misma cuenta de Microsoft Entra a la que asignó el rol en la cuenta almacenamiento. Puede autenticarse a través de la CLI de Azure, Visual Studio Code o Azure PowerShell.

    Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

    az login

  2. Para usar DefaultAzureCredential, asegúrese de que la dependencia azure-identity se agrega en pom.xml:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

  3. Agregue este código al método Main. Cuando el código se ejecute en la estación de trabajo local, usará las credenciales de desarrollador de la herramienta clasificada por orden de prioridad en la que ha iniciado sesión para autenticarse en Azure, como la CLI de Azure o Visual Studio Code.

    /*
 * The default credential first checks environment variables for configuration
 * If environment configuration is incomplete, it will try managed identity
 */
DefaultAzureCredential defaultCredential = 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(defaultCredential)
        .buildClient();

  4. Asegúrese de actualizar el nombre de la cuenta de almacenamiento en el URI de BlobServiceClient. El nombre de la cuenta de almacenamiento se puede encontrar en la página de información general de Azure Portal.

    Una captura de pantalla que muestra cómo encontrar el nombre de la cuenta de almacenamiento.

    Nota

    Cuando se implementa en Azure, se puede usar este mismo código para autorizar solicitudes a Azure Storage desde una aplicación que se ejecute en Azure. Sin embargo, deberá habilitar la identidad administrada en la aplicación en Azure. A continuación, configure la cuenta almacenamiento para permitir que esa identidad administrada se conecte. Para obtener instrucciones detalladas sobre la configuración de esta conexión entre los servicios de Azure, consulte el tutorial Autenticación desde aplicaciones hospedadas en Azure.

Crear un contenedor

Cree un nuevo contenedor en su cuenta de almacenamiento llamando al método createBlobContainer en el objeto blobServiceClient. En este ejemplo, el código añade un valor GUID al nombre del contenedor para asegurarse de que es único.

Agregue este código al final del método Main:

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

Para obtener más información sobre cómo crear un contenedor y explorar más ejemplos de código, consulte Creación de un contenedor de blobs con Java.

Importante

Los nombres de contenedor deben estar en minúsculas. Para más información acerca de los contenedores de nomenclatura y los blobs, consulte Naming and Referencing Containers, Blobs, and Metadata (Asignación de nombres y realización de referencias a contenedores, blobs y metadatos).

Carga de los blobs en un contenedor

Cargue un blob en un contenedor llamando al método uploadFromFile. El código del ejemplo crea un archivo de texto en el directorio local de datos para cargarlo en el contenedor.

Agregue este código al final del método Main:

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

Para obtener más información sobre cómo cargar blobs y explorar más ejemplos de código, consulte Carga de un blob con Java.

Enumerar los blobs de un contenedor

Enumere los blobs en el contenedor llamando al método listBlobs. En este caso, solo se ha agregado un blob al contenedor, por lo que la operación de enumeración devuelve simplemente dicho blob.

Agregue este código al final del método Main:

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

Para obtener más información sobre cómo enumerar blobs y explorar más ejemplos de código, consulte Enumeración de blobs con Java.

Descargar blobs

Descargue el blob creado previamente llamando al método downloadToFile. El código de ejemplo agrega el sufijo "DOWNLOAD" al nombre de archivo para que pueda ver ambos archivos en el sistema de archivos local.

Agregue este código al final del método Main:

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

Para obtener más información sobre cómo descargar blobs y explorar más ejemplos de código, consulte Descarga de un blob con Java.

Eliminación de un contenedor

El código siguiente limpia los recursos que creó la aplicación; para ello, quita todo el contenedor con el método delete. También elimina los archivos locales creados por la aplicación.

La aplicación se detiene para la entrada del usuario mediante una llamada a System.console().readLine() antes de eliminar el blob, el contenedor y los archivos locales. Esta es una buena oportunidad para verificar que los recursos se han creado correctamente antes de eliminarlos.

Agregue este código al final del método Main:

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

Para obtener más información sobre cómo eliminar un contenedor y explorar más ejemplos de código, consulte Eliminación y restauración de un contenedor de blobs con Java.

Ejecución del código

Esta aplicación crea un archivo de prueba en la carpeta local y lo carga en Blob Storage. Después, en el ejemplo se enumeran los blobs del contenedor y se descarga el archivo con un nombre nuevo para que pueda comparar los archivos antiguo y nuevo.

Siga los pasos para compilar, empaquetar y ejecutar el código

  1. Navegue hasta el directorio que contiene el archivo pom.xml y compile el proyecto mediante el siguiente comando mvn: 
    mvn compile
  2. Empaquete el código compilado en su formato distribuible: 
    mvn package
  3. Ejecute el siguiente comando mvn para ejecutar la aplicación: 
    mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
    Para simplificar el paso de ejecución, puede agregar exec-maven-plugin y pom.xml configurarlos como se muestra a continuación: 
    <plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>1.4.0</version>
  <configuration>
    <mainClass>com.blobs.quickstart.App</mainClass>
    <cleanupDaemonThreads>false</cleanupDaemonThreads>
  </configuration>
</plugin>
    Con esta configuración, puede ejecutar la aplicación con el siguiente comando: 
    mvn exec:java

La salida de la aplicación es similar al ejemplo siguiente (se omiten los valores UUID para mejorar la legibilidad):

Azure Blob Storage - Java quickstart sample

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Antes de comenzar el proceso de limpieza, compruebe la carpeta data para ver si están los dos archivos. Puede compararlos y comprobar que son idénticos.

Limpieza de recursos

Después de comprobar los archivos y finalizar las pruebas, presione la tecla ENTRAR para eliminar los archivos de prueba junto con el contenedor que creó en la cuenta de almacenamiento. También puede usar la CLI de Azure para eliminar recursos.

Cuando haya terminado con el inicio rápido, puede limpiar los recursos que creó con el siguiente comando:

azd down

Se le pedirá que confirme la eliminación de los recursos. Escriba y para confirmar.

Paso siguiente

Muestras y guías para desarrolladores de Azure Storage para Java