Início Rápido: Responder às alterações de banco de dados no Azure Cosmos DB usando o Azure Functions

Neste Início Rápido, você usará o Visual Studio Code para criar um aplicativo que responde a alterações de banco de dados em um banco de dados Sem SQL no Azure Cosmos DB. Após testar o código localmente, você o implantará em um novo aplicativo de funções sem servidor que você cria e executa em um plano de Consumo Flex no Azure Functions.

O código-fonte do projeto usa a extensão Azure Developer CLI (azd) com o Visual Studio Code para simplificar a inicialização e a validação do código do projeto localmente, bem como a implantação do código no Azure. Esta implantação segue as melhores práticas atuais para implantações seguras e escaláveis do Azure Functions.

Embora o plano de Consumo Flex siga um modelo de cobrança pay-for-what-you-use, este projeto de código cria recursos de Azure adicionais, incluindo uma instância de Azure Cosmos DB. Lembre-se de limpar os recursos quando terminar para evitar encargos contínuos.

Este artigo dá suporte à versão 4 do modelo de programação Node.js para Azure Functions.

Este artigo dá suporte à versão 2 do modelo de programação Python para Azure Functions.

Pré-requisitos

  • Node.js 18.x ou posterior. Use o comando node --version para verificar sua versão.

Inicializar o projeto

Use a CLI do Desenvolvedor do Azure (azd) para criar um projeto de código de Azure Functions local a partir de um modelo.

  1. Em um terminal, execute este azd init comando para criar um projeto local a partir do modelo:

    azd init --template functions-quickstart-dotnet-azd-cosmosdb -e cosmosdbchanges-dotnet

    Esse comando extrai os arquivos de projeto do repositório template e inicializa o projeto em uma nova pasta. Em azd, o ambiente é utilizado para manter um contexto de implantação único para o seu aplicativo e você pode definir mais de um. Ele também faz parte do nome do grupo de recursos que você cria no Azure.

  2. Mudar para o diretório do projeto:

    cd functions-quickstart-dotnet-azd-cosmosdb

  1. Em um terminal, execute este azd init comando para criar um projeto local a partir do modelo:

    azd init --template functions-quickstart-java-azd-cosmosdb -e cosmosdbchanges-java

    Esse comando extrai os arquivos de projeto do repositório template e inicializa o projeto em uma nova pasta. Em azd, o ambiente é utilizado para manter um contexto de implantação único para o seu aplicativo e você pode definir mais de um. Ele também faz parte do nome do grupo de recursos que você cria no Azure.

  2. Mudar para o diretório do projeto:

    cd functions-quickstart-java-azd-cosmosdb

  1. Em um terminal, execute este azd init comando para criar um projeto local a partir do modelo:

    azd init --template functions-quickstart-javascript-azd-cosmosdb -e cosmosdbchanges-js

    Esse comando extrai os arquivos de projeto do repositório template e inicializa o projeto em uma nova pasta. Em azd, o ambiente é utilizado para manter um contexto de implantação único para o seu aplicativo e você pode definir mais de um. Ele também faz parte do nome do grupo de recursos que você cria no Azure.

  2. Mudar para o diretório do projeto:

    cd functions-quickstart-javascript-azd-cosmosdb

  1. Em um terminal, execute este azd init comando para criar um projeto local a partir do modelo:

    azd init --template functions-quickstart-powershell-azd-cosmosdb -e cosmosdbchanges-ps

    Esse comando extrai os arquivos de projeto do repositório template e inicializa o projeto em uma nova pasta. Em azd, o ambiente é utilizado para manter um contexto de implantação único para o seu aplicativo e você pode definir mais de um. Ele também faz parte do nome do grupo de recursos que você cria no Azure.

  2. Mudar para o diretório do projeto:

    cd functions-quickstart-powershell-azd-cosmosdb

  1. Em um terminal, execute este azd init comando para criar um projeto local a partir do modelo:

    azd init --template functions-quickstart-typescript-azd-cosmosdb -e cosmosdbchanges-ts

    Esse comando extrai os arquivos de projeto do repositório template e inicializa o projeto em uma nova pasta. Em azd, o ambiente é utilizado para manter um contexto de implantação único para o seu aplicativo e você pode definir mais de um. Ele também faz parte do nome do grupo de recursos que você cria no Azure.

  2. Mudar para o diretório do projeto:

    cd functions-quickstart-typescript-azd-cosmosdb

  1. Em um terminal, execute este azd init comando para criar um projeto local a partir do modelo:

    azd init --template functions-quickstart-python-azd-cosmosdb -e cosmosdbchanges-py

    Esse comando extrai os arquivos de projeto do repositório template e inicializa o projeto em uma nova pasta. Em azd, o ambiente é utilizado para manter um contexto de implantação único para o seu aplicativo e você pode definir mais de um. Ele também faz parte do nome do grupo de recursos que você cria no Azure.

  2. Mudar para o diretório do projeto:

    cd functions-quickstart-python-azd-cosmosdb

  1. Execute este comando, dependendo do sistema operacional local, para conceder aos scripts de configuração as permissões necessárias:

    Execute este comando com privilégios suficientes:

    chmod +x ./infra/scripts/*.sh

  2. Abra o projeto no Visual Studio Code:

    code .

Antes de executar seu aplicativo localmente, você deve criar os recursos no Azure. Este projeto não usa a emulação local para o Azure Cosmos DB.

Criar recursos do Azure

Este projeto é configurado para usar o azd provision comando para criar um aplicativo de funções em um plano de Consumo Flex, juntamente com outros recursos necessários do Azure que seguem as práticas recomendadas atuais.

  1. No Visual Studio Code, pressione F1 para abrir a paleta de comandos, pesquise e execute o comando Azure Developer CLI (azd): Sign In with Azure Developer CLIe entre usando sua conta do Azure.

  2. Pressione F1 para abrir a paleta de comandos, pesquise e execute o comando Azure Developer CLI (azd): Provision Azure resources (provision) para criar os recursos necessários do Azure:

  3. Quando solicitado na janela terminal, forneça estes parâmetros de implantação necessários:

    Rápido Description
    Selecione uma Assinatura do Azure a ser usada Escolha a assinatura na qual você deseja que seus recursos sejam criados.
    parâmetro de implantação de localização Região do Azure na qual criar o grupo de recursos que contém os novos recursos do Azure. Somente regiões que atualmente dão suporte para o plano de Consumo Flex são mostradas.
    Parâmetro de implantação vnetEnabled Embora o modelo dê suporte à criação de recursos dentro de uma rede virtual, para simplificar a implantação e o teste, escolha False.

    O azd provision comando usa sua resposta a esses prompts com os arquivos de configuração do Bicep para criar e configurar esses recursos necessários do Azure, seguindo as práticas recomendadas mais recentes:

    • plano de Consumo Flex e aplicativo de funções
    • Conta do Azure Cosmos DB
    • Armazenamento do Microsoft Azure (obrigatório) e Application Insights (recomendado)
    • Políticas de acesso e funções para sua conta
    • Conexões de serviço a serviço usando identidades gerenciadas (em vez de cadeias de conexão armazenadas)

    Os ganchos pós-provisionamento também geram o arquivo local.settings.json, que é necessário ao executar localmente. Esse arquivo também contém as configurações necessárias para se conectar ao banco de dados do Azure Cosmos DB no Azure.

    Dica

    Se as etapas falharem durante o provisionamento, você poderá executar novamente o azd provision comando novamente depois de resolver quaisquer problemas.

    Depois que o comando for concluído com êxito, você poderá executar o código do projeto localmente e disparar no banco de dados do Azure Cosmos DB no Azure.

Executar a função localmente

O Visual Studio Code integra-se às ferramentas do Azure Functions Core para permitir que você execute este projeto em seu computador de desenvolvimento local antes de publicar em seu novo aplicativo de funções no Azure.

  1. Pressione F1 e, na paleta de comandos, pesquise e execute o comando Azurite: Start.

  2. Para iniciar a função localmente, pressione F5 ou o ícone Executar e Depurar na barra Atividade do lado esquerdo. O painel Terminal exibe a saída das Core Tools. Seu aplicativo começa no painel Terminal e você pode ver o nome da função que está sendo executada localmente.

    Se você tiver problemas com a execução no Windows, verifique se o terminal padrão do Visual Studio Code não está definido como bash WSL.

  3. Com as Ferramentas Principais ainda em execução no Terminal, pressione F1 e, na paleta de comandos, pesquise e execute o comando NoSQL: Create Item... e selecione o document-db banco de dados e o documents contêiner.

  4. Substitua o conteúdo do arquivo Novo Item.json por esses dados JSON e selecione Salvar:

    {
    "id": "doc1",
    "title": "Sample document",
    "content": "This is a sample document for testing my Azure Cosmos DB trigger in Azure Functions."
}

    Depois de selecionar Salvar, você verá a execução da função no terminal e o documento local é atualizado para incluir metadados adicionados pelo serviço.

  5. Quando terminar, pressione Ctrl+C na janela do terminal para interromper o processo do host func.exe.

Examinar o código (opcional)

A função é disparada com base no feed de alterações em um banco de dados NoSQL do Azure Cosmos DB.

Essas variáveis de ambiente configuram como o gatilho monitora o feed de alterações:

  • COSMOS_CONNECTION__accountEndpoint: o endpoint da conta do Cosmos DB
  • COSMOS_DATABASE_NAME: o nome do banco de dados a ser monitorado
  • COSMOS_CONTAINER_NAME: o nome do contêiner a ser monitorado

Essas variáveis de ambiente são criadas para você no Azure (configurações do aplicativo de funções) e localmente (local.settings.json) durante a azd provision operação.

A variável de ambiente COSMOS_CONNECTION configura o endpoint da conta do Cosmos DB usado pelo acionador. Essa variável de ambiente é criada para você em Azure (configurações do aplicativo de funções) e localmente (local.settings.json) durante a operação azd provision. Os nomes do banco de dados e do contêiner são definidos na configuração do gatilho.

Você pode examinar o código que define o gatilho Azure Cosmos DB:

using System;
using System.Collections.Generic;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class CosmosTrigger
    {
        private readonly ILogger _logger;

        public CosmosTrigger(ILoggerFactory loggerFactory)
        {
            _logger = loggerFactory.CreateLogger<CosmosTrigger>();
        }

        [Function("cosmos_trigger")]
        public void Run([CosmosDBTrigger(
            databaseName: "%COSMOS_DATABASE_NAME%",
            containerName: "%COSMOS_CONTAINER_NAME%",
            Connection = "COSMOS_CONNECTION",
            LeaseContainerName = "leases",
            CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input)
        {
            if (input != null && input.Count > 0)
            {
                _logger.LogInformation("Documents modified: " + input.Count);
                _logger.LogInformation("First document Id: " + input[0].id);
            }
        }
    }
    public class MyDocument
    {
        /// <summary>
        /// The unique identifier for the document.
        /// </summary>
        public required string id { get; set; }

        /// <summary>
        /// A text field in the document.
        /// </summary>
        public required string Text { get; set; }

        /// <summary>
        /// A numeric field in the document.
        /// </summary>
        public int Number { get; set; }

        /// <summary>
        /// A boolean field in the document.
        /// </summary>
        public bool Boolean { get; set; }
    }
}

Você pode examinar o projeto de modelo completo a.

package com.function;

import com.microsoft.azure.functions.ExecutionContext;
import com.microsoft.azure.functions.annotation.CosmosDBTrigger;
import com.microsoft.azure.functions.annotation.FunctionName;

public class CosmosTrigger {

    @FunctionName("cosmos_trigger")
    public void run(
        @CosmosDBTrigger(
            name = "input",
            databaseName = "%COSMOS_DATABASE_NAME%",
            containerName = "%COSMOS_CONTAINER_NAME%",
            connection = "COSMOS_CONNECTION",
            leaseContainerName = "leases",
            createLeaseContainerIfNotExists = true
        ) Object[] items,
        final ExecutionContext context
    ) {
        if (items != null && items.length > 0) {
            context.getLogger().info("Documents modified: " + items.length);
            context.getLogger().info("First document Id: " + items[0].toString());
        }
    }
}

Você pode examinar o projeto de modelo completo a.

const { app } = require('@azure/functions');

app.cosmosDB('cosmos_trigger', {
    connection: 'COSMOS_CONNECTION',
    databaseName: '%COSMOS_DATABASE_NAME%',
    containerName: '%COSMOS_CONTAINER_NAME%',
    leaseContainerName: 'leases',
    createLeaseContainerIfNotExists: true,
    handler: (documents, context) => {
        if (documents && documents.length > 0) {
            context.log(`Documents modified: ${documents.length}`);
            context.log(`First document Id: ${documents[0].id}`);
        }
    }
});

Você pode examinar o projeto de modelo completo a.

import { app, InvocationContext } from "@azure/functions";

export async function cosmos_trigger(documents: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Cosmos DB function processed ${documents.length} documents`);

    if (documents && documents.length > 0) {
        for (const doc of documents) {
            context.log(`First document: ${JSON.stringify(doc)}`);
            if (doc && typeof doc === "object" && "id" in doc) {
                context.log(`First document id: ${(doc as { id?: string }).id}`);
            }
        }
    } else {
        context.log("No documents found.");
    }
}


app.cosmosDB('cosmos_trigger', {
    connection: 'COSMOS_CONNECTION',
    databaseName: 'documents-db',
    containerName: 'documents',
    createLeaseContainerIfNotExists: true,
    handler: cosmos_trigger
});

Você pode examinar o projeto de modelo completo a.

O gatilho é definido neste arquivo function.json :

{
  "bindings": [
    {
      "type": "cosmosDBTrigger",
      "name": "InputDocuments",
      "direction": "in",
      "databaseName": "%COSMOS_DATABASE_NAME%",
      "containerName": "%COSMOS_CONTAINER_NAME%",
      "connection": "COSMOS_CONNECTION",
      "leaseContainerName": "leases",
      "createLeaseContainerIfNotExists": true
    }
  ]
}

O código a seguir é executado quando o gatilho é executado:

param($InputDocuments, $TriggerMetadata)

if ($InputDocuments -and $InputDocuments.Count -gt 0) {
    Write-Host "Documents modified: $($InputDocuments.Count)"
    Write-Host "First document Id: $($InputDocuments[0].id)"
}

Você pode examinar o projeto de modelo completo a.

import os
import azure.functions as func
import logging

app = func.FunctionApp()


@app.cosmos_db_trigger(
    arg_name="documents",
    container_name=os.environ.get("COSMOS_CONTAINER_NAME"),
    database_name=os.environ.get("COSMOS_DATABASE_NAME"),
    connection="COSMOS_CONNECTION",
    create_lease_container_if_not_exists="true",
)
def cosmos_trigger(documents: func.DocumentList):
    logging.info("Python CosmosDB triggered.")
    logging.info(f"Documents modified: {len(documents)}")
    if documents:
        for doc in documents:
            logging.info(f"First document: {doc.to_json()}")
            logging.info(f"First document id: {doc.get('id')}")
    else:
        logging.info("No documents found.")

Você pode examinar o projeto de modelo completo a.

Depois de examinar e verificar seu código de função localmente, é hora de publicar o projeto no Azure.

Publicar no Azure

Você pode executar o azd deploy comando do Visual Studio Code para implantar o código do projeto em seus recursos já provisionados no Azure.

  1. Pressione F1 para abrir a paleta de comandos.

  2. Pesquise e execute o comando Azure Developer CLI (azd): Deploy to Azure (deploy).

    O azd deploy comando empacota e implanta seu código no contêiner de implantação. O aplicativo é então iniciado e executa no pacote implantado.

    Depois que o comando for concluído com êxito, seu aplicativo será executado no Azure.

Invocar a função no Azure

  1. No Visual Studio Code, pressione F1 e, na paleta de comandos, pesquise e execute o comando Azure: Open in portal, selecione Function appe escolha seu novo aplicativo. Entre com sua conta do Azure, se necessário.

    Esse comando abre seu novo aplicativo de funções no portal do Azure.

  2. Na guia Visão geral na página principal, selecione o nome do aplicativo de funções e, em seguida, a guia Logs .

  3. Use o NoSQL: Create Item comando no Visual Studio Code para adicionar novamente um documento ao contêiner como antes.

  4. Verifique novamente se a função é disparada por uma atualização no contêiner monitorado.

Reimplantar seu código

Você pode executar o azd deploy comando quantas vezes precisar para implantar atualizações de código em seu aplicativo de funções.

Observação

Os arquivos de código implantados são sempre sobrescritos pelo pacote de implantação mais recente.

Suas respostas iniciais aos prompts azd e quaisquer variáveis de ambiente geradas por azd são armazenadas localmente no seu ambiente nomeado. Use o comando azd env get-values para revisar todas as variáveis no seu ambiente que foram usadas ao criar recursos do Azure.

Limpar os recursos

Quando terminar de trabalhar com seu aplicativo de funções e recursos relacionados, você pode utilizar este comando para excluir o aplicativo de funções e seus recursos relacionados do Azure e evitar custos adicionais:

azd down --no-prompt

Observação

A opção --no-prompt instrui azd a excluir seu grupo de recursos sem uma confirmação sua.

Este comando não afeta seu projeto de código local.

Conteúdo relacionado

  • Last updated on