Esercitazione per JavaScript: Caricare e analizzare un file con Funzioni di Azure e Archiviazione BLOB

  • Articolo

In questa esercitazione si apprenderà come caricare un'immagine in Archiviazione BLOB di Azure ed elaborarla usando Funzioni di Azure, Visione artificiale e Cosmos DB. Si apprenderà anche come implementare trigger e associazioni di Funzioni di Azure come parte di questo processo. Insieme, questi servizi analizzano un'immagine caricata che contiene testo, estraggono il testo e quindi lo archiviano in una riga del database per analisi successive o altri scopi.

Archiviazione BLOB di Azure è la soluzione Microsoft di archiviazione oggetti altamente scalabile per il cloud. È progettata per l'archiviazione di immagini e documenti, lo streaming di file multimediali, la gestione dei dati di backup e archiviazione e molto altro ancora. Per altre informazioni su Archiviazione BLOB, vedere la pagina di panoramica.

Avviso

Per semplificare il completamento di questa esercitazione viene usato uno spazio di archiviazione accessibile pubblicamente. L'accesso anonimo pubblico presenta un rischio per la sicurezza. Leggere l'articolo su come correggere questo rischio.

Azure Cosmos DB è un database relazionale e NoSQL completamente gestito per lo sviluppo di app moderne.

Funzioni di Azure è una soluzione per computer serverless, che consente di scrivere ed eseguire piccoli blocchi di codice come funzioni a scalabilità elevata, serverless e basate su eventi. Per altre informazioni su Funzioni di Azure, vedere la pagina di panoramica.

In questa esercitazione, scopri come:

  • Caricare le immagini e i file in Archiviazione BLOB
  • Usare un trigger di evento di Funzioni di Azure per elaborare i dati caricati in Archiviazione BLOB
  • Usare Servizi di Azure AI per analizzare un'immagine
  • Scrivere dati in Cosmos DB usando associazioni di output di Funzioni di Azure

Architectural diagram showing an image blob is added to Blob Storage, then analyzed by an Azure Function, with the analysis inserted into a Cosmos DB.

Prerequisiti

Creare l'account di archiviazione e il contenitore

Il primo passaggio consiste nel creare l'account di archiviazione che conterrà i dati BLOB caricati, che in questo scenario saranno immagini che contengono testo. Un account di archiviazione offre svariati servizi, ma questa esercitazione utilizza solo Archiviazione BLOB.

  1. In Visual Studio Code premere CTRL + MAIUSC + P per aprire il riquadro comandi.

  2. Cercare Azure Storage: Create Storage Account (Advanced).

  3. Usare la tabella seguente per creare la risorsa di archiviazione.

    Impostazione valore
    Nome Immettere msdocsstoragefunction o qualcosa di simile.
    Gruppo di risorse Selezionare il gruppo di risorse msdocs-storage-function creato in precedenza.
    Hosting Web statico No.

  4. In Visual Studio Code selezionare MAIUSC + ALT + A per aprire Azure Explorer.

  5. Espandere la sezione Storage, espandere il nodo della sottoscrizione e attendere la creazione della risorsa.

Creare il contenitore in Visual Studio Code

  1. Sempre in Azure Explorer con la nuova risorsa di archiviazione trovata, espandere la risorsa per visualizzare i nodi.
  2. Fare clic con il pulsante destro del mouse su Blob Containers e selezionare Create Blob Container.
  3. Immettere il nome images. Verrà creato un contenitore privato.

Passare da contenitore privato a pubblico nel portale di Azure

Questa procedura prevede un contenitore pubblico. Per modificare la configurazione, apportare la modifica nel portale di Azure.

  1. Fare clic con il pulsante destro del mouse sulla risorsa di archiviazione in Azure Explorer e selezionare Open in portal.
  2. Nella sezione Archiviazione dati selezionare Contenitori.
  3. Trovare il contenitore, images, e selezionare il simbolo ... (puntini di sospensione) alla fine della riga.
  4. Selezionare Modifica livello di accesso.
  5. Selezionare BLOB (accesso in lettura anonimo solo per i BLOB) e quindi scegliere OK.
  6. Tornare a Visual Studio Code.

Recuperare la stringa di connessione in Visual Studio Code

  1. In Visual Studio Code selezionare MAIUSC + ALT + A per aprire Azure Explorer.
  2. Fare clic con il pulsante destro del mouse sulla risorsa di archiviazione e selezionare Copy Connection String.
  3. Incollarla da qualche parte per usarla in un secondo momento.
  4. Prendere nota anche del nome dell'account di archiviazione msdocsstoragefunction per usarlo in un secondo momento.

Creare il servizio Visione di Azure AI

Creare quindi l'account del servizio Visione di Azure AI per elaborare i file caricati. Visione fa parte di Servizi di Azure AI e offre svariate funzionalità per estrarre i dati dalle immagini. Per altre informazioni su Visione di Azure AI, vedere la pagina di panoramica.

  1. Nella barra di ricerca nella parte superiore del portale cercare Visione e selezionare il risultato Visione artificiale.

  2. Nella pagina Visione artificiale selezionare + Crea.

  3. Nella pagina Crea visione artificiale immettere i valori seguenti:

    • Sottoscrizione: scegliere la sottoscrizione desiderata.
    • Gruppo di risorse: usare il gruppo di risorse msdocs-storage-function creato in precedenza.
    • Area: selezionare l'area più vicina.
    • Nome: immettere il nome msdocscomputervision.
    • Piano tariffario: scegliere Gratuito se disponibile. In caso contrario, scegliere S1 Standard.
    • Selezionare la casella Informativa Intelligenza artificiale responsabile se si accettano le condizioni

    A screenshot showing how to create a new Computer Vision service.

  4. Selezionare Rivedi e crea nella parte inferiore. Azure impiegherà qualche istante per convalidare le informazioni immesse. Una volta convalidate le impostazioni, scegliere Crea e Azure inizierà il provisioning del servizio Visione artificiale, che potrebbe richiedere qualche istante.

  5. Al termine dell'operazione, selezionare Vai alla risorsa.

Recuperare le chiavi di Visione artificiale

Successivamente, è necessario trovare la chiave privata e l'URL dell'endpoint per il servizio Visione artificiale da usare nell'app per le funzioni di Azure.

  1. Nella pagina di panoramica di Visione artificiale selezionare Chiavi ed endpoint.

  2. Nella pagina Chiavi ed endpoint copiare i valori di Chiave 1 e EndPoint e incollarli da qualche parte per usarli in un secondo momento. L'endpoint deve essere nel formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/

A screenshot showing how to retrieve the Keys and URL Endpoint for a Computer Vision service.

Creare un account del servizio Cosmos DB

Creare l'account del servizio Cosmos DB per archiviare l'analisi dei file. Azure Cosmos DB è un database relazionale e NoSQL completamente gestito per lo sviluppo di app moderne. Seguire il collegamento per altre informazioni su Cosmos DB e sulle API di supporto.

Anche se in questa esercitazione viene specificata un'API quando si crea la risorsa, le associazioni di Funzioni di Azure per Cosmos DB sono configurate nello stesso modo per tutte le API di Cosmos DB.

  1. Nella barra di ricerca in alto nel portale di Azure cercare Azure Cosmos DB e selezionare il risultato.

  2. Nella pagina Azure Cosmos DB selezionare + Crea. Selezionare Azure Cosmos DB for NoSQL dall'elenco delle API.

  3. Nella pagina Crea Cosmos DB immettere i valori seguenti:

    • Sottoscrizione: scegliere la sottoscrizione desiderata.
    • Gruppo di risorse: usare il gruppo di risorse msdocs-storage-function creato in precedenza.
    • Area: selezionare la stessa area del gruppo di risorse.
    • Nome: immettere il nome msdocscosmosdb.
    • Piano tariffario: scegliere Gratuito se disponibile. In caso contrario, scegliere S1 Standard.

  4. Selezionare Rivedi e crea nella parte inferiore. Azure impiegherà qualche istante per convalidare le informazioni immesse. Una volta convalidate le impostazioni, scegliere Crea e Azure inizierà il provisioning del servizio Visione artificiale, che potrebbe richiedere qualche istante.

  5. Al termine dell'operazione, selezionare Vai alla risorsa.

  6. Selezionare Esplora dati e quindi selezionare Nuovo contenitore.

  7. Creare un nuovo database e un nuovo contenitore con le impostazioni seguenti:

    • Creare un nuovo ID database: StorageTutorial.
    • Immettere il nuovo ID contenitore: analysis.
    • Immettere la chiave di partizione: /type.

  8. Accettare le altre impostazioni predefinite e scegliere OK.

Recuperare la stringa di connessione di Cosmos DB

Recuperare la stringa di connessione per l'account del servizio Cosmos DB da usare nell'app per le funzioni di Azure.

  1. Nella pagina di panoramica di Cosmos DB selezionare Chiavi.

  2. Nella pagina Chiavi copiare la Stringa di connessione primaria per usarla in un secondo momento.

Scaricare e configurare il progetto di esempio

Il codice per la funzione di Azure usata in questa esercitazione è disponibile in questo repository GitHub, nella sottodirectory JavaScript-v4. È anche possibile clonare il progetto usando il comando seguente.

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

Il progetto di esempio esegue le attività seguenti:

  • Recupera le variabili di ambiente per connettersi all'account di archiviazione, al servizio Visione artificiale e al servizio Cosmos DB
  • Accetta il file caricato come parametro BLOB
  • Analizza il BLOB usando il servizio Visione artificiale
  • Inserisce il testo dell'immagine analizzata in Cosmos DB come oggetto JSON, usando associazioni di output

Dopo aver scaricato e aperto il progetto, è bene comprendere alcuni aspetti essenziali:

Idea Scopo
Funzione La funzione di Azure è definita dal codice della funzione e dalle associazioni. Si trovano in ./src/functions/process-blobs.js.
Trigger e associazioni I trigger e le associazioni indicano i dati previsti in ingresso o in uscita dalla funzione e il servizio che invierà o riceverà tali dati.

I trigger e le associazioni usati in questa esercitazione servono ad accelerare il processo di sviluppo eliminando la necessità di scrivere codice per connettersi ai servizi.

Trigger BLOB di archiviazione di input

Il codice di seguito specifica che la funzione viene attivata quando viene caricato un BLOB nel contenitore images. La funzione viene attivata in qualsiasi nome di BLOB, incluse le cartelle gerarchiche.


// ...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: il trigger di input BLOB di archiviazione viene usato per associare la funzione all'evento di caricamento nell'archiviazione BLOB. Il trigger ha due parametri obbligatori.
    • path: percorso in cui il trigger controlla gli eventi. Il percorso include il nome del contenitore,images, e la sostituzione della variabile per il nome del BLOB. Il nome del BLOB viene recuperato dalla proprietà name.
    • {name}: nome del BLOB caricato. L'uso di blob è il nome del parametro per il BLOB in ingresso nella funzione. Non modificare il valore blob.
    • connection: stringa di connessione dell'account di archiviazione. Quando si sviluppa in locale, il valore StorageConnection corrisponde al nome nel file local.settings.json.

Trigger Cosmos DB di uscita

Al termine dell'esecuzione, la funzione usa l'oggetto restituito come dati da inserire in 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'
    })
});

Per il contenitore in questo articolo sono obbligatorie le proprietà seguenti:

  • id: ID necessario per Cosmos DB per creare una nuova riga.

  • /type: chiave di partizione specificata alla creazione del contenitore.

  • output.cosmosDB: il trigger di output Cosmos DB viene usato per inserire il risultato della funzione in Cosmos DB.

    • connection: stringa di connessione dell'account di archiviazione. Il valore StorageConnection corrisponde al nome nel file local.settings.json.
    • databaseName: database Cosmos DB a cui connettersi.
    • containerName: nome della tabella in cui scrivere il valore del testo dell'immagine analizzata restituito dalla funzione. La tabella deve esistere già.

Codice della funzione di Azure

Di seguito è riportato il codice completo della funzione.

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'
    })
});

Questo codice recupera inoltre i valori di configurazione essenziali dalle variabili di ambiente, ad esempio la stringa di connessione di Archiviazione BLOB e la chiave di Visione artificiale. Queste variabili di ambiente vengono aggiunte all'ambiente della funzione di Azure dopo la distribuzione.

La funzione predefinita usa anche un secondo metodo denominato AnalyzeImage. Questo codice usa l'endpoint dell'URL e la chiave dell'account di Visione artificiale per richiedere a Visione artificiale di elaborare l'immagine. La richiesta restituisce tutto il testo individuato nell'immagine. Questo testo viene scritto in Cosmos DB usando l'associazione in uscita.

Configurare le impostazioni locali

Per eseguire il progetto in locale, immettere le variabili di ambiente nel file ./local.settings.json. Sostituire i valori dei segnaposto con i valori salvati in precedenza durante la creazione delle risorse di Azure.

Anche se il codice della funzione di Azure viene eseguito in locale, esegue comunque la connessione a servizi di archiviazione basati sul cloud anziché usare emulatori locali.

{
  "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"
  }
}

Creare un'app per le funzioni di Azure

A questo punto è possibile distribuire l'applicazione in Azure usando un'estensione di Visual Studio Code.

  1. In Visual Studio Code selezionare MAIUSC + ALT + A per aprire Azure Explorer.

  2. Nella sezione Functions individuare e fare clic con il pulsante destro del mouse sulla sottoscrizione e selezionare Create Function App in Azure (Advanced).

  3. Usare la tabella seguente per creare la risorsa di Funzioni.

    Impostazione valore
    Nome Immettere msdocsprocessimage o un nome simile.
    Stack di runtime Selezionare una versione di Node.js LTS.
    Modello di programmazione Selezionare v4.
    Sistema operativo Selezionare Linux.
    Gruppo di risorse Scegliere il gruppo di risorse msdocs-storage-function creato in precedenza.
    Location Selezionare la stessa area del gruppo di risorse.
    Tipo di piano Selezionare Consumption.
    Archiviazione di Azure Selezionare l'account di archiviazione creato in precedenza.
    Application Insights Ignorare per il momento.

  4. Azure effettua il provisioning delle risorse richieste, che richiederà alcuni istanti.

Distribuire l'app per le funzioni di Azure

  1. Al termine del processo di creazione risorse precedente, fare clic con il pulsante destro del mouse sulla nuova risorsa nella sezione Functions di Azure Explorer e selezionare Deploy to Function App.
  2. Se viene visualizzata la richiesta di conferma Are you sure you want to deploy..., selezionare Deploy.
  3. Al termine del processo viene visualizzata una notifica che include l'opzione Upload settings. Selezionare questa opzione. In questo modo i valori del file local.settings.json vengono copiati nell'app per le funzioni di Azure. Se la notifica è scomparsa prima di poterla selezionare, continuare con la sezione successiva.

Aggiungere le impostazioni dell'app per Archiviazione e Visione artificiale

Se è stata selezionata l'opzione Upload settings nella notifica, ignorare questa sezione.

La funzione di Azure è stata distribuita correttamente, ma non può ancora connettersi all'account di archiviazione e ai servizi di Visione artificiale. È necessario prima aggiungere le chiavi e le stringhe di connessione corrette alle impostazioni di configurazione dell'app per le funzioni di Azure.

  1. Trovare la risorsa nella sezione Functions di Azure Explorer, fare clic con il pulsante destro del mouse, scegliere Application Settingse selezionare Add New Setting.

  2. Immettere una nuova impostazione dell'app per i segreti seguenti. Copiare e incollare i valori dei segreti dal progetto locale nel file local.settings.json.

    Impostazione
    StorageConnection
    StorageAccountName
    StorageContainerName
    ComputerVisionKey
    ComputerVisionEndPoint
    CosmosDBConnection

Tutte le variabili di ambiente necessarie per connettere la funzione di Azure ai vari servizi sono ora disponibili.

Caricare un'immagine in Archiviazione BLOB

A questo punto, è possibile testare l'applicazione. È possibile caricare un BLOB nel contenitore e quindi verificare che il testo nell'immagine sia stato salvato in Cosmos DB.

  1. In Azure Explorer in Visual Studio Code trovare ed espandere la risorsa di archiviazione nella sezione Storage.
  2. Espandere Blob Containers e fare clic con il pulsante destro del mouse sul nome del contenitore, images, quindi selezionare Upload files.
  3. È possibile trovare alcune immagini di esempio incluse nella cartella images nella radice del progetto di esempio scaricabile oppure è possibile usarne una personalizzata.
  4. Per la directory di destinazione accettare il valore predefinito /.
  5. Attendere che i file vengano caricati ed elencati nel contenitore.

Visualizzare l'analisi del testo dell'immagine

Successivamente, è possibile verificare che il caricamento abbia attivato la funzione di Azure e che il testo nell'immagine sia stato analizzato e salvato correttamente in Cosmos DB.

  1. In Visual Studio Code, in Azure Explorer, nel nodo Azure Cosmos DB selezionare la risorsa ed espanderla per trovare il database StorageTutorial.

  2. Espandere il nodo del database.

  3. Dovrebbe essere disponibile un contenitore denominato analysis. Selezionare il nodo Documents del contenitore per visualizzare in anteprima i dati all'interno. Dovrebbe essere visualizzata una voce per il testo dell'immagine elaborata di un file caricato.

    {
    "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
}

Complimenti. È stata eseguita l'elaborazione di un'immagine caricata in Archiviazione BLOB usando Funzioni di Azure e Visione artificiale.

Risoluzione dei problemi

Usare la tabella seguente per risolvere i problemi che si verificano durante questa procedura.

Problema Risoluzione
await computerVisionClient.read(url); errori con Only absolute URLs are supported Assicurarsi che l'endpoint ComputerVisionEndPoint sia nel formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/.

Pulire le risorse

Se non si intende continuare a usare questa applicazione, è possibile eliminare le risorse create rimuovendo il gruppo di risorse.

  1. Selezionare Resource groups in Azure Explorer
  2. Trovare il gruppo di risorse msdocs-storage-function nell'elenco e fare clic sul nome corrispondente con il pulsante destro del mouse.
  3. Selezionare Elimina. Il completamento del processo per eliminare il gruppo di risorse può richiedere alcuni minuti.

Codice di esempio

Passaggi successivi