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

Use una aplicación web estática para cargar un archivo en un blob de Azure Storage mediante un paquete npm de azure Storage @azure/storage-blob con un token de SAS de Azure Storage.

Requisitos previos

Arquitectura de la aplicación

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

  • Azure Static Web Apps para la aplicación cliente generada estáticamente. El recurso también proporciona la API administrada de Azure Functions. Administrado significa que el recurso Static Web Apps administra el recurso de API para su propio uso.
  • Azure Storage para Blob Storage.

Diagram showing how a customer interacts from their computer to use the website to upload a file to Azure Storage directly.

Paso Description
1 El cliente se conecta al sitio web generado estáticamente. El sitio web se hospeda en Azure Static Web Apps.
2 El cliente usa ese sitio web para seleccionar un archivo que se va a cargar. En este tutorial, el marco de 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 de archivo 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 la 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 usan los siguientes entornos:

  • Desarrollo local con GitHub Codespaces o Visual Studio Code.
  • Compile e implemente con Acciones de GitHub.

1. 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 vínculo siguiente para comenzar la bifurcación para su propia cuenta del repositorio de ejemplo: Azure-Samples/azure-typescript-e2e-apps.
  2. Complete los pasos para bifurcar el ejemplo solo con la rama principal .

2. 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 la 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, inicie el proceso para crear un nuevo gitHub Codespace en la main rama de la bifurcación seleccionando el botón CÓDIGO .

    GitHub screenshot of Code Spaces buttons for a repository.

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

    GitHub screenshot of Code Spaces tab with ellipsis control highlighted.

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

    GitHub screenshot of Codespaces New with options menu item highlighted.

  4. Seleccione las opciones siguientes y, a continuación, seleccione Crear espacio de código.

    • 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 el valor predeterminado

    GitHub screenshot of Codespaces New with options menu with the following dev container highlighted, Tutorial: Upload file to storage with SAS Token.

  5. Espere a que se inicie Codespace. Este proceso de startup 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.

    Screenshot of the codespaces menu option to open a new 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
    Azure Functions Core Tools ≥ 4.5098
  8. Cierre el terminal.

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

3. Instalación de dependencias

La aplicación de ejemplo de este tutorial se encuentra en la azure-upload-file-to-storage carpeta . No tendrá que usar ninguna otra carpeta del 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 de API.

  3. En uno de los terminales, ejecute el siguiente comando para instalar las dependencias de la aplicación de 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
    

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

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

  • Desencadenadores en la aplicación de 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, a continuación, seleccione Create Resource....

    Screenshot of Visual Studio Code in the Azure Explorer with the right-click menu showing the Create Resource item highlighted.

  4. Seleccione Crear cuenta de almacenamiento en la lista.

  5. Siga las indicaciones que se indican en la tabla siguiente para comprender cómo crear el recurso de Storage.

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

    Este nombre único es el nombre de recurso que se utiliza en la sección siguiente. Use solo caracteres y números, de hasta 24 caracteres de longitud. Necesitará este nombre de cuenta para utilizarlo más adelante.
    Seleccione una ubicación para los nuevos recursos. Use la ubicación recomendada.
  6. Una vez finalizado el proceso de creación de la aplicación, aparece una notificación con información sobre el nuevo recurso.

    Screenshot of Visual Studio Code showing the Azure Activity Bar and the notification that the storage account was successfully created.

5. Configuración de 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.

  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 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: Todo excepto revisión
    • Encabezados permitidos: *
    • Encabezados expuestos: *
    • Edad máxima: 86400

    Esta configuración se usa para este tutorial para simplificar los pasos y no está pensado para indicar procedimientos recomendados o seguridad. Más información sobre CORS para Azure Storage.

  4. Seleccione Guardar.

6. Concesión de acceso anónimo al almacenamiento

La carga de archivos se protege desde el cliente cuando se crea un token de SAS limitado por el tiempo y el permiso limitado. Sin embargo, una vez cargado el archivo, en este escenario de tutorial, quiere que cualquiera lo vea. Para ello, debe cambiar el permiso de almacenamiento para que sea accesible públicamente.

Aunque la cuenta sea accesible públicamente, cada contenedor y cada blob puede tener acceso privado. Un método más seguro pero demasiado complicado para este tutorial es cargar en una cuenta de almacenamiento con el token de SAS y, a continuación, mover el blob a otra cuenta de almacenamiento con acceso público.

  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 blobs.

7. Creación de un contenedor de carga

  1. Mientras sigue 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. Seleccione Crear.

8. Conceda acceso a los datos de blobs

Mientras creó el recurso, no tiene permiso para ver el contenido del contenedor. Está reservado para roles de IAM específicos. Agregue su cuenta para que pueda ver los blobs en los contenedores.

  1. Aún en la cuenta de almacenamiento de Azure Portal, seleccione Control de acceso (IAM) .
  2. Seleccione Agregar asignación de roles.
  3. Busque y seleccione Colaborador de datos de Storage Blob. Seleccione Siguiente.
  4. Seleccione + Seleccionar integrantes.
  5. Busque y seleccione su cuenta.
  6. Seleccione Revisar y asignar.
  7. Seleccione Contenedores y, a continuación, cargue el contenedor. Debería poder ver que no hay blobs en el contenedor sin errores de autorización.

9. Obtención de credenciales de recursos de almacenamiento

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

  1. Mientras sigue en Azure Portal, en la sección Seguridad y redes , seleccione Claves de acceso.

  2. Recuerde que los archivos de API se encuentran en ./workspaces/azure-typescript-e2e-apps/azure-upload-file-to-storage/api.

  3. En la carpeta DE API, cambie el nombre del archivo de local.settings.json.sample a local.settings.json. Git omite el archivo, por lo que no se comprobará en el control de código fuente.

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

    Propiedad Valor 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 Storage.
    Azure_Storage_AccountKey Clave de cuenta de Azure Storage Se usa en el código fuente para conectarse al recurso de Storage.
    AzureWebJobsStorage Cadena de conexión de la cuenta de Azure Storage Use el entorno de ejecución de Azure Functions para almacenar el estado y los registros.

Puede parecer que ha escrito las mismas credenciales de cuenta dos veces, una vez como una clave y una vez como una cadena de conexión. Lo hizo, pero específicamente para este sencillo tutorial. Por lo general, las aplicaciones de Azure Functions deben tener un recurso de Almacenamiento independiente que no se reutiliza para otro propósito. Cuando cree el recurso de Azure Functions más adelante en el tutorial, no tendrá que establecer el valor azureWebJobsStorage para el recurso en la nube. Solo tendrá que establecer los valores de Azure_Storage_AccountName y Azure_Storage_AccountKey que se usan en el código fuente.

10. 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 de Azure Functions. Verá que el puerto de la aplicación de Azure Functions, 7071 ya está disponible. También debería ver las API que aparecen 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 y 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 expone esta aplicación como pública, recibirá un error al usar 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 en el área Dirección local del puerto 7071. Se abre un explorador web en la aplicación de funciones.

  5. Agregue la ruta de API a la barra de direcciones URL: /api/sas?container=upload&file=test.png. Está bien que el archivo aún no esté en el contenedor. La API crea el token de SAS en función de dónde desea 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 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 dirección URL base es todo antes de /api/sas.

11. 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 dirección URL base de la sección anterior como valor de VITE_API_SERVER.

    Un ejemplo de un entorno de Codespaces puede tener un aspecto similar al de 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 del panel inferior y haga clic con el botón derecho en el puerto 5173 y seleccione el icono de globo.

  6. Debería ver la aplicación web sencilla.

    Screenshot of web browser showing web app with Select File button available.

  7. Interactuar con la aplicación web:

    • Seleccione un archivo de imagen (*.jpg o *.png) en el equipo 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 usará para cargar el archivo en Storage.
    • Seleccione el botón Cargar para enviar el archivo de imagen directamente a Storage.

    Screenshot of web browser showing web app with the image file uploaded and a thumbnail of the file displayed.

  8. La aplicación cliente y la aplicación de API trabajaron correctamente en un entorno para desarrolladores en contenedores.

12. 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 almacenar provisionalmente todos los cambios. Estos cambios solo deben incluir nuevos archivos package-lock.json para las app carpetas y api de este tutorial.

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

La aplicación de Azure Functions usa una característica en versión preliminar; debe implementarse en Oeste de EE. UU. 2 para funcionar correctamente.

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

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

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

  4. Siga las indicaciones con la tabla siguiente para comprender cómo crear el recurso Static Web App.

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

    Este nombre único es el nombre de recurso que se utiliza en la sección siguiente. Use solo caracteres y números, de hasta 24 caracteres de longitud. Necesitará este nombre de cuenta para utilizarlo más adelante.
    Seleccione una ubicación para los nuevos recursos. Use la ubicación recomendada.
  5. Siga los mensajes para proporcionar la siguiente información:

    Prompt Entrar
    Seleccione un grupo de recursos para los nuevos recursos. Use el grupo de recursos que creó para el recurso de almacenamiento.
    Escriba el nombre de la nueva aplicación web estática. Aceptar el nombre predeterminado.
    Selección de una SKU En este tutorial, seleccione la SKU gratuita. Si ya tiene un recurso de Aplicación web estática gratis en la suscripción, seleccione el siguiente plan de tarifa.
    Elija el valor preestablecido de compilación para configurar la estructura predeterminada del proyecto. seleccione Personalizada.
    Seleccione la ubicación del código de la aplicación. azure-upload-file-to-storage/app
    Seleccione la ubicación del código de Azure Functions. azure-upload-file-to-storage/api
    Escriba la ruta de acceso de la salida de compilación... dist

    Esta 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. Una vez completado el proceso, aparecerá un elemento emergente de notificación. Seleccione Ver/Editar flujo de trabajo.

  7. La bifurcación remota tiene un nuevo archivo de flujo de trabajo para la implementación en Static Web Apps. Extraiga ese archivo hasta el 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ífico de la aplicación web estática de este tutorial debe ser similar a la siguiente:

    ###### 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 la acción de compilación e implementación, denominada Azure Static Web Apps CI/CD, completada correctamente. Esta operación puede tardar algunos minutos en completarse.

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

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

    • list
    • Sas
    • status
  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.

14. Configuración de la API con el nombre y la clave del recurso de Storage

La aplicación necesita el nombre y la clave del recurso de Azure Storage antes de que la API funcione correctamente.

  1. Aún 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 tabla siguiente.

    Propiedad Valor 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 Storage.
    Azure_Storage_AccountKey Clave de cuenta de Azure Storage Se usa en el código fuente para conectarse al recurso de Storage.
  4. Seleccione Guardar en la página Configuración para guardar ambas opciones.

Nota:

No es necesario establecer la variable env de la aplicación cliente VITE_API_SERVER porque la aplicación cliente y la API se hospedan desde el mismo dominio.

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

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

  1. En Visual Studio Code, haga clic con el botón derecho en la aplicación web estática en el explorador de Azure y seleccione Examinar sitio.
  2. En la nueva ventana del explorador web, seleccione Elegir archivo y, a continuación, seleccione un archivo de imagen (*.png o *.jpg) para cargarlo.
  3. Seleccione Obtener token de 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 explorador muestra la miniatura y la dirección URL del archivo cargado.

16. 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 seleccione Eliminar.

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

Solución de problemas

Informe de problemas con este ejemplo en el repositorio de GitHub que se indica a continuación. Incluya lo siguiente con el problema:

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

Código de ejemplo

Si desea continuar con esta aplicación, obtenga información sobre cómo implementar la aplicación en Azure para su hospedaje con una de las siguientes opciones: