Partilhar via

Tutorial JavaScript: Carregar e analisar um arquivo com o Azure Functions e o Armazenamento de Blobs

  • Artigo

Neste tutorial, você aprenderá a carregar uma imagem no Armazenamento de Blobs do Azure e processá-la usando o Azure Functions, a Visão do Computador e o Cosmos DB. Você também aprenderá como implementar gatilhos e associações do Azure Function como parte desse processo. Juntos, esses serviços analisam uma imagem carregada que contém texto, extraem o texto dela e, em seguida, armazenam o texto em uma linha de banco de dados para análise posterior ou outros fins.

O Armazenamento de Blobs do Azure é a solução de armazenamento de objetos massivamente escalável da Microsoft para a nuvem. O Blob Storage foi projetado para armazenar imagens e documentos, transmitir arquivos de mídia, gerenciar dados de backup e arquivamento e muito mais. Você pode ler mais sobre o Armazenamento de Blob na página de visão geral.

Aviso

Este tutorial destina-se a uma adoção rápida e, como tal, não segue os requisitos de segurança por padrão. Para entender mais sobre esse cenário com uma meta de segurança por padrão, vá para Considerações de segurança.

O Azure Cosmos DB é um NoSQL totalmente gerenciado e um banco de dados relacional para desenvolvimento de aplicativos modernos.

O Azure Functions é uma solução de computador sem servidor que permite escrever e executar pequenos blocos de código como funções altamente escaláveis, sem servidor e orientadas por eventos. Você pode ler mais sobre o Azure Functions na página de visão geral.

Neste tutorial, saiba como:

  • Carregue imagens e arquivos para o Armazenamento de Blobs
  • Usar um gatilho de evento do Azure Function para processar dados carregados no Armazenamento de Blobs
  • Usar os serviços de IA do Azure para analisar uma imagem
  • Gravar dados no Cosmos DB usando associações de saída do Azure Function

O diagrama de arquitetura mostrando um blob de imagem é adicionado ao Armazenamento de Blobs e, em seguida, analisado por uma Função do Azure, com a análise inserida em um Cosmos DB.

Pré-requisitos

Criar a conta de armazenamento e o contêiner

O primeiro passo é criar a conta de armazenamento que conterá os dados de blob carregados, que neste cenário serão imagens que contêm texto. Uma conta de armazenamento oferece vários serviços diferentes, mas este tutorial utiliza apenas o Armazenamento de Blob.

  1. No Visual Studio Code, selecione Ctrl + Shift + P para abrir a paleta de comandos.

  2. Pesquisar Armazenamento do Azure: Criar Conta de Armazenamento (Avançado).

  3. Use a tabela a seguir para criar o recurso de armazenamento.

    Definição Valor
    Nome Digite msdocsstoragefunction ou algo semelhante.
    Grupo de Recursos Crie o grupo de msdocs-storage-function recursos criado anteriormente.
    Alojamento web estático N.º

  4. No Visual Studio Code, selecione Shift + Alt + A para abrir o Azure Explorer.

  5. Expanda a seção Armazenamento, expanda o nó de assinatura e aguarde a criação do recurso.

Criar o contêiner no Visual Studio Code

  1. Ainda no Azure Explorer com seu novo recurso de armazenamento encontrado, expanda o recurso para ver os nós.
  2. Clique com o botão direito do mouse em Contêineres de Blob e selecione Criar Contêiner de Blob.
  3. Introduza o nome images. Isso cria um contêiner privado.

Alterar de contêiner privado para público no portal do Azure

Este procedimento espera um contêiner público. Para alterar essa configuração, faça a alteração no portal do Azure.

  1. Clique com o botão direito do mouse no Recurso de Armazenamento no Azure Explorer e selecione Abrir no Portal.
  2. Na seção Armazenamento de Dados, selecione Contêineres.
  3. Encontre seu contêiner imagese selecione a ... (elipse) no final da linha.
  4. Selecione Alterar nível de acesso.
  5. Selecione Blob (acesso de leitura anônimo apenas para blobs e selecione Ok.
  6. Retorne ao Visual Studio Code.

Recuperar a cadeia de conexão no Visual Studio Code

  1. No Visual Studio Code, selecione Shift + Alt + A para abrir o Azure Explorer.
  2. Clique com o botão direito do mouse no recurso de armazenamento e selecione Copiar cadeia de conexão.
  3. cole em algum lugar para usar mais tarde.
  4. Anote também o nome msdocsstoragefunction da conta de armazenamento para usar mais tarde.

Criar o serviço Azure AI Vision

Em seguida, crie a conta de serviço Azure AI Vision que processará nossos arquivos carregados. O Vision faz parte dos serviços de IA do Azure e oferece vários recursos para extrair dados de imagens. Você pode saber mais sobre o Azure AI Vision na página de visão geral.

  1. Na barra de pesquisa na parte superior do portal, procure por Computador e selecione o resultado rotulado Visão computacional.

  2. Na página Visão computacional, selecione + Criar.

  3. Na página Criar Visão por Computador, insira os seguintes valores:

    • Subscrição: Escolha a Subscrição pretendida.
    • Grupo de Recursos: use o grupo de msdocs-storage-function recursos criado anteriormente.
    • Região: selecione a região mais próxima de você.
    • Nome: insira um nome de msdocscomputervision.
    • Nível de preço: Escolha Gratuito se estiver disponível, caso contrário, escolha Standard S1.
    • Marque a caixa Aviso de IA Responsável se concordar com os termos

    Uma captura de tela mostrando como criar um novo serviço de Visão por Computador.

  4. Selecione Rever + Criar na parte inferior. O Azure leva um momento para validar as informações que você inseriu. Depois que as configurações forem validadas, escolha Criar e o Azure começará a provisionar o serviço de Visão por Computador, o que pode levar um momento.

  5. Quando a operação estiver concluída, selecione Ir para Recurso.

Recuperar as teclas do Computer Vision

Em seguida, precisamos encontrar a chave secreta e a URL do ponto de extremidade para o serviço de Visão Computacional usar em nosso aplicativo Azure Function.

  1. Na página de visão geral da Visão Computacional, selecione Chaves e Ponto de extremidade.

  2. Na página Chaves e Ponto de Extremidade, copie o valor da Chave 1 e os valores de Ponto de Extremidade e cole-os em algum lugar para usar mais tarde. O parâmetro de avaliação deve ter o formato de https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/

Uma captura de tela mostrando como recuperar o ponto de extremidade de chaves e URL para um serviço de visão computacional.

Criar uma conta de serviço do Cosmos DB

Crie a conta de serviço do Cosmos DB para armazenar a análise de arquivos. O Azure Cosmos DB é um NoSQL totalmente gerenciado e um banco de dados relacional para desenvolvimento de aplicativos modernos. Você pode saber mais sobre o Cosmos DB e suas APIs de suporte para vários bancos de dados diferentes do setor.

Embora este tutorial especifique uma API quando você cria seu recurso, as associações de Função do Azure para o Cosmos DB são configuradas da mesma maneira para todas as APIs do Cosmos DB.

  1. Na barra de pesquisa na parte superior do portal, procure o Azure Cosmos DB e selecione o resultado.

  2. Na página Azure Cosmos DB, selecione + Criar. Selecione Azure Cosmos DB para NoSQL na lista de opções de API.

  3. Na página Criar Cosmos DB, insira os seguintes valores:

    • Subscrição: Escolha a Subscrição pretendida.
    • Grupo de Recursos: use o grupo de msdocs-storage-function recursos criado anteriormente.
    • Região: selecione a mesma região que o seu grupo de recursos.
    • Nome: insira um nome de msdocscosmosdb.
    • Nível de preço: Escolha Gratuito se estiver disponível, caso contrário, escolha Standard S1.

  4. Selecione Rever + Criar na parte inferior. O Azure levará um momento para validar as informações que você inseriu. Depois que as configurações forem validadas, escolha Criar e o Azure começará a provisionar o serviço de Visão por Computador, o que pode levar um momento.

  5. Quando a operação estiver concluída, selecione Ir para Recurso.

  6. Selecione Data Explorer e, em seguida, selecione Novo contêiner.

  7. Crie um novo banco de dados e contêiner com as seguintes configurações:

    • Crie uma nova ID de banco de dados: StorageTutorial.
    • Insira o novo ID do contêiner: analysis.
    • Digite a chave de partição: /type.

  8. Deixe o restante das configurações padrão e selecione OK.

Obter a cadeia de conexão do Cosmos DB

Obtenha a cadeia de conexão para a conta de serviço do Cosmos DB a ser usada em nosso aplicativo Azure Function.

  1. Na página de visão geral do Cosmos DB , selecione Chaves.

  2. Na página Chaves, copie a Cadeia de Conexão Primária para usar mais tarde.

Baixar e configurar o projeto de exemplo

O código para a Função do Azure usada neste tutorial pode ser encontrado neste repositório GitHub, no JavaScript-v4 subdiretório. Você também pode clonar o projeto usando o comando abaixo.

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

O projeto de exemplo realiza as seguintes tarefas:

  • Recupera variáveis de ambiente para se conectar à conta de armazenamento, ao Computer Vision e ao serviço Cosmos DB
  • Aceita o arquivo carregado como um parâmetro de blob
  • Analisa o blob usando o serviço de Visão por Computador
  • Insere o texto da imagem analisada, como um objeto JSON, no Cosmos DB usando associações de saída

Depois de baixar e abrir o projeto, há alguns conceitos essenciais para entender:

Conceito Propósito
Function A Função do Azure é definida pelo código da função e pelas associações. Estes estão em ./src/functions/process-blobs.js.
Acionadores e enlaces Os gatilhos e ligações indicam que os dados, que são esperados dentro ou fora da função e qual serviço vai enviar ou receber esses dados.

Gatilhos e ligações usados neste tutorial para agilizar o processo de desenvolvimento, removendo a necessidade de escrever código para se conectar a serviços.

Gatilho de Blob de armazenamento de entrada

O código, que especifica que a função é acionada quando um blob é carregado no contêiner de imagens , segue. A função é acionada em qualquer nome de blob, incluindo pastas hierá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 - O gatilho de entrada de Blob de Armazenamento é usado para vincular a função ao evento de carregamento no Armazenamento de Blob. O gatilho tem dois parâmetros necessários:
    • path: O caminho que o gatilho observa para eventos. O caminho inclui o nomeimages do contêiner e a substituição da variável pelo nome do blob. Esse nome de blob é recuperado da name propriedade.
    • {name}: O nome do blob carregado. O uso do é o nome do blob parâmetro para o blob que entra na função. Não altere o valor blob.
    • connection: A cadeia de conexão da conta de armazenamento. O valor StorageConnection corresponde ao nome no local.settings.json arquivo ao desenvolver localmente.

Gatilho de saída do Cosmos DB

Quando a função termina, a função usa o objeto retornado como os dados para inserir no Cosmos DB.


// ... function definition object
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 o contêiner neste artigo, as seguintes propriedades necessárias são:

  • id: a ID necessária para o Cosmos DB criar uma nova linha.

  • /type: a chave de partição especificada com o contêiner foi criada.

  • output.cosmosDB - O gatilho de saída do Cosmos DB é usado para inserir o resultado da função no Cosmos DB.

    • connection: A cadeia de conexão da conta de armazenamento. O valor StorageConnection corresponde ao nome no local.settings.json arquivo.
    • databaseName: O banco de dados do Cosmos DB ao qual se conectar.
    • containerName: O nome da tabela para escrever o valor de texto da imagem analisada retornado pela função. A tabela já deve existir.

Código da função do Azure

A seguir está o código de função 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'
    })
});

Esse código também recupera valores de configuração essenciais de variáveis de ambiente, como a cadeia de conexão Blob Storage e a chave Computer Vision. Essas variáveis de ambiente são adicionadas ao ambiente do Azure Function após sua implantação.

A função padrão também usa um segundo método chamado AnalyzeImage. Esse código usa a URL Endpoint e a Key da conta Computer Vision para fazer uma solicitação à Computer Vision para processar a imagem. A solicitação retorna todo o texto descoberto na imagem. Este texto é escrito no Cosmos DB, usando a ligação de saída.

Definir configurações locais

Para executar o projeto localmente, insira as variáveis de ambiente no ./local.settings.json arquivo. Preencha os valores de espaço reservado com os valores salvos anteriormente ao criar os recursos do Azure.

Embora o código do Azure Function seja executado localmente, ele se conecta aos serviços baseados em nuvem para Armazenamento, em vez de usar emuladores locais.

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

Criar aplicativo Azure Functions

Agora você está pronto para implantar o aplicativo no Azure usando uma extensão de código do Visual Studio.

  1. No Visual Studio Code, selecione Shift + Alt + A para abrir o explorador do Azure.

  2. Na seção Funções, localize e clique com o botão direito do mouse na assinatura e selecione Criar Aplicativo de Função no Azure (Avançado).

  3. Use a tabela a seguir para criar o recurso Função.

    Definição Valor
    Nome Digite msdocsprocessimage ou algo semelhante.
    Pilha de runtime Selecione uma versão Node.js LTS .
    Modelo de programação Selecione v4.
    SO Selecione Linux.
    Grupo de Recursos Escolha o grupo de msdocs-storage-function recursos criado anteriormente.
    Location Selecione a mesma região do seu grupo de recursos.
    Tipo de Plano Selecione Consumo.
    Armazenamento do Azure Selecione a conta de armazenamento que criou anteriormente.
    Application Insights Pule por enquanto.

  4. O Azure provisiona os recursos solicitados, que levarão alguns minutos para serem concluídos.

Implantar o aplicativo Azure Functions

  1. Quando o processo de criação de recursos anterior terminar, clique com o botão direito do mouse no novo recurso na seção Funções do explorador do Azure e selecione Implantar no Aplicativo de Função.
  2. Se lhe for perguntado Tem certeza de que deseja implantar..., selecione Implantar.
  3. Quando o processo é concluído, aparece uma notificação que uma escolha, que inclui as configurações de upload. Selecione essa opção. Isso copia os valores do seu arquivo de local.settings.json para seu aplicativo Azure Function. Se a notificação desapareceu antes que você pudesse selecioná-la, continue para a próxima seção.

Adicionar configurações de aplicativo para Armazenamento e Visão Computacional

Se você selecionou Configurações de upload na notificação, ignore esta seção.

A Função do Azure foi implantada com êxito, mas ainda não pode se conectar à nossa conta de Armazenamento e aos serviços de Visão Computacional. As chaves e cadeias de conexão corretas devem primeiro ser adicionadas às definições de configuração do aplicativo Azure Functions.

  1. Encontre seu recurso na seção Funções do explorador do Azure, clique com o botão direito do mouse em Configurações do Aplicativo e selecione Adicionar Nova Configuração.

  2. Insira uma nova configuração de aplicativo para os seguintes segredos. Copie e cole seus valores secretos local.settings.json do seu projeto local no arquivo.

    Definição
    Conexão de armazenamento
    StorageAccountName
    StorageContainerName
    ComputadorVisionKey
    ComputerVisionEndPoint
    CosmosDBConnection

Todas as variáveis de ambiente necessárias para conectar nossa função do Azure a diferentes serviços agora estão em vigor.

Carregar uma imagem para o Armazenamento de Blobs

Agora está pronto para testar a nossa aplicação! Você pode carregar um blob para o contêiner e, em seguida, verificar se o texto na imagem foi salvo no Cosmos DB.

  1. No explorador do Azure no Visual Studio Code, localize e expanda seu recurso de armazenamento na seção Armazenamento .
  2. Expanda Contêineres de Blob, clique com o botão direito do mouse no nome imagesdo contêiner e selecione Carregar arquivos.
  3. Você pode encontrar algumas imagens de exemplo incluídas na pasta de imagens na raiz do projeto de exemplo para download, ou você pode usar uma de sua própria.
  4. Para o diretório de destino, aceite o valor padrão, /.
  5. Aguarde até que os arquivos sejam carregados e listados no contêiner.

Ver análise de texto da imagem

Em seguida, você pode verificar se o carregamento acionou a Função do Azure e se o texto na imagem foi analisado e salvo no Cosmos DB corretamente.

  1. No Visual Studio Code, no Azure Explorer, no nó Azure Cosmos DB, selecione seu recurso e expanda-o para localizar seu banco de dados, StorageTutorial.

  2. Expanda o nó do banco de dados.

  3. Um contêiner de análise deve agora estar disponível. Selecione no nó Documentos do contêiner para visualizar os dados internos. Você verá uma entrada para o texto da imagem processada de um arquivo carregado.

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

Parabéns! Você conseguiu processar uma imagem que foi carregada no Armazenamento de Blob usando o Azure Functions e o Computer Vision.

Resolução de Problemas

Use a tabela a seguir para ajudar a solucionar problemas durante este procedimento.

Problema Resolução
await computerVisionClient.read(url); erros com Only absolute URLs are supported Certifique-se de que o seu ComputerVisionEndPoint ponto de extremidade está no formato de https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/.

Considerações de segurança

Esta solução, como um tutorial para iniciantes, não demonstra práticas seguras por padrão. Isso é intencional para permitir que você seja bem-sucedido na implantação da solução. A próxima etapa após essa implantação bem-sucedida é proteger os recursos. Esta solução usa três serviços do Azure, cada um com seus próprios recursos de segurança e considerações para configuração segura por padrão:

Código de exemplo

Clean up resources (Limpar recursos)

Se não pretender continuar a utilizar esta aplicação, pode eliminar os recursos que criou removendo o grupo de recursos.

  1. Selecione Grupos de recursos no explorador do Azure
  2. Localize e clique com o botão direito do mouse no msdocs-storage-function grupo de recursos da lista.
  3. Selecione Eliminar. O processo para excluir o grupo de recursos pode levar alguns minutos para ser concluído.

Conteúdos relacionados