Compartir a través de

Tutorial: Carga de una imagen en un blob de Azure Storage con JavaScript

En este tutorial, usará una aplicación web estática para cargar archivos directamente en un blob de Azure Storage mediante el @azure/storage-blob paquete. La API genera un token de SAS siguiendo el patrón Valet Key, que le permite delegar de forma segura el acceso limitado sin exponer las credenciales completas.

Precaución

En este tutorial se muestra cómo hospedar la aplicación de funciones en un plan de consumo. Cuando planee proteger sus conexiones mediante el identificador de Microsoft Entra con identidades administradas, debe considerar la posibilidad de hospedar la aplicación en el plan de consumo flexible. El nivel de consumo flexible optimiza la seguridad al admitir el uso de identidades administradas y la integración de redes virtuales.

Prerrequisitos

Arquitectura de la aplicación

Esta arquitectura de aplicación incluye dos recursos de Azure:

  • Azure Static Web Apps hospeda tanto el cliente estático como la API de Azure Functions vinculada, y el servicio administra el recurso de API automáticamente.
  • Azure Storage para el almacenamiento de blobs.

Diagrama que muestra cómo interactúa un cliente desde su equipo para usar el sitio web para cargar un archivo directamente en Azure Storage.

Paso Descripción
1 El cliente se conecta al sitio web generado estáticamente. El sitio web está hospedado en Azure Static Web Apps.
2 El cliente utiliza ese sitio web para seleccionar un archivo para cargar. Para este tutorial, el marco front-end es Vite React y el archivo cargado es un archivo de imagen.
3 El sitio web llama a la API sas de Azure Functions para obtener un token de SAS basado en el nombre exacto del archivo que se va a cargar. La API sin servidor usa el SDK de Azure Blob Storage para crear el token de SAS. La API devuelve la dirección URL completa que se usará para cargar el archivo, que incluye el token de SAS como cadena de consulta.
https://YOUR-STORAGE-NAME.blob.core.windows.net/YOUR-CONTAINER/YOUR-FILE-NAME?YOUR-SAS-TOKEN
4 El sitio web front-end usa la dirección URL del token de SAS para cargar el archivo directamente en Azure Blob Storage.

Entornos locales y de compilación

En este tutorial se utilizan los siguientes entornos:

  • Desarrollo local con GitHub Codespaces o Visual Studio Code.
  • Compila e implementa con GitHub Actions.

Repositorio de aplicaciones de ejemplo de bifurcación con GitHub

En este tutorial se usan acciones de GitHub para implementar la aplicación de ejemplo en Azure. Necesita una cuenta de GitHub y una bifurcación del repositorio de aplicaciones de ejemplo para completar esa implementación.

  1. En un explorador web, use el siguiente vínculo para iniciar la bifurcación de su propia cuenta del repositorio de ejemplo: Azure-Samples/azure-typescript-e2e-apps.
  2. Complete los pasos para bifurcar la muestra solo con la rama principal .

Configuración del entorno de desarrollo

Un entorno de contenedor de desarrollo está disponible con todas las dependencias necesarias para completar todos los ejercicios de este proyecto. Puede ejecutar el contenedor de desarrollo en GitHub Codespaces o localmente mediante Visual Studio Code.

GitHub Codespaces ejecuta un contenedor de desarrollo administrado por GitHub con Visual Studio Code para web como interfaz de usuario. Para el entorno de desarrollo más sencillo, use GitHub Codespaces para tener las herramientas de desarrollo y las dependencias correctas instaladas previamente para completar este módulo de formación.

Importante

Todas las cuentas de GitHub pueden usar Codespaces durante un máximo de 60 horas gratis cada mes con 2 instancias principales. Para obtener más información, consulte Almacenamiento y horas de núcleo incluidas mensualmente en GitHub Codespaces.

  1. En un explorador web, en la bifurcación de GitHub del repositorio de ejemplo, inicia el proceso para crear un nuevo GitHub Codespace en la rama de la main bifurcación seleccionando el botón CÓDIGO .

    Captura de pantalla de GitHub de los botones de Codespaces para un repositorio.

  2. En la pestaña Codespaces , seleccione los puntos suspensivos, ....

    Captura de pantalla de GitHub de la pestaña Codespaces con el control de puntos suspensivos resaltado.

  3. Seleccione + Nuevo con opciones para seleccionar un contenedor de desarrollo de Codespaces específico.

    Captura de pantalla de GitHub de Codespaces Nuevo con el elemento de menú de opciones resaltado.

  4. Selecciona las siguientes opciones y, a continuación, selecciona Crear codespace.

    • Rama: main
    • Configuración del contenedor de desarrollo: Tutorial: Upload file to storage with SAS Token
    • Región: aceptar el valor predeterminado
    • Tipo de máquina: aceptar por defecto

    Captura de pantalla de GitHub de Codespaces Nuevo con menú de opciones con el siguiente contenedor de desarrollo resaltado, Tutorial: Cargar archivo al almacenamiento con token de SAS.

  5. Espere a que se inicie Codespace. Este proceso de inicio puede tardar unos minutos.

  6. Abra un nuevo terminal en el codespace.

    Sugerencia

    Puede usar el menú principal para ir a la opción de menú Terminal y, a continuación, seleccionar la opción Nuevo terminal.

    Captura de pantalla de la opción de menú Codespaces para abrir un nuevo terminal.

  7. Compruebe las versiones de las herramientas que usa en este tutorial.

    node --version
npm --version
func --version

    Este tutorial requiere las siguientes versiones de cada herramienta, que están preinstaladas en su entorno:

    Herramienta Versión
    Node.js. ≥ 18
    npm ≥ 9.5
    Herramientas principales de Azure Functions ≥ 4.5098

  8. Cierre el terminal.

  9. Los pasos restantes de este tutorial tienen lugar en el contexto de este contenedor de desarrollo.

Instalación de dependencias

La aplicación de ejemplo para este tutorial se encuentra en la azure-upload-file-to-storage carpeta. No necesitarás usar ninguna otra carpeta en el proyecto.

  1. En Visual Studio Code, abra un terminal y vaya a la carpeta del proyecto.

    cd azure-upload-file-to-storage

  2. Divida el terminal para que tenga dos terminales, uno para la aplicación cliente y otro para la aplicación API.

  3. En uno de los terminales, ejecute el siguiente comando para instalar las dependencias de la aplicación API y ejecutar la aplicación.

    cd api && npm install

  4. En el otro terminal, ejecute el comando para instalar la aplicación cliente.

    cd app && npm install

Creación de un recurso de almacenamiento con la extensión de Visual Studio

Cree el recurso de Azure Storage para usarlo con la aplicación de ejemplo. El almacenamiento se usa para:

  • Desencadenadores en la aplicación Azure Functions
  • Almacenamiento de blobs (archivos)

  1. Vaya a la extensión de Azure Storage.

  2. Inicie sesión en Azure si es necesario.

  3. Haga clic con el botón derecho en la suscripción y luego seleccione Create Resource....

    Captura de pantalla de Visual Studio Code en Azure Explorer con el menú contextual que muestra el elemento Crear recurso resaltado.

  4. Seleccione Crear cuenta de almacenamiento en la lista.

  5. Siga las indicaciones de la tabla siguiente para comprender cómo crear el recurso de almacenamiento.

    Propiedad Importancia
    Escriba un nombre único global para la nueva aplicación web. Introduzca un valor único como fileuploadstor, para el nombre del recurso de almacenamiento.

    Este nombre único es el nombre del recurso que se usa en la sección siguiente. Utilice un máximo de 24 caracteres alfanuméricos de longitud. Necesita este nombre de cuenta para usarlo más adelante.
    Seleccione una ubicación para los nuevos recursos. Utilice la ubicación recomendada.

  6. Cuando se completa el proceso de creación de la aplicación, aparece una notificación con información sobre el nuevo recurso.

    Captura de pantalla de Visual Studio Code que muestra la barra de actividad de Azure y la notificación de que la cuenta de almacenamiento se creó correctamente.

Configurar CORS de almacenamiento

Dado que el explorador se usa para cargar el archivo, la cuenta de Azure Storage debe configurar CORS para permitir solicitudes entre orígenes. Esta configuración de CORS se usa en este tutorial para simplificar los pasos y no está pensada para indicar las prácticas recomendadas o la seguridad. Obtenga más información sobre CORS para Azure Storage.

  1. Vaya a la extensión de Azure Storage. Haga clic con el botón derecho en el recurso de almacenamiento y seleccione Abrir en el portal.

  2. En la sección Configuración de la cuenta de almacenamiento de Azure Portal, seleccione Uso compartido de recursos (CORS).

  3. Use las siguientes propiedades para establecer CORS para este tutorial.

    • Orígenes permitidos: *
    • Métodos permitidos: Todos excepto el parche
    • Encabezados permitidos: *
    • Encabezados expuestos: *
    • Antigüedad máxima = 86400

  4. Haga clic en Guardar.

Conceder acceso anónimo al almacenamiento

Después de cargar el archivo, el escenario del tutorial requiere acceso público al blob para su visualización. Para simplificar, esta guía permite el acceso anónimo a los archivos cargados.

  1. Para habilitar el acceso público en Azure Portal, seleccione la página Información general de la cuenta de almacenamiento, en la sección Propiedades , seleccione Acceso anónimo de blobs y, a continuación, seleccione Deshabilitado.
  2. En la página Configuración , habilite Permitir el acceso anónimo de Blob.

Creación de un contenedor de carga

Cree un contenedor privado que tenga blobs legibles públicamente.

  1. Mientras aún está en la cuenta de almacenamiento de Azure Portal, en la sección Almacenamiento de datos , seleccione Contenedores.

  2. Seleccione + Contenedor para crear el upload contenedor con la siguiente configuración:

    • Nombre: upload
    • Nivel de acceso público: Blob

  3. Selecciona Crear.

Concédete acceso a Blob Data

Aunque haya creado el recurso, no tiene permiso para ver el contenido del contenedor. Esta autorización está reservada para roles específicos de IAM. Agregue su cuenta para que pueda ver los blobs en los contenedores.

  1. En la cuenta de almacenamiento de Azure Portal, seleccione Control de acceso (IAM).
  2. Seleccione Agregar asignaciones de roles.
  3. Busque y seleccione Colaborador de datos de blob en almacenamiento. Seleccione Siguiente.
  4. Seleccione + Seleccionar miembros.
  5. Busca y selecciona tu cuenta.
  6. Seleccione Revisar y asignar.
  7. Seleccione Contenedores y, a continuación, el contenedor de carga . Debería poder ver que no hay blobs en el contenedor sin errores de autorización.

Obtención de credenciales de recursos de almacenamiento

Las credenciales del recurso de almacenamiento se usan en la aplicación de la API de Azure Functions para conectarse al recurso de almacenamiento.

  1. En Azure Portal, en la sección Seguridad + redes , seleccione Claves de acceso.

  2. Copie la Key clave.

  3. En Visual Studio Code, en la ./workspaces/azure-typescript-e2e-apps/azure-upload-file-to-storage/apicarpeta, cambie el nombre del archivo de local.settings.json.sample a local.settings.json. Git omite el archivo, por lo que no se protege en el control de código fuente.

  4. Actualice la configuración para local.settings.json usar la tabla siguiente.

    Propiedad Importancia Descripción
    Azure_Storage_AccountName Nombre de la cuenta de Azure Storage, por ejemplo: fileuploadstor. Se usa en el código fuente para conectarse al recurso de almacenamiento.
    Azure_Storage_AccountKey Clave de cuenta de Azure Storage Se usa en el código fuente para conectarse al recurso de almacenamiento.
    AzureWebJobsStorage Cadena de conexión de la cuenta de Azure Storage Úselo por el entorno de ejecución de Azure Functions para almacenar el estado y los registros.

Puede parecer que ha introducido las mismas credenciales de cuenta dos veces, una como clave y otra como cadena de conexión. Lo hiciste, pero específicamente para este sencillo tutorial. En términos generales, las aplicaciones de Azure Functions deben tener un recurso de almacenamiento independiente que no se reutilice para otro propósito. Al crear el recurso de Azure Functions más adelante en el tutorial, no será necesario establecer el valor de AzureWebJobsStorage para el recurso en la nube. Deberá establecer los valores de Azure_Storage_AccountName y Azure_Storage_AccountKey que se utilizan en el código fuente.

Ejecución de la aplicación de API

Ejecute la aplicación de Functions para asegurarse de que funciona correctamente antes de implementarla en Azure.

  1. En el terminal de la aplicación de API, ejecute el siguiente comando para iniciar la aplicación de API.

    npm run start

  2. Espere hasta que se inicie la aplicación Azure Functions. Recibirá un aviso de que el puerto de la aplicación Azure Functions, 7071 , ya está disponible. También debería ver las API enumeradas en el terminal de la aplicación de API.

    Functions:

        list: [POST,GET] http://localhost:7071/api/list

        sas: [POST,GET] http://localhost:7071/api/sas

        status: [GET] http://localhost:7071/api/status

  3. Seleccione la pestaña Puertos en el panel inferior, luego haga clic con el botón derecho en el puerto 7071 y seleccione Visibilidad del puerto y, a continuación, seleccione Público.

    Si no expones esta aplicación como pública, obtendrás un error cuando uses la API de la aplicación cliente.

  4. Para probar que la API funciona y se conecta al almacenamiento, en la pestaña Puertos del panel inferior, seleccione el icono de globo terráqueo en el área Dirección local para el puerto 7071. Esto abre un navegador web a la aplicación de funciones.

  5. Agregue la ruta de la API a la barra de direcciones URL: /api/sas?container=upload&file=test.png. No pasa nada porque el archivo aún no está en el contenedor. La API crea el token de SAS en función del lugar en el que desee que se cargue.

  6. La respuesta JSON debe tener un aspecto similar al siguiente:

    {
    "url":"https://YOUR-STORAGE-RESOURCE.blob.core.windows.net/upload/test.png?sv=2023-01-03&spr=https&st=2023-07-26T22%3A15%3A59Z&se=2023-07-26T22%3A25%3A59Z&sr=b&sp=w&sig=j3Yc..."
}

  7. Copie la base de la dirección URL de la API en la barra de direcciones del explorador (no la dirección URL del token de SAS en el objeto JSON) para usarla en el paso siguiente. La URL base es todo lo anterior a /api/sas. Pegará esta dirección URL base en el archivo de variables de entorno de la aplicación cliente en la sección siguiente.

Configurar y ejecutar la aplicación cliente

  1. Cambiar el nombre del archivo ./azure-upload-file-to-storage/app/.env.sample a .env.

  2. Abra el .env archivo y pegue la URL base de la sección anterior como valor para el VITE_API_SERVERarchivo .

    Un ejemplo de un entorno de Codespaces puede tener un aspecto similar al siguiente: VITE_API_SERVER=https://improved-space-fishstick-pgvxvxjpqgrh6qxp-7071.app.github.dev

  3. En el otro terminal dividido, inicie la aplicación cliente con el siguiente comando:

    npm run dev

  4. Espere hasta que el terminal devuelva el siguiente aviso de que la aplicación está disponible en el puerto 5173.

      VITE v4.4.4  ready in 410 ms

  ➜  Local:   https://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

  5. Seleccione la pestaña Puertos en el panel inferior, luego haga clic con el botón derecho en el puerto 5173 y seleccione el icono del globo terráqueo.

  6. Deberías ver la aplicación web.

    Captura de pantalla del navegador web que muestra la aplicación web con el botón Seleccionar archivo disponible.

  7. Interactuar con la aplicación web:

    • Seleccione un archivo de imagen (*.jpg o *.png) de su computadora local para cargarlo.
    • Seleccione el botón Obtener una SAS para solicitar un token de SAS desde la aplicación de API. La respuesta muestra la dirección URL completa que se va a usar para cargar el archivo en el almacenamiento.
    • Seleccione el botón Cargar para enviar el archivo de imagen directamente al almacenamiento.

    Captura de pantalla del navegador web que muestra la aplicación web con el archivo de imagen cargado y una miniatura del archivo mostrado.

  8. La aplicación cliente y la aplicación de API funcionaron juntas correctamente en un entorno de desarrollador en contenedores.

Confirmar cambios en el código

  1. En Visual Studio Code, abra la pestaña Control de código fuente .
  2. Seleccione el + icono para preparar todos los cambios. Estos cambios solo deben incluir nuevos archivos package-lock.json para las app carpetas y api de este tutorial.

Implementación de una aplicación web estática en Azure

La aplicación Azure Functions usa una característica en versión preliminar. Debe desplegarse en el oeste de EE. UU. 2 para funcionar correctamente.

  1. En Visual Studio Code, seleccione el explorador de Azure.

  2. En Azure Explorer, haga clic con el botón derecho en el nombre de la suscripción y, a continuación, seleccione Create Resource....

  3. Seleccione Crear aplicación web estática de la lista.

  4. Siga las indicaciones de la tabla siguiente para comprender cómo crear el recurso de aplicación web estática.

    Propiedad Importancia
    Escriba un nombre único global para la nueva aplicación web. Introduzca un valor único como fileuploadstor, para el nombre del recurso de almacenamiento.

    Este nombre único es el nombre del recurso que se usa en la sección siguiente. Utilice solo caracteres y números, de hasta 24 de longitud. Necesita este nombre de cuenta para usarlo más adelante.
    Seleccione una ubicación para los nuevos recursos. Utilice la ubicación recomendada.

  5. Siga las indicaciones para proporcionar la siguiente información:

    Pronto Entrar
    Seleccione un grupo de recursos para los nuevos recursos. Utilice el grupo de recursos que ha creado para el recurso de almacenamiento.
    Escriba el nombre de la nueva aplicación web estática. Aceptar el nombre predeterminado.
    Seleccionar un SKU En este tutorial, seleccione la SKU gratuita. Si ya tiene un recurso gratuito de aplicación web estática en su suscripción, seleccione el siguiente plan de tarifa.
    Elija build preset para configurar la estructura predeterminada del proyecto. seleccione Personalizada.
    Seleccione la ubicación del código de aplicación azure-upload-file-to-storage/app
    Seleccione la ubicación del código de Azure Functions azure-upload-file-to-storage/api
    Introduzca la ruta de acceso de la salida de la compilación... dist

    value es la ruta de acceso desde la aplicación hasta los archivos estáticos (generados).
    Seleccione una ubicación para los nuevos recursos. Seleccione una región cercana.

  6. Cuando se completa el proceso, aparece una ventana emergente de notificación. Seleccione Ver/Editar flujo de trabajo.

  7. La bifurcación remota tiene un nuevo archivo de flujo de trabajo para implementarlo en aplicaciones web estáticas. Tire de ese archivo a su entorno con el siguiente comando en el terminal:

    git pull origin main

  8. Abra el archivo de flujo de trabajo ubicado en /.github/workflows/.

  9. Compruebe que la sección del flujo de trabajo específica de la aplicación web estática de este tutorial debe tener el siguiente aspecto:

    ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
app_location: "/azure-upload-file-to-storage/app" # App source code path
api_location: "/azure-upload-file-to-storage/api" # Api source code path - optional
output_location: "dist" # Built app content directory - optional
###### End of Repository/Build Configurations ######

  10. Vaya a la bifurcación de GitHub del ejemplo https://github.com/<YOUR-ACCOUNT>/azure-typescript-e2e-apps/actions para comprobar que la acción de compilación e implementación, denominada Azure Static Web Apps CI/CD, se completó correctamente. Esta acción puede tardar unos minutos en completarse.

  11. Vaya a Azure Portal de la aplicación y vea la sección API de Configuración. El nombre del recurso de back-end en el entorno (managed) de producción indica que las API se han implementado correctamente.

  12. Seleccione (administrado) para ver la lista de API cargadas en la aplicación:

    • lista
    • Sas
    • estado

  13. Vaya a la página Información general para buscar la dirección URL de la aplicación implementada.

  14. La implementación de la aplicación se ha completado.

Configurar la API con el nombre y la clave del recurso de almacenamiento

La aplicación necesita el nombre y la clave del recurso de Azure Storage para que la API funcione correctamente. Cuando se implementa en Azure Static Web Apps, la aplicación cliente y la API se hospedan desde el mismo dominio, lo que elimina la necesidad de establecer la variable de entorno de la aplicación cliente VITE_API_SERVER.

  1. Todavía en el Explorador de Azure, haga clic con el botón derecho en el recurso Aplicación web estática y seleccione Abrir en el portal.

  2. Seleccione Configuración en la sección Configuración .

  3. Agregue la configuración de la aplicación mediante la siguiente tabla.

    Propiedad Importancia Descripción
    Azure_Storage_AccountName Nombre de la cuenta de Azure Storage, por ejemplo: fileuploadstor. Se usa en el código fuente para conectarse al recurso de almacenamiento.
    Azure_Storage_AccountKey Clave de cuenta de Azure Storage Se usa en el código fuente para conectarse al recurso de almacenamiento.

  4. Seleccione Guardar en la página Configuración para guardar ambas configuraciones.

Uso de la aplicación web estática implementada en Azure

Compruebe que la implementación y la configuración se han realizado correctamente mediante el sitio web.

  1. En Visual Studio Code, haga clic con el botón derecho en la aplicación web estática desde el explorador de Azure y seleccione Examinar sitio.
  2. En la nueva ventana del navegador web, seleccione Elegir archivo y, a continuación, seleccione un archivo de imagen (*.png o *.jpg) para cargarlo.
  3. Seleccione Obtener token sas. Esta acción pasa el nombre de archivo a la API y recibe la dirección URL del token de SAS necesaria para cargar el archivo.
  4. Seleccione Cargar archivo para usar la dirección URL del token de SAS para cargar el archivo. El navegador muestra la miniatura y la URL del archivo cargado.

Limpieza de recursos

En Visual Studio Code, use el explorador de Azure para grupos de recursos. Haga clic con el botón derecho en el grupo de recursos y, a continuación, seleccione Eliminar.

Esta acción elimina todos los recursos del grupo, incluidos los recursos de almacenamiento y de la aplicación web estática.

Solución de problemas

Notifique problemas con este ejemplo en el repositorio de GitHub. Incluya lo siguiente con el problema:

  • Dirección URL del artículo
  • El paso o contexto dentro del artículo que fue problemático
  • Su entorno de desarrollo

Código de ejemplo

Contenido relacionado