Ejercicio: configuración e inicialización de la biblioteca cliente

10 minutos

El siguiente es un flujo de trabajo típico para aplicaciones que usan Azure Blob Storage:

Recuperar configuración: en el inicio, cargue la configuración de la cuenta de almacenamiento, normalmente una cadena de conexión de la cuenta de almacenamiento.
Inicializar el cliente: Para inicializar la biblioteca de cliente de Azure Storage, use la cadena de conexión. Esta inicialización crea los objetos que usa la aplicación para trabajar con la API de Blob Storage.
Usar: Para trabajar con contenedores y blobs, realice llamadas API con la biblioteca de cliente.

Configuración de una cadena de conexión

Antes de ejecutar la aplicación, obtenga la cadena de conexión de la cuenta de almacenamiento que use. Puede utilizar cualquier interfaz de administración de Azure para obtenerla, como Azure Portal, la CLI de Azure y Azure PowerShell. Cuando configure la aplicación web para ejecutar el código cerca del final de este módulo, usará la CLI de Azure para obtener la cadena de conexión de la cuenta de almacenamiento que ha creado antes.

Las cadenas de conexión de la cuenta de almacenamiento incluyen la clave de cuenta. Considere la clave de cuenta un secreto y almacénelo siempre de forma segura. Aquí, almacenará la cadena de conexión en una configuración de aplicación de App Service. La configuración de la aplicación de App Service es un lugar seguro para los secretos de la aplicación. Este diseño no admite el desarrollo local y no es una solución sólida de un extremo a otro por sí misma.

Importante

En este ejemplo de código se usa una cadena de conexión para autorizar el acceso a la cuenta de almacenamiento. Esta configuración es por ejemplo. Las cadenas de conexión y las claves de acceso de la cuenta deben usarse con precaución en el código de aplicació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.

Para una seguridad óptima, Microsoft recomienda usar Microsoft Entra ID con identidades administradas para autorizar solicitudes contra datos de blob, cola y tabla, siempre que sea posible. Para obtener más información, consulte Autorizar el acceso a blobs mediante Microsoft Entra ID.

Inicialización del modelo de objetos de Blob Storage

En el SDK de Azure Storage para .NET, el patrón estándar para usar Blob Storage es el siguiente:

Cree una instancia de un nuevo objeto BlobServiceClient y proporcione la cadena de conexión a la cuenta de almacenamiento.
Para obtener un elemento BlobContainerClient, llame a GetBlobContainerClient en BlobServiceClient con el nombre del contenedor que quiere crear o con el que quiere interactuar.

En el código, estos pasos tienen el aspecto que se muestra a continuación.

BlobServiceClient blobServiceClient = new BlobServiceClient(storageConfig.ConnectionString);
BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient(storageConfig.FileContainerName);

Ninguna parte de este código de inicialización realiza llamadas a través de la red. Este hecho significa que algunas excepciones que se producen debido a información incorrecta no se inician hasta más tarde. Por ejemplo, si se proporciona una cadena de conexión con un formato incorrecto al constructor de la clase BlobServiceClient, se producirá una excepción inmediatamente. Sin embargo, si la cadena de conexión apunta a una cuenta de almacenamiento que no existe, no se produce ninguna excepción hasta que intente realizar una operación en la cuenta de almacenamiento.

En el SDK de Azure Storage para Java, el patrón estándar para usar Blob Storage consta de los pasos siguientes:

Cree un objeto BlobServiceClient mediante la creación de una instancia de un nuevo objeto BlobServiceClientBuilder usando la cadena de conexión a la cuenta de almacenamiento.
Para obtener un elemento BlobContainerClient, llame al método getBlobContainerClient en BlobServiceClient con el nombre del contenedor que quiere crear o con el que quiere interactuar.

En el código, estos pasos tienen el aspecto que se muestra a continuación.

BlobServiceClient blobServiceClient = BlobServiceClientBuilder()
    .connectionString(connectionString)
    .buildClient();
BlobContainerClient containerClient = blobServiceClient.getBlobContainerClient(containerName);

Ninguna parte de este código de inicialización realiza llamadas a través de la red. Este hecho significa que algunas excepciones que se producen debido a información incorrecta no se inician hasta más tarde. Por ejemplo, si se proporciona una cadena de conexión con un formato incorrecto a BlobServiceClientBuilder, se producirá una excepción inmediatamente. Sin embargo, si la cadena de conexión apunta a una cuenta de almacenamiento que no existe, no se produce ninguna excepción hasta que intente realizar una operación en la cuenta de almacenamiento.

Creación de contenedores al inicio

Para crear un contenedor cuando se inicia la aplicación o la primera vez que la aplicación intenta usar un contenedor, llame a CreateIfNotExistsAsync en BlobContainerClient.

CreateIfNotExistsAsync no inicia una excepción si el contenedor ya existe, pero realizará una llamada de red a Azure Blob Storage. Llame una vez durante la inicialización, no cada vez que intente usar un contenedor.

Para crear un contenedor cuando se inicia la aplicación o cuando intenta usarlo por primera vez, llame a exists en BlobContainerClient para comprobar si el contenedor ya existe. Si no existe, llame a create. Llame una vez durante la inicialización, no cada vez que intente usar un contenedor.

Ejercicio

Clonación y exploración de la aplicación sin terminar

Primero, clone la aplicación de inicio desde GitHub. Ejecute los siguientes comandos en la CLI de Azure para obtener una copia del código fuente y abrirla en el editor:
```
git clone https://github.com/MicrosoftDocs/mslearn-store-data-in-azure.git
cd mslearn-store-data-in-azure/store-app-data-with-azure-blob-storage/src/start
code .
```
En el editor, abra el archivo Controllers/FilesController.cs. No hay nada que hacer aquí, pero echemos un vistazo rápido a lo que hace la aplicación.

Este controlador implementa una API con tres acciones:
- Índice: (GET /api/Files) devuelve una lista de direcciones URL, una para cada archivo que se ha cargado. El front-end de la aplicación llama a este método para crear una lista de hipervínculos a los archivos cargados.
- Carga: (POST /api/Files) recibe el contenido de un archivo cargado y lo guarda.
- Descarga: (GET /api/Files/{filename}) descarga un archivo individual por su nombre.
Para realizar su trabajo, cada método usa una instancia de IStorage denominada storage. Hay una implementación incompleta de IStorage en Models/BlobStorage.cs por rellenar.

Incorporación del paquete NuGet

Agregue una referencia al SDK de Azure Storage. Ejecute los comandos siguientes en la CLI de Azure Shell:
```
dotnet add package Azure.Storage.Blobs
dotnet restore
```
Este comando garantiza que usa la versión más reciente de la biblioteca cliente de Blob Storage.

Configurar

Los valores de configuración que necesita son la cadena de conexión de la cuenta de almacenamiento y el nombre del contenedor que la aplicación usa para almacenar archivos. En este módulo, solo ejecutará la aplicación en Azure App Service. Siga el procedimiento recomendado de App Service y almacene los valores en la configuración de la aplicación de App Service. Usted realiza esto al crear la instancia de App Service. No hay nada que hacer en ese momento.

Cuando se trata de usar la configuración, la aplicación de inicio incluye la mecánica necesaria. El parámetro de constructor IOptions<AzureStorageConfig> en BlobStorage tiene dos propiedades: la cadena de conexión de la cuenta de almacenamiento y el nombre del contenedor que la aplicación usar para almacenar los blobs. Hay código en el método ConfigureServices de Startup.cs que carga los valores de configuración cuando se inicia la aplicación.

Inicialización

En el editor, abra Models/BlobStorage.cs. En la parte superior del archivo, agregue las siguientes instrucciones using para prepararlo para el código que se va a agregar.
```
using Azure;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
```
Busque el método Initialize. La aplicación llama a este método cuando se usa BlobStorage por primera vez. Si tiene curiosidad, puede consultar ConfigureServices en Startup.cs para ver cómo se realiza la llamada.

Initialize es donde quiere crear el contenedor si aún no existe. Reemplace la implementación actual de Initialize por el código siguiente y guarde su trabajo mediante CTRL+S.
```
public Task Initialize()
{
    BlobServiceClient blobServiceClient = new BlobServiceClient(storageConfig.ConnectionString);
    BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient(storageConfig.FileContainerName);
    return containerClient.CreateIfNotExistsAsync();
}
```

Clonación y exploración de la aplicación sin terminar

Primero, clone la aplicación de inicio desde GitHub. Ejecute los siguientes comandos en la CLI de Azure para obtener una copia del código fuente y abrirla en el editor:

git clone https://github.com/MicrosoftDocs/mslearn-store-data-in-azure.git
cd mslearn-store-data-in-azure/store-java-ee-application-data-with-azure-blob-storage/start
code .

En el editor, abra el archivo src/main/java/com/microsoft/azure/samples/jsf/IndexBean.java. No hay nada que hacer aquí, pero echemos un vistazo rápido a lo que hace la aplicación.

Este bean con ámbito de solicitud implementa tres acciones que usa la página src/main/webapp/index.xhtml de Java Server Faces (JSF):
- listFileNames: devuelve una lista de nombres de archivo, una para cada archivo que se ha cargado. La página index.xhtml llama a este método para crear una lista de hipervínculos a los archivos cargados.
- upload: recibe el contenido de un archivo cargado y lo guarda. El contenido y los metadatos del archivo se insertan en la propiedad uploadedFile mediante el marco JSF.
- download: descarga un archivo individual por su nombre.
Para realizar su trabajo, cada método usa una instancia de Storage denominada storage. Hay una implementación incompleta de Storage en src/main/java/com/microsoft/azure/samples/service/BlobStorage.java por rellenar.

Adición del SDK de Azure Storage para la referencia de Java

Se recomienda usar la lista de materiales de Azure para agregar bibliotecas cliente de Azure al proyecto. Proporciona una manera sencilla y elegante de organizar el uso de varias bibliotecas de cliente de Azure al tiempo que garantiza conflictos de dependencia mínimos.

En el editor, abra el archivo pom.xml.

Para agregar BOM de Azure al proyecto, agregue la siguiente sección dependencyManagement bajo la etiqueta xml project.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>1.0.6</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Para agregar el SDK de Azure Storage para Java, agregue el siguiente elemento dependency a la sección xml project/dependencies.
```
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob</artifactId>
</dependency>
```

Configurar

Los valores de configuración necesarios son la cadena de conexión de la cuenta de almacenamiento y el nombre del contenedor que la aplicación usará para almacenar archivos. En este módulo, solo ejecutará la aplicación en Azure App Service. Siga el procedimiento recomendado de App Service y almacene los valores en la configuración de la aplicación de App Service. Para ello, creemos la instancia de App Service. No hay nada que hacer en ese momento.

Cuando se trata de usar la configuración, la configuración de aplicaciones de App Service se pasa como variables de entorno al código de la aplicación. Los leerá en el código de inicialización.

Inicialización

En el editor, abra src/main/java/com/microsoft/azure/samples/service/BlobStorage.java. En la parte superior del archivo, agregue las siguientes instrucciones import para prepararlo para el código que se va a agregar durante el ejercicio.

import java.util.stream.Collectors;

import com.azure.storage.blob.BlobClient;
import com.azure.storage.blob.BlobContainerClient;
import com.azure.storage.blob.BlobServiceClient;
import com.azure.storage.blob.BlobServiceClientBuilder;
import com.azure.storage.blob.models.BlobItem;

Agregue una propiedad de clase en la clase BlobStorage para contener la referencia BlobContainerClient.
```
private BlobContainerClient blobContainerClient;
```
Sugerencia

Los clientes de Azure no tienen estado y son seguros para subprocesos. Se recomienda almacenar en caché sus instancias cuando proceda. Por ejemplo, la aplicación en la que trabaja usa un único contenedor con un nombre constante, por lo que es mejor almacenarla en caché en el ámbito de duración de la aplicación. BlobStorage se anota con @Singleton, por lo tanto, se recomienda almacenar la referencia BlobContainerClient en su campo.

Busque el método init con la anotación @PostConstruct. La aplicación llama a este método después de crear la instancia BlobStorage y antes de que se utilice por primera vez.

init es donde debe crear el contenedor si aún no existe. Reemplace la implementación actual de init por el código siguiente y guarde su trabajo.

@PostConstruct
private void init() {
    String connectionString = System.getenv("STORAGE_CONNECTION_STRING");
    String containerName = System.getenv("STORAGE_CONTAINER_NAME");
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .connectionString(connectionString)
        .buildClient();
    blobContainerClient = blobServiceClient.getBlobContainerClient(containerName);
    if (!blobContainerClient.exists()) {
        blobContainerClient.create();
    }
}

Ejercicio: configuración e inicialización de la biblioteca cliente

Configuración de una cadena de conexión

Inicialización del modelo de objetos de Blob Storage

Creación de contenedores al inicio

Ejercicio

Clonación y exploración de la aplicación sin terminar

Incorporación del paquete NuGet

Configurar

Inicialización

Clonación y exploración de la aplicación sin terminar

Adición del SDK de Azure Storage para la referencia de Java

Configurar

Inicialización

Comentarios