Share via

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

  • Artigo

Neste tutorial, você aprenderá a carregar uma imagem para Armazenamento de Blobs do Azure e processá-la usando o Azure Functions, a Pesquisa Visual Computacional e o Cosmos DB. Você também aprenderá a implementar gatilhos e associações do Azure Function como parte desse processo. Juntos, esses serviços analisarão uma imagem carregada que contém texto, extrairão o texto dela e armazenarão o texto em uma linha de banco de dados para análise posterior ou outras finalidades.

O Armazenamento de Blobs do Azure é uma solução de armazenamento de objetos massivamente escalável da Microsoft para a nuvem. O Armazenamento de Blobs 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 Blobs na página de visão geral.

Aviso

Este tutorial usa o armazenamento acessível publicamente para simplificar o processo para concluir este tutorial. O acesso público anônimo apresenta um risco à segurança. Aprenda a evitar este risco.

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

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

Neste tutorial, você aprenderá a:

  • Carregar imagens e arquivos no 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 uma função do Azure

Diagrama de arquitetura mostrando um blob de imagem sendo adicionado ao Armazenamento de Blobs e, em seguida, sendo analisado por uma função do Azure, com a análise inserida no Cosmos DB.

Pré-requisitos

Crie a conta de armazenamento e o contêiner

A primeira etapa é 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 somente o Armazenamento de Blobs.

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

  2. Pesquise Armazenamento do Azure: Criar conta de Armazenamento (Avançado).

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

    Configuração Valor
    Nome Insira msdocsstoragefunction ou algo semelhante.
    Grupo de Recursos Crie o grupo de recursos msdocs-storage-function que você criou anteriormente.
    Hospedagem da Web estática Não.

  4. No Visual Studio Code, pressione 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 botão direito do mouse em Contêineres de Blobs e selecione Criar Contêiner de Blobs.
  3. Insira 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 Armazenamento no Azure Explorer e selecione Abrir no Portal.
  2. Na seção Armazenamento de dados, selecione Contêineres.
  3. Localize o contêiner images e selecione o ... (reticência) no final da linha.
  4. Selecione Alterar nível de acesso.
  5. Selecione Blob (acesso de leitura anônimo para blobs somente, depois selecione Ok.
  6. Retorne ao Visual Studio Code.

Recuperar a cadeia de conexão no Visual Studio Code

  1. No Visual Studio Code, pressione 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 isso em algum lugar para usar mais tarde.
  4. Anote o nome da conta de armazenamento msdocsstoragefunction para uso posterior.

Criar o serviço Azure AI Vision

Next, create the Azure AI Vision service account that will process our uploaded files. 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, pesquise por Computador e selecione o resultado rotulado como Visual computacional.

  2. Na página Pesquisa visual computacional, selecione + Criar.

  3. Na página Criar a Pesquisa Visual Computacional, insira os seguintes valores:

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

    Uma captura de tela mostrando como criar um novo serviço de Pesquisa Visual Computacional.

  4. Selecione Examinar + Criar na parte inferior. O Azure levará um momento para validar as informações inseridas. Depois que as configurações forem validadas, escolha Criar e o Azure começará a provisionar ao serviço de Pesquisa Visual Computacional, o que pode levar um momento.

  5. Ao concluir a operação, selecione Ir para Recursos.

Recuperar as chaves da Pesquisa Visual Computacional

Em seguida, precisamos encontrar a chave secreta e o URL do ponto de extremidade para o serviço Pesquisa Visual Computacional a ser usado em nosso aplicativo de Azure Function.

  1. Na página de visão geral Pesquisa Visual 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 do Ponto de extremidade e cole-os em algum lugar para usar posteriormente. O ponto de extremidade deverá estar no formato do https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/

Uma captura de tela mostrando como recuperar o ponto de extremidade de URL e chaves para um serviço de Pesquisa Visual Computacional.

Criar um ponto de extremidade no 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 banco de dados relacional e NoSQL totalmente gerenciado para o 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 ao criar seu recurso, as associações de uma função do Azure para 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, pesquise Azure Cosmos DB e selecione o resultado.

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

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

    • Assinatura: escolha a Assinatura desejada.
    • Grupo de recursos: use o grupo de recursos msdocs-storage-function que você criou anteriormente.
    • Região: selecione a mesma região que seu grupo de recursos.
    • Nome: insira um nome de msdocscosmosdb.
    • Tipo de preço: escolha Gratuito se estiver disponível, caso contrário, escolha Standard S1.

  4. Selecione Examinar + Criar na parte inferior. O Azure levará um momento para validar as informações inseridas. Depois que as configurações forem validadas, escolha Criar e o Azure começará a provisionar ao serviço de Pesquisa Visual Computacional, o que pode levar um momento.

  5. Ao concluir a operação, selecione Ir para Recursos.

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

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

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

  8. Mantenha o restante dos valores padrão e selecione OK.

Obter a cadeia de conexão do Cosmos DB

Obtenha a cadeia de conexão da conta de serviço do Cosmos DB a ser usada no aplicativo de funções de Azure.

  1. Na página 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 amostra

O código da função do Azure usado neste tutorial pode ser encontrado neste repositório do GitHub, no subdiretório JavaScript-v4. 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 amostra realiza as seguintes tarefas:

  • Recupera variáveis de ambiente para se conectar à conta de armazenamento, ao serviço de Pesquisa Visual Computacional e ao serviço do Cosmos DB
  • Aceita o arquivo carregado como um parâmetro de blob
  • Analisa o blob usando o serviço de Pesquisa Visual Computacional
  • Insere o texto da imagem analisado, como um objeto JSON, no Cosmos DB usando associações de saída

Depois que você baixou e abriu o projeto, há alguns conceitos essenciais a entender:

Conceito Finalidade
Função A Função do Azure é definida pelo código de função e pelas associações. Elas estão em ./src/functions/process-blobs.js.
Gatilhos e associações Os gatilhos e associações indicam os dados esperados para dentro ou para fora da função e qual serviço enviará ou receberá esses dados.

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

Gatilho de Blob de Armazenamento de Entrada

O código, que especifica que a função é disparada quando um blob é carregado no contêiner de imagens, virá a seguir. A função é disparada em qualquer nome de blob, incluindo as 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 do Blob de Armazenamento é usado para associar a função ao evento de upload no Armazenamento de Blobs. O gatilho tem dois parâmetros necessários:
    • path: o caminho que o gatilho observa para eventos. O caminho inclui o nome do contêiner, images e a substituição de variável para o nome do blob. Esse nome de blob é recuperado da propriedade name.
    • {name}: o nome do blob carregado. O uso do blob é o nome do parâmetro para o blob que está entrando 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 arquivo local.settings.json ao desenvolver localmente.

Gatilho do Azure Cosmos DB

Quando a função é concluída, a função usa o objeto retornado como os dados a serem inseridos no 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 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 de StorageConnection corresponde ao nome no arquivo local.settings.json.
    • databaseName: o banco de dados do Cosmos DB ao qual se conectar.
    • containerName: o nome da tabela para gravar o valor de texto da imagem analisada retornado pela função. A tabela já precisa existir.

Código da função do Azure

Veja a seguir 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 da conta do Armazenamento de Blobs e a chave da Pesquisa Visual Computacional. Essas variáveis de ambiente são adicionadas ao ambiente do Azure Function depois que ele é implantado.

A função padrão também utiliza um segundo método chamado AnalyzeImage. Esse código usa o ponto de extremidade da URL e a chave de nossa conta de Pesquisa Visual Computacional para fazer uma solicitação à Pesquisa Visual Computacional para processar a imagem. A solicitação retorna todo o texto descoberto na imagem. Esse texto é gravado no Cosmos DB, usando a associação de saída.

Configurar as configurações locais

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

Embora o código da Função do Azure seja executado localmente, ele se conecta aos serviços baseados em nuvem para o Armazenamento, em vez de usar quaisquer 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 o aplicativo Azure Functions

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

  1. No Visual Studio Code, pressione 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ções no Azure (Avançado).

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

    Configuração Valor
    Nome Insira msdocsprocessimage ou algo similar.
    Pilha de runtime Selecione uma versão do Node.js LTS.
    Modelo de programação Selecione v4.
    SO Selecione Linux.
    Grupo de Recursos Escolha o msdocs-storage-function grupo de recursos que você criou anteriormente.
    Localidade Selecione a mesma região que a do grupo de recursos.
    Tipo de Plano Selecione Consumo.
    Armazenamento do Azure Selecione a conta de armazenamento criada anteriormente.
    Application Insights Ignorar por enquanto.

  4. O Azure provisiona os recursos solicitados, o que levará alguns instantes para ser concluído.

Implantar o aplicativo Azure Functions

  1. Quando o processo de criação de recursos anterior for concluído, clique com o botão direito do mouse no novo recurso na seção Funções do Azure Explorer e selecione Implantar no Aplicativo de Funções.
  2. Se você for perguntado Tem certeza de que deseja implantar..., selecione Implantar.
  3. Quando o processo for concluído, será exibida uma notificação que inclui Carregar configurações. Selecione essa opção. Isso copia os valores do arquivo local.settings.json em seu aplicativo de funções do Azure. Se a notificação desaparecer antes que você puder selecioná-la, continue para a próxima seção.

Adicionar configurações de aplicativo para Armazenamento e Pesquisa Visual Computacional

Se você selecionou Carregar configurações na notificação, ignore esta seção.

O Azure Function foi implantado com êxito, mas ainda não pode se conectar à nossa conta de Armazenamento e aos serviços de Pesquisa Visual Computacional. As chaves corretas e as cadeias de conexão devem primeiro ser adicionadas às configurações do aplicativo do Azure Functions.

  1. Localize o recurso na seção Functions 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 segredos a seguir. Copie e cole seus valores secretos do projeto local no arquivo local.settings.json.

    Configuração
    StorageConnection
    StorageAccountName
    StorageContainerName
    ComputerVisionKey
    ComputerVisionEndPoint
    CosmosDBConnection

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

Carregue uma imagem para o Armazenamento de Blobs

Agora você está pronto para testar nosso aplicativo! Você pode carregar um blob no contêiner e verificar se o texto na imagem foi salvo no Cosmos DB.

  1. No Gerenciador do Azure no Visual Studio Code, localize e expanda seu recurso de Armazenamento na seção Armazenamento.
  2. Expanda Contêineres de Blob e clique com o botão direito do mouse no nome do contêiner images e selecione Carregar arquivos.
  3. É possível encontrar algumas imagens de exemplo incluídas na pasta de imagens na raiz do projeto de exemplo para download ou pode usar uma das suas.
  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.

Exibir análise de texto da imagem

Em seguida, você pode verificar se o upload disparou 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 Explorer do Azure, no nó do Azure Cosmos DB, selecione o recurso e expanda-o para localizar seu banco de dados, StorageTutorial.

  2. Expanda o nó de banco de dados.

  3. Um contêiner de análise agora deve estar disponível. Selecione no nó Documentos do contêiner para visualizar os dados no interior. Você deve 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 Blobs usando o Azure Functions e a Pesquisa Visual Computacional.

Soluçã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 Verifique se seu ComputerVisionEndPoint ponto de extremidade está no formato https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/.

Limpar os recursos

Se você não quiser continuar a usar esse aplicativo, poderá excluir os recursos criados 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 Excluir. O processo para excluir o grupo de recursos pode levar alguns minutos para ser concluído.

Código de exemplo

Próximas etapas