Compartir vía

Inicio rápido: Extensión Quarkus para Azure Blob Storage

Introducción a la extensión Quarkus para Azure Blob Storage para administrar blobs y contenedores. En este artículo, siga los pasos para probar código de ejemplo para tareas básicas.

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

Prerrequisitos

Configuración

En esta sección se explica cómo preparar un proyecto para trabajar con las extensiones de Quarkus para Azure Blob Storage.

Descarga de la aplicación de ejemplo

La aplicación de ejemplo que se usa en este inicio rápido es una aplicación básica de Quarkus.

Use Git para descargar una copia de la aplicación en el entorno de desarrollo y vaya al storage-blob-quarkus directorio .

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

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. Uso de DefaultAzureCredential y la biblioteca cliente de Identidad de Azure es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en tu código, como es el caso de Blob Storage. La extensión Quarkus para los servicios de Azure admite este enfoque.

DefaultAzureCredential es una implementación de cadena de credenciales proporcionada por la biblioteca cliente de Identidad de Azure para Java. DefaultAzureCredential admite varios métodos de autenticación y determina qué método se usa en tiempo de ejecución. Este enfoque permite a la aplicación usar diferentes métodos de autenticación en distintos entornos (locales frente a producción) sin implementar código específico del entorno.

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

En este inicio rápido, la aplicación se autentica mediante las credenciales de inicio de sesión de la CLI de Azure al ejecutarse localmente. Una vez implementada en Azure, la aplicación puede usar una identidad administrada. Esta transición entre entornos no requiere ningún cambio de código.

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

Al desarrollar localmente, asegúrese de que la cuenta de usuario que tiene acceso a datos de blobs tiene 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. Para más información sobre el rol Colaborador de datos de Storage Blob , consulte Colaborador de datos de Storage Blob. Para más información sobre los ámbitos disponibles para las asignaciones de roles, consulte Descripción del ámbito de RBAC de Azure.

En este escenario, asignará permisos a su cuenta de usuario, con un alcance limitado a la cuenta de almacenamiento, para 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ú izquierdo.

  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.

    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 Storage Blob 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 pasos siguientes:

  1. Asegúrese de que está autenticado con la misma cuenta de Microsoft Entra a la que asignó el rol en la cuenta de almacenamiento. En el ejemplo siguiente se muestra cómo autenticarse a través de la CLI de Azure:

    az login

  2. Asegúrese de proporcionar el punto de conexión de la cuenta de Azure Blob Storage. En el ejemplo siguiente se muestra cómo establecer el punto de conexión mediante la variable QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT de entorno a través de la CLI de Azure. Reemplace <resource-group-name> y <storage-account-name> por los nombres del grupo de recursos y de la cuenta de almacenamiento antes de ejecutar el comando:

    export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)

Nota:

Cuando se implementa en Azure, debe habilitar la identidad administrada en la aplicación y configurar la cuenta de almacenamiento para permitir que esa identidad administrada se conecte. Para más información sobre cómo configurar esta conexión entre servicios de Azure, consulte Autenticación de aplicaciones Java hospedadas en Azure.

Ejecución del ejemplo

En el ejemplo de código se realizan las siguientes acciones:

  • Inserta un objeto cliente que ya está autorizado para el acceso a datos utilizando la extensión Quarkus para Azure Blob Storage mediante DefaultAzureCredential.
  • Crea un contenedor en una cuenta de almacenamiento.
  • Carga un blob en el contenedor.
  • Enumera los blobs del contenedor.
  • Descarga los datos del blob en el sistema de archivos local.
  • Elimina los recursos de blob y contenedor creados por la aplicación.
  • Elimina el origen local y los archivos descargados.

Ejecute la aplicación en modo JVM mediante el comando siguiente:

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

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

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 de datos de los dos archivos. Puede compararlos y observar que son idénticos.

Opcionalmente, puede ejecutar el ejemplo en modo nativo. Para ello, debe tener GraalVM instalado o usar una imagen de generador para compilar el ejecutable nativo. Para obtener más información, vea Compilar un ejecutable nativo. En este inicio rápido se usa Docker como entorno de ejecución de contenedor para compilar un ejecutable nativo de Linux. Si no ha instalado Docker, puede descargarlo desde el sitio web de Docker.

Ejecute el comando siguiente para compilar y ejecutar el ejecutable nativo en un entorno de Linux:

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

Descripción del código de ejemplo

A continuación, recorrerá el código de ejemplo para comprender cómo funciona.

Inserción de un objeto de cliente con acceso autorizado

Trabajar con cualquier recurso de Azure mediante el SDK comienza con la creación de un objeto de cliente. La extensión Quarkus para Azure Blob Storage inserta automáticamente un objeto de cliente con acceso autorizado mediante DefaultAzureCredential.

Para insertar correctamente un objeto de cliente, primero debe agregar las extensiones quarkus-arc y quarkus-azure-storage-blob al archivo pom.xml como dependencias:

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

La extensión quarkus-arc es necesaria para utilizar la anotación @Inject e inyectar el objeto cliente en el código de tu aplicación. Las quarkus-bom dependencias y quarkus-azure-services-bom se usan para administrar las versiones de la plataforma Quarkus y la extensión Quarkus para los servicios de Azure.

A continuación, puede insertar el objeto de cliente en el código de la aplicación mediante la @Inject anotación :

@Inject
BlobServiceClient blobServiceClient;

Es todo lo que necesita codificar para obtener un objeto de cliente mediante la extensión Quarkus para Azure Blob Storage. Para asegurarse de que el objeto cliente está autorizado para acceder a la cuenta de almacenamiento en tiempo de ejecución, debe seguir los pasos descritos en la sección anterior Autenticación en Azure y autorización del acceso a datos de blobs antes de ejecutar la aplicación.

Administrar blobs y contenedores

En el ejemplo de código siguiente se muestra cómo crear un contenedor, cargar un blob, enumerar blobs en un contenedor y descargar un blob.

Nota:

La escritura en el sistema de archivos local se considera un procedimiento incorrecto en aplicaciones nativas en la nube. Sin embargo, en el ejemplo se usa el sistema de archivos local para ilustrar el uso de Blob Storage de una manera fácil de comprobar al usuario. Al llevar una aplicación a producción, revise las opciones de almacenamiento y elija la mejor opción para sus necesidades. Para más información, consulte Revisión de las opciones de almacenamiento.

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

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

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

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

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

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

Estas operaciones son similares a las descritas en Inicio rápido: Biblioteca cliente de Azure Blob Storage para Java SE. Para obtener explicaciones de código más detalladas, consulte las secciones siguientes en ese inicio rápido:

Limpieza

Puede elegir seguir los vínculos de la sección Pasos siguientes para implementar la aplicación Quarkus en Azure. O bien, puede limpiar la cuenta de almacenamiento eliminando el grupo de recursos. Para más información, consulte Grupo de recursos y eliminación de recursos de Azure Resource Manager.

Pasos siguientes

Ejemplos de Azure Storage y guías para desarrolladores deImplementación de una aplicación Java con Quarkus en un clúster de Azure Kubernetes ServiceImplementación de una aplicación Java con Quarkus en Azure Container Apps

  • Last updated on