Guida introduttiva: Rispondere alle modifiche del database in Azure Cosmos DB con Funzioni di Azure

In questa guida rapida si usa Visual Studio Code per creare un'app che risponde alle modifiche in un database No SQL in Azure Cosmos DB. Dopo aver testato il codice in locale, è possibile distribuirlo in una nuova app per le funzioni serverless creata in un piano a consumo Flex in Funzioni di Azure.

L'origine del progetto usa l'estensione Azure Developer CLI (azd) con Visual Studio Code per semplificare l'inizializzazione e la verifica del codice del progetto in locale, nonché la distribuzione del codice in Azure. Questa distribuzione segue le procedure consigliate correnti per le distribuzioni di Funzioni di Azure sicure e scalabili.

Mentre il piano Flex Consumption segue un modello di fatturazione pay-for-what-you-use, questo progetto di codice crea risorse aggiuntive Azure, inclusa un'istanza di Azure Cosmos DB. Assicurarsi di pulire le risorse al termine per evitare addebiti in corso.

Questo articolo supporta la versione 4 del modello di programmazione Node.js per Funzioni di Azure.

Questo articolo supporta la versione 2 del modello di programmazione Python per Funzioni di Azure.

Prerequisiti

  • Node.js 18.x o versione successiva. Usare il comando node --version per controllare la versione in uso.

Inizializzare il progetto

Usare l'interfaccia della riga di comando Azure Developer (azd) per creare un progetto di codice Funzioni di Azure locale da un modello.

  1. Da un terminale eseguire questo azd init comando per creare un progetto locale dal modello:

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

    Questo comando esegue il pull dei file di progetto dal repository template e inizializza il progetto in una nuova cartella. In azd, l'ambiente viene usato per mantenere un contesto di distribuzione univoco per l'app ed è possibile definirne più di uno. Fa anche parte del nome del gruppo di risorse creato in Azure.

  2. Spostarsi nella directory del progetto:

    cd functions-quickstart-dotnet-azd-cosmosdb

  1. Da un terminale eseguire questo azd init comando per creare un progetto locale dal modello:

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

    Questo comando esegue il pull dei file di progetto dal repository template e inizializza il progetto in una nuova cartella. In azd, l'ambiente viene usato per mantenere un contesto di distribuzione univoco per l'app ed è possibile definirne più di uno. Fa anche parte del nome del gruppo di risorse creato in Azure.

  2. Spostarsi nella directory del progetto:

    cd functions-quickstart-java-azd-cosmosdb

  1. Da un terminale eseguire questo azd init comando per creare un progetto locale dal modello:

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

    Questo comando esegue il pull dei file di progetto dal repository template e inizializza il progetto in una nuova cartella. In azd, l'ambiente viene usato per mantenere un contesto di distribuzione univoco per l'app ed è possibile definirne più di uno. Fa anche parte del nome del gruppo di risorse creato in Azure.

  2. Spostarsi nella directory del progetto:

    cd functions-quickstart-javascript-azd-cosmosdb

  1. Da un terminale eseguire questo azd init comando per creare un progetto locale dal modello:

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

    Questo comando esegue il pull dei file di progetto dal repository template e inizializza il progetto in una nuova cartella. In azd, l'ambiente viene usato per mantenere un contesto di distribuzione univoco per l'app ed è possibile definirne più di uno. Fa anche parte del nome del gruppo di risorse creato in Azure.

  2. Spostarsi nella directory del progetto:

    cd functions-quickstart-powershell-azd-cosmosdb

  1. Da un terminale eseguire questo azd init comando per creare un progetto locale dal modello:

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

    Questo comando esegue il pull dei file di progetto dal repository template e inizializza il progetto in una nuova cartella. In azd, l'ambiente viene usato per mantenere un contesto di distribuzione univoco per l'app ed è possibile definirne più di uno. Fa anche parte del nome del gruppo di risorse creato in Azure.

  2. Spostarsi nella directory del progetto:

    cd functions-quickstart-typescript-azd-cosmosdb

  1. Da un terminale eseguire questo azd init comando per creare un progetto locale dal modello:

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

    Questo comando esegue il pull dei file di progetto dal repository template e inizializza il progetto in una nuova cartella. In azd, l'ambiente viene usato per mantenere un contesto di distribuzione univoco per l'app ed è possibile definirne più di uno. Fa anche parte del nome del gruppo di risorse creato in Azure.

  2. Spostarsi nella directory del progetto:

    cd functions-quickstart-python-azd-cosmosdb

  1. Eseguire questo comando, a seconda del sistema operativo locale, per concedere agli script di configurazione le autorizzazioni necessarie:

    Eseguire questo comando con privilegi sufficienti:

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

  2. Aprire il progetto in Visual Studio Code:

    code .

Prima di poter eseguire l'app in locale, è necessario creare le risorse in Azure. Questo progetto non usa l'emulazione locale per Azure Cosmos DB.

Creare risorse di Azure

Questo progetto è configurato per usare il azd provision comando per creare un'app per le funzioni in un piano a consumo Flex, insieme ad altre risorse di Azure necessarie che seguono le procedure consigliate correnti.

  1. In Visual Studio Code premere F1 per aprire il riquadro comandi, cercare ed eseguire il comando Azure Developer CLI (azd): Sign In with Azure Developer CLIe quindi accedere usando l'account Azure.

  2. Premere F1 per aprire il riquadro comandi, cercare ed eseguire il comando Azure Developer CLI (azd): Provision Azure resources (provision) per creare le risorse di Azure necessarie:

  3. Quando richiesto nella finestra Terminale, specificare questi parametri di distribuzione obbligatori:

    Rapido Description
    Selezionare una sottoscrizione di Azure da usare Scegliere la sottoscrizione in cui si desidera creare le risorse.
    parametro di distribuzione per la località Area di Azure in cui creare il gruppo di risorse che contiene le nuove risorse di Azure. Vengono visualizzate solo le aree che attualmente supportano il piano a consumo Flex.
    Parametro di distribuzione vnetEnabled Mentre il modello supporta la creazione di risorse all'interno di una rete virtuale, per semplificare la distribuzione e i test, scegliere False.

    Il azd provision comando usa la risposta a questi prompt con i file di configurazione Bicep per creare e configurare queste risorse di Azure necessarie, seguendo le procedure consigliate più recenti:

    • Piano a consumo Flex e app per le funzioni
    • Account Azure Cosmos DB
    • Archiviazione di Azure (richiesta) e Application Insights (scelta consigliata)
    • Criteri di accesso e ruoli per l'account
    • Connessioni da servizio a servizio che usano identità gestite (anziché stringhe di connessione archiviate)

    Gli hook di post-provision generano anche il file local.settings.json necessario quando si esegue in locale. Questo file contiene anche le impostazioni necessarie per connettersi al database di Azure Cosmos DB in Azure.

    Suggerimento

    In caso di esito negativo dei passaggi durante il provisioning, è possibile rieseguire il azd provision comando dopo aver risolto eventuali problemi.

    Al termine del comando, è possibile eseguire il codice del progetto in locale e attivare il database di Azure Cosmos DB in Azure.

Eseguire la funzione in locale

Visual Studio Code si integra con gli strumenti di base di Funzioni di Azure per consentire di eseguire questo progetto nel computer di sviluppo locale prima di pubblicare nella nuova app per le funzioni in Azure.

  1. Premere F1 e nel riquadro comandi cercare ed eseguire il comando Azurite: Start.

  2. Per avviare la funzione in locale, premere F5 o l'icona Esegui e debug nella barra attività sul lato sinistro. Il pannello Terminale visualizza l'output di Core Tools. L'app viene avviata nel pannello Terminale ed è possibile visualizzare il nome della funzione in esecuzione in locale.

    In caso di problemi con l'esecuzione in Windows, assicurarsi che il terminale predefinito per Visual Studio Code non sia impostato su WSL Bash.

  3. Con Core Tools ancora in esecuzione nel terminale, premere F1 e nel riquadro comandi cercare ed eseguire il comando NoSQL: Create Item... e selezionare sia il document-db database che il documents contenitore.

  4. Sostituire il contenuto del nuovo file Item.json con questi dati JSON e selezionare Salva:

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

    Dopo aver selezionato Salva, viene visualizzata l'esecuzione della funzione nel terminale e il documento locale viene aggiornato per includere i metadati aggiunti dal servizio.

  5. Al termine, premere CTRL+C nella finestra del terminale per arrestare il processo host func.exe.

Esaminare il codice (facoltativo)

La funzione viene attivata in base al feed di modifiche in un database NoSQL di Azure Cosmos DB.

Queste variabili di ambiente configurano il modo in cui il trigger monitora il feed di modifiche:

  • COSMOS_CONNECTION__accountEndpoint: URI dell'endpoint dell'account Cosmos DB
  • COSMOS_DATABASE_NAME: nome del database da monitorare
  • COSMOS_CONTAINER_NAME: nome del contenitore da monitorare

Queste variabili di ambiente vengono create sia in Azure (impostazioni dell'app per le funzioni) che in locale (local.settings.json) durante l'operazione azd provision .

La COSMOS_CONNECTION variabile di ambiente configura l'endpoint dell'account Cosmos DB usato dal trigger. Questa variabile di ambiente viene creata sia in Azure (impostazioni dell'app per le funzioni) che in locale (local.settings.json) durante l'operazione di azd provision. I nomi di database e contenitori sono definiti nella configurazione del trigger.

È possibile esaminare il codice che definisce il trigger 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; }
    }
}

È possibile esaminare il progetto modello completo here.

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

È possibile esaminare il progetto modello completo here.

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

È possibile esaminare il progetto modello completo here.

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

È possibile esaminare il progetto modello completo here.

Il trigger viene definito in questo file function.json :

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

Il codice seguente viene eseguito quando il trigger viene eseguito:

param($InputDocuments, $TriggerMetadata)

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

È possibile esaminare il progetto modello completo here.

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.")

È possibile esaminare il progetto modello completo here.

Dopo aver esaminato e verificato il codice della funzione in locale, è possibile pubblicare il progetto in Azure.

Distribuzione su Azure

Puoi eseguire il comando azd deploy da Visual Studio Code per distribuire il codice del progetto alle risorse in Azure già configurate.

  1. Premere F1 per aprire il riquadro comandi.

  2. Cercare ed eseguire il comando Azure Developer CLI (azd): Deploy to Azure (deploy).

    Il azd deploy comando crea pacchetti e distribuisce il codice nel contenitore di distribuzione. L'app viene quindi avviata ed eseguita nel pacchetto distribuito.

    Al termine del comando, l'app viene eseguita in Azure.

Richiamare la funzione in Azure

  1. In Visual Studio Code premere F1 e nel riquadro comandi cercare ed eseguire il comando Azure: Open in portal, selezionare Function appe scegliere la nuova app. Se necessario, accedere con l'account Azure.

    Questo comando apre la nuova app per le funzioni nel portale di Azure.

  2. Nella scheda Panoramica della pagina principale, selezionare il nome della tua app per le funzioni e quindi la scheda Registri.

  3. Usare il NoSQL: Create Item comando in Visual Studio Code per aggiungere di nuovo un documento al contenitore come in precedenza.

  4. Verificare di nuovo che la funzione venga attivata da un aggiornamento nel contenitore monitorato.

Ridistribuire il codice

È possibile eseguire il azd deploy comando quante volte è necessario distribuire gli aggiornamenti del codice nell'app per le funzioni.

Annotazioni

I file di codice distribuiti vengono sempre sovrascritti dal pacchetto di distribuzione più recente.

Le risposte iniziali alle richieste di azd e a tutte le variabili di ambiente generate da azd, vengono archiviate localmente nell'ambiente denominato. Usare il comando azd env get-values per esaminare tutte le variabili nell'ambiente usato durante la creazione di risorse di Azure.

Pulire le risorse

Al termine dell'uso dell'app per le funzioni e delle risorse correlate, è possibile usare questo comando per eliminare l'app per le funzioni e le relative risorse da Azure ed evitare di sostenere ulteriori costi:

azd down --no-prompt

Annotazioni

L'opzione --no-prompt indica a azd di eliminare il gruppo di risorse senza conferma.

Questo comando non influisce sul progetto di codice locale.

Contenuti correlati

  • Last updated on