Tutorial de JavaScript: Carga y análisis de un archivo con Azure Functions y Blob Storage

  • Artículo

En este tutorial, aprenderá a cargar una imagen en Azure Blob Storage y procesarla mediante Azure Functions, Computer Vision y Cosmos DB. También aprenderá a implementar desencadenadores y enlaces de Azure Functions como parte de este proceso. Juntos, estos servicios analizan una imagen cargada que contiene texto, extraen el texto de ella y, a continuación, almacenan el texto en una fila de base de datos para realizar análisis posteriores u otros fines.

Azure Blob Storage es la solución de almacenamiento de objetos de Microsoft para la nube y es escalable de forma masiva. Blob Storage está diseñado para almacenar imágenes y documentos, transmitir archivos multimedia, administrar datos de copia de seguridad y archivo, y mucho más. Puede obtener más información sobre Blob Storage en la página de información general.

Advertencia

En este tutorial se usa el almacenamiento accesible públicamente para simplificar el proceso para finalizar este tutorial. El acceso público anónimo presenta un riesgo de seguridad. Obtener información sobre cómo corregir este riesgo.

Azure Cosmos DB es una base de datos NoSQL y relacional totalmente administrada para el desarrollo de aplicaciones modernas.

Azure Functions es una solución de equipo sin servidor que permite escribir y ejecutar pequeños bloques de código como funciones controladas por eventos altamente escalables y sin servidor. Puede obtener más información sobre Azure Functions en la página de información general.

En este tutorial, aprenderá a:

  • Upload imágenes y archivos en Blob Storage
  • Uso de un desencadenador de eventos de Azure Functions para procesar los datos cargados en Blob Storage
  • Usar servicios de Azure AI para analizar una imagen
  • Escritura de datos en Cosmos DB mediante enlaces de salida de Azure Function

Diagrama de arquitectura en el que se muestra un blob de imágenes que se agrega a Blob Storage; a continuación, el blob es analizado por una función de Azure y el análisis se inserta en Cosmos DB.

Requisitos previos

Creación de una cuenta de almacenamiento y un contenedor

El primer paso es crear la cuenta de almacenamiento que contendrá los datos de blobs cargados, que en este escenario serán imágenes que contienen texto. Una cuenta de almacenamiento ofrece varios servicios diferentes, pero en este tutorial solo se usa Blob Storage.

  1. En Visual Studio Code, seleccione Ctrl + Mayús + P para abrir la paleta de comandos.

  2. Busque Azure Storage: Crear cuenta de Storage (avanzadas).

  3. Use la tabla siguiente para crear el recurso de Storage.

    Configuración Valor
    Nombre Escriba msdocsstoragefunction o algo similar.
    Grupo de recursos Cree el grupo de recursos msdocs-storage-function que ha creado antes.
    Hospedaje web estático No.

  4. En Visual Studio Code, presione Mayús + Alt + A para abrir el explorador de Azure.

  5. Expanda la sección Storage, expanda el nodo de la suscripción y espere a que se cree el recurso.

Creación del contenedor en Visual Studio Code

  1. Todavía en Azure Explorer con el nuevo recurso de Storage encontrado, expanda el recurso para ver los nodos.
  2. Haga clic con el botón derecho en Contenedores de blob y seleccione Crear contenedor de blobs.
  3. Escriba el nombre images. Esto crea un contenedor privado.

Cambio del contenedor privado a público en Azure Portal

Este procedimiento espera un contenedor público. Para cambiar esa configuración, realice el cambio en Azure Portal.

  1. Haga clic con el botón derecho en el recurso de Storage en Azure Explorer y seleccione Abrir en el portal.
  2. En la sección Almacenamiento de datos, seleccione Contenedores.
  3. Busque el contenedor, images, y seleccione ... (puntos suspensivos) al final de la línea.
  4. Seleccione Cambiar nivel de acceso.
  5. Seleccione Blob (acceso de lectura anónimo solo para blobs) y después Aceptar.
  6. Vuelva a Visual Studio Code.

Recuperación de la cadena de conexión con Visual Studio Code

  1. En Visual Studio Code, presione Mayús + Alt + A para abrir el explorador de Azure.
  2. Haga clic con el botón derecho en el recurso de almacenamiento y seleccione Copiar cadena de conexión.
  3. Pegue esto en algún lugar para usarlo más adelante.
  4. Asimismo, anote el nombre de la cuenta de almacenamiento msdocsstoragefunction que se usará más adelante.

Creación del servicio Visión de Azure AI

A continuación, cree la cuenta de servicio de Visión de Azure AI que procesará los archivos cargados. Vision forma parte de los servicios de Azure AI y ofrece una variedad de características para extraer datos de imágenes. Puede conocer más sobre Visión de Azure AI en la página de información general.

  1. En la barra de búsqueda en la parte superior del portal, busque Equipo y seleccione el resultado etiquetado como Computer Vision.

  2. En la página Computer Vision, seleccione + Crear.

  3. En la página Crear Computer Vision, escriba los siguientes valores:

    • Suscripción: elija la suscripción preferida.
    • Grupo de recursos: use el msdocs-storage-function grupo de recursos creado anteriormente.
    • Región: Seleccione la región más cercana a usted.
    • Nombre: escriba en un nombre de msdocscomputervision.
    • Plan de tarifa: elija Gratis si está disponible; de lo contrario, elija Estándar S1.
    • Active la casilla Aviso de IA responsable si acepta los términos.

    Captura de pantalla que muestra cómo crear un servicio de Computer Vision.

  4. En la parte inferior, seleccione Revisar y crear. Azure tarda un momento en validar la información que escribió. Una vez validada la configuración, elija Crear y Azure comenzará a aprovisionar el servicio de Computer Vision, lo que puede tardar un momento.

  5. Una vez finalizada la operación, seleccione Ir al Recurso.

Recuperación de las claves de Computer Vision

A continuación, es necesario encontrar la clave secreta y la dirección URL del punto de conexión del servicio Computer Vision que se va a usar en nuestra aplicación de funciones de Azure.

  1. En la página de información general de Computer Vision, seleccione Claves y punto de conexión.

  2. En la página Claves y punto de conexión, copie el valor clave 1 y los valores de punto de conexión y péguelos en algún lugar para usarlos más adelante. El punto de conexión debe tener el formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/

Una captura de pantalla que muestra cómo recuperar las claves y el punto de conexión de URL de un servicio de Computer Vision.

Crear una cuenta de servicio de Cosmos DB

Cree la cuenta de servicio de Cosmos DB para almacenar el análisis de archivos. Azure Cosmos DB es una base de datos NoSQL y relacional totalmente administrada para el desarrollo de aplicaciones modernas. Puede obtener más información sobre Cosmos DB y sus API de soporte técnico para diferentes bases de datos del sector.

Aunque en este tutorial se especifica una API al crear el recurso, los enlaces de función de Azure para Cosmos DB se configuran de la misma manera para todas las API de Cosmos DB.

  1. En la barra de búsqueda de la parte superior del portal, busque Azure Cosmos DB y seleccione el resultado.

  2. En la página Azure Cosmos DB, seleccione + Crear. Seleccione Azure Cosmos DB for NoSQL en la lista de opciones de API.

  3. En la página Crear Cosmos DB, escriba los valores siguientes:

    • Suscripción: elija la suscripción preferida.
    • Grupo de recursos: use el msdocs-storage-function grupo de recursos creado anteriormente.
    • Región: seleccione la misma región que la del grupo de recursos.
    • Nombre: escriba en un nombre de msdocscosmosdb.
    • Plan de tarifa: elija Gratis si está disponible; de lo contrario, elija Estándar S1.

  4. En la parte inferior, seleccione Revisar y crear. Azure tardará un momento en validar la información que escribió. Una vez validada la configuración, elija Crear y Azure comenzará a aprovisionar el servicio de Computer Vision, lo que puede tardar un momento.

  5. Una vez finalizada la operación, seleccione Ir al Recurso.

  6. Seleccione Explorador de datos y luego Nuevo contenedor.

  7. Cree una nueva base de datos y un contenedor con esta configuración:

    • Cree un nuevo id. de base de datos: StorageTutorial.
    • Escriba el nuevo id. de contenedor: analysis.
    • Escriba la nueva clave de partición: /type.

  8. Deje el resto de la configuración predeterminada como está y seleccione Aceptar.

Obtención de la cadena de conexión de Cosmos DB

Obtenga la cadena de conexión de la cuenta de servicio de Cosmos DB que se usará en nuestra aplicación de funciones de Azure.

  1. En la página información general de Cosmos DB, seleccione Claves.

  2. En la página Claves, copie la cadena de conexión principal para usarla después.

Descarga y configuración del proyecto de ejemplo

El código de la función de Azure que se usa en este tutorial se puede encontrar en este repositorio de GitHub en el subdirectorio JavaScript-v4. También puede clonar el proyecto mediante el comando siguiente.

git clone https://github.com/Azure-Samples/msdocs-storage-bind-function-service.git \
cd msdocs-storage-bind-function-service/javascript-v4 \
code .

En el proyecto de ejemplo se realizan las tareas siguientes:

  • Recupera variables de entorno para conectarse a la cuenta de almacenamiento, Computer Vision y al servicio Cosmos DB
  • Acepta el archivo cargado como un parámetro de blob.
  • Analiza el blob mediante el servicio Computer Vision.
  • Inserta el texto de imagen analizado, como un objeto JSON, en Cosmos DB mediante enlaces de salida

Una vez que haya descargado y abierto el proyecto, hay algunos conceptos esenciales que debe comprender:

Concepto Propósito
Función La función de Azure se define mediante el código de función y los enlaces. Se encuentran en ./src/functions/process-blobs.js.
Desencadenadores y enlaces Los desencadenadores y enlaces indican los datos que se esperan dentro o fuera de la función y el servicio que va a enviar o recibir esos datos.

Los desencadenadores y enlaces usados en este tutorial para acelerar el proceso de desarrollo al evitar tener que escribir código para conectarse a los servicios.

Desencadenador de blobs de almacenamiento de entrada

El código, que especifica que la función se desencadena cuando se carga un blob en el contenedor images. La función se desencadena en cualquier nombre de blob, incluidas las carpetas jerárquicas.


// ...preceding code removed for brevity

app.storageBlob('process-blob-image', { 
    path: 'images/{name}',                // Storage container name: images, Blob name: {name}
    connection: 'StorageConnection',      // Storage account connection string
    handler: async (blob, context) => {

// ... function code removed for brevity
  • app.storageBlob: el desencadenador de entrada de blob de almacenamiento se usa para enlazar la función al evento de carga en Blob Storage. El desencadenador tiene dos parámetros obligatorios:
    • path: la ruta en la que el desencadenador inspecciona los eventos. La ruta incluye el nombre del contenedor (images) y la sustitución de variables para el nombre del blob. Este nombre de blob se recupera de la propiedad name.
    • {name}: nombre del blob cargado. El uso de blob es el nombre de parámetro del blob que entra en la función. No cambie el valor blob.
    • connection: cadena de conexión de la cuenta de almacenamiento. El valor StorageConnection coincide con el nombre del archivo local.settings.json al desarrollar localmente.

Desencadenador de salida de Cosmos DB

Cuando finaliza la función, la función usa el objeto devuelto como los datos que se van a insertar en Cosmos DB.


// ... function definition ojbect
app.storageBlob('process-blob-image', { 
    
        // removed for brevity    
        
        // Data to insert into Cosmos DB
        const id = uuidv4().toString();
        const analysis = await analyzeImage(blobUrl);
        
        // `type` is the partition key 
        const dataToInsertToDatabase = {
                id,
                type: 'image',
                blobUrl,
                blobSize: blob.length,
                analysis,
                trigger: context.triggerMetadata
            }

        return dataToInsertToDatabase;
    }),

    // Output binding for Cosmos DB
    return: output.cosmosDB({
        connection: 'CosmosDBConnection',
        databaseName:'StorageTutorial',
        containerName:'analysis'
    })
});

Para el contenedor de este artículo, las propiedades necesarias son las siguientes:

  • id: el identificador necesario para que Cosmos DB cree una nueva fila.

  • /type: se creó la clave de partición especificada con el contenedor.

  • output.cosmosDB: el desencadenador de salida de Cosmos DB se usa para insertar el resultado de la función en Cosmos DB.

    • connection: cadena de conexión de la cuenta de almacenamiento. El valor StorageConnection coincide con el nombre en el archivo local.settings.json.
    • databaseName: base de datos de Cosmos DB a la que se va a conectar.
    • containerName: nombre de la tabla para escribir el valor de texto de imagen analizado devuelto por la función. La tabla ya debe existir.

Código de función de Azure

A continuación se muestra el código de función completo.

const { app, input, output } = require('@azure/functions');
const { v4: uuidv4 } = require('uuid');
const { ApiKeyCredentials } = require('@azure/ms-rest-js');
const { ComputerVisionClient } = require('@azure/cognitiveservices-computervision');
const sleep = require('util').promisify(setTimeout);

const STATUS_SUCCEEDED = "succeeded";
const STATUS_FAILED = "failed"

const imageExtensions = ["jpg", "jpeg", "png", "bmp", "gif", "tiff"];

async function analyzeImage(url) {

    try {

        const computerVision_ResourceKey = process.env.ComputerVisionKey;
        const computerVision_Endpoint = process.env.ComputerVisionEndPoint;

        const computerVisionClient = new ComputerVisionClient(
            new ApiKeyCredentials({ inHeader: { 'Ocp-Apim-Subscription-Key': computerVision_ResourceKey } }), computerVision_Endpoint);

        const contents = await computerVisionClient.analyzeImage(url, {
            visualFeatures: ['ImageType', 'Categories', 'Tags', 'Description', 'Objects', 'Adult', 'Faces']
        });

        return contents;

    } catch (err) {
        console.log(err);
    }
}
app.storageBlob('process-blob-image', { 
    path: 'images/{name}',
    connection: 'StorageConnection',
    handler: async (blob, context) => {

        context.log(`Storage blob 'process-blob-image' url:${context.triggerMetadata.uri}, size:${blob.length} bytes`);

        const blobUrl = context.triggerMetadata.uri;
        const extension = blobUrl.split('.').pop();

        if(!blobUrl) {
            // url is empty
            return;
        } else if (!extension || !imageExtensions.includes(extension.toLowerCase())){
            // not processing file because it isn't a valid and accepted image extension
            return;
        } else {
            //url is image
            const id = uuidv4().toString();
            const analysis = await analyzeImage(blobUrl);
            
            // `type` is the partition key 
            const dataToInsertToDatabase = {
                    id,
                    type: 'image',
                    blobUrl,
                    blobSize: blob.length,
                    ...analysis,
                    trigger: context.triggerMetadata
                }

            return dataToInsertToDatabase;
        }

        
    },
    return: output.cosmosDB({
        connection: 'CosmosDBConnection',
        databaseName:'StorageTutorial',
        containerName:'analysis'
    })
});

Este código también recupera valores de configuración esenciales de variables de entorno, como la cadena de conexión de Blob Storage y la clave de Computer Vision. Estas variables de entorno se agregan al entorno de Azure Functions después de implementarlo.

La función predeterminada también utiliza un segundo método denominado AnalyzeImage. Este código usa el punto de conexión URL y la clave de la de Computer Vision para realizar una solicitud a Computer Vision para procesar la imagen. La solicitud devuelve todo el texto detectado en la imagen. Este texto se escribe en Cosmos DB, mediante el enlace de salida.

Configuración de valores locales

Para ejecutar el proyecto localmente, escriba las variables de entorno en el archivo ./local.settings.json. Rellene los valores de marcador de posición con los valores que ha guardado antes al crear los recursos de Azure.

Aunque el código de Azure Functions se ejecuta localmente, se conecta a los servicios basados en la nube para Storage, en lugar de usar emuladores locales.

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AzureWebJobsStorage": "",
    "StorageConnection": "STORAGE-CONNECTION-STRING",
    "StorageAccountName": "STORAGE-ACCOUNT-NAME",
    "StorageContainerName": "STORAGE-CONTAINER-NAME",
    "ComputerVisionKey": "COMPUTER-VISION-KEY",
    "ComputerVisionEndPoint":  "COMPUTER-VISION-ENDPOINT",
    "CosmosDBConnection": "COSMOS-DB-CONNECTION-STRING"
  }
}

Creación de la aplicación de Azure Functions

Ya está listo para implementar la aplicación en Azure mediante una extensión de Visual Studio Code.

  1. En Visual Studio Code, presione Mayús + Alt + A para abrir el explorador de Azure.

  2. En la sección Funciones, busque y haga clic con el botón derecho en la suscripción y seleccione Crear aplicación de funciones en Azure (avanzado).

  3. Use la tabla siguiente para crear el recurso de Functions.

    Configuración Valor
    Nombre Escriba msdocsprocessimage o algo similar.
    Pila en tiempo de ejecución Seleccione una versión Node.js LTS.
    Modelo de programación Seleccione v4.
    SISTEMA OPERATIVO Seleccione Linux.
    Grupo de recursos Seleccione el grupo de recursos msdocs-storage-function que ha creado antes.
    Ubicación seleccione la misma región que la del grupo de recursos.
    Tipo de plan Seleccione Consumo.
    Almacenamiento de Azure Seleccione la cuenta de almacenamiento creada anteriormente.
    Application Insights Omítalo por ahora.

  4. Azure aprovisiona los recursos solicitados, lo que tardará unos minutos en completarse.

Implementación de la aplicación de Azure Functions

  1. Cuando finalice el proceso de creación de recursos anterior, haga clic con el botón derecho en el nuevo recurso de la sección Funciones del Explorador de Azure y seleccione Implementar en aplicación de funciones.
  2. Si se le pregunta ¿Está seguro de que quiere implementar...?, seleccione Implementar.
  3. Cuando se complete el proceso, aparecerá una notificación con una opción que incluye Cargar configuración. Seleccione esa opción. Esto copia los valores del archivo local.settings.json en la aplicación de funciones de Azure. Si la notificación ha desaparecido antes de poder seleccionarla, continúe con la sección siguiente.

Adición de la configuración de la aplicación para Storage y Computer Vision

Si ha seleccionado Cargar configuración en la notificación, omita esta sección.

La función de Azure se ha implementado correctamente, pero todavía no se puede conectar a la cuenta de Storage y los servicios de Computer Vision. Primero se deben agregar las claves correctas y las cadenas de conexión a los valores de configuración de la aplicación Azure Functions.

  1. Busque el recurso en la sección Funciones del Explorador de Azure, haga clic con el botón derecho en Configuración de la aplicación y seleccione Agregar nueva configuración.

  2. Escriba una nueva configuración de aplicación para los secretos siguientes. Copie y pegue los valores de secreto del proyecto local en el archivo local.settings.json.

    Configuración
    StorageConnection
    StorageAccountName
    StorageContainerName
    ComputerVisionKey
    ComputerVisionEndPoint
    CosmosDBConnection

Todas las variables de entorno necesarias para conectar nuestra función de Azure a diferentes servicios están ahora en vigor.

Carga de una imagen en Blob Storage

Ya está listo para probar la aplicación. Puede cargar un blob en el contenedor y, a continuación, comprobar que el texto de la imagen se guardó en Cosmos DB.

  1. En el explorador de Azure de Visual Studio Code, busque y expanda el recurso de Storage en la sección Storage.
  2. Expanda Contenedores de blobs, haga clic con el botón derecho en el nombre del contenedor y, después, imagesseleccione Cargar archivos.
  3. Puede encontrar algunas imágenes de ejemplo incluidas en la carpeta images en la raíz del proyecto de ejemplo descargable, o puede usar una de sus propias imágenes.
  4. Para el directorio Destino, acepte el valor predeterminado, /.
  5. Espere hasta que los archivos se carguen y aparezcan en el contenedor.

Visualización del análisis de texto de la imagen

A continuación, puede comprobar que la carga desencadenó la función de Azure y que el texto de la imagen se ha analizado y guardado en Cosmos DB correctamente.

  1. En Visual Studio Code, en Azure Explorer, en el nodo de Azure Cosmos DB, seleccione el recurso y expándalo para buscar la base de datos, StorageTutorial.

  2. Expanda el nodo de la base de datos.

  3. Ahora debería haber disponible un contenedor de análisis. Seleccione el nodo Documentos del contenedor para obtener una vista previa de los datos que contiene. Debería ver una entrada para el texto de la imagen procesada de un archivo cargado.

    {
    "id": "3cf7d6f0-a362-421e-9482-3020d7d1e689",
    "type": "image",
    "blobUrl": "https://msdocsstoragefunction.blob.core.windows.net/images/presentation.png",
    "blobSize": 1383614,
    "analysis": {  ... details removed for brevity ...
        "categories": [],
        "adult": {},
        "imageType": {},
        "tags": [],
        "description": {},
        "faces": [],
        "objects": [],
        "requestId": "eead3d60-9905-499c-99c5-23d084d9cac2",
        "metadata": {},
        "modelVersion": "2021-05-01"
    },
    "trigger": { 
        "blobTrigger": "images/presentation.png",
        "uri": "https://msdocsstorageaccount.blob.core.windows.net/images/presentation.png",
        "properties": {
            "lastModified": "2023-07-07T15:32:38+00:00",
            "createdOn": "2023-07-07T15:32:38+00:00",
            "metadata": {},
            ... removed for brevity ...
            "contentLength": 1383614,
            "contentType": "image/png",
            "accessTier": "Hot",
            "accessTierInferred": true,
        },
        "metadata": {},
        "name": "presentation.png"
    },
    "_rid": "YN1FAKcZojEFAAAAAAAAAA==",
    "_self": "dbs/YN1FAA==/colls/YN1FAKcZojE=/docs/YN1FAKcZojEFAAAAAAAAAA==/",
    "_etag": "\"7d00f2d3-0000-0700-0000-64a830210000\"",
    "_attachments": "attachments/",
    "_ts": 1688743969
}

¡Enhorabuena! Ha ejecutado correctamente el procesamiento de una imagen que se cargó en Blob Storage mediante Azure Functions y Computer Vision.

Solución de problemas

Use la tabla siguiente para facilitar la solución de problemas durante este procedimiento.

Problema Solución
await computerVisionClient.read(url); errores con Only absolute URLs are supported Asegúrese de que el punto de conexión ComputerVisionEndPoint tiene el formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/.

Limpieza de recursos

Si no va a seguir usando esta aplicación, puede eliminar los recursos que ha creado al quitar el grupo de recursos.

  1. Seleccione Grupos de recursos en el Explorador de Azure.
  2. Busque y haga clic con el botón derecho en el grupo de recursos msdocs-storage-function en la lista.
  3. Seleccione Eliminar. El proceso para eliminar el grupo de recursos puede tardar unos minutos en completarse.

Código de ejemplo

Pasos siguientes