Připojení Azure Functions do služby Azure Cosmos DB pomocí editoru Visual Studio Code

Azure Functions umožňuje připojit služby Azure a další prostředky k funkcím, aniž byste museli psát vlastní integrační kód. Tyto vazby, které představují vstup i výstup, jsou deklarovány v rámci definice funkce. Data z vazeb má funkce k dispozici jako parametry. Trigger je speciální typ vstupní vazby. I když má funkce pouze jeden trigger, může mít více vstupních a výstupních vazeb. Další informace najdete v tématu Koncepty triggerů a vazeb Azure Functions.

V tomto článku se dozvíte, jak pomocí editoru Visual Studio Code připojit službu Azure Cosmos DB k funkci, kterou jste vytvořili v předchozím článku rychlého startu. Výstupní vazba, kterou do této funkce přidáte, zapisuje data z požadavku HTTP do dokumentu JSON uloženého v kontejneru Azure Cosmos DB.

Než začnete, musíte dokončit rychlý start: Vytvoření funkce jazyka C# v Azure pomocí editoru Visual Studio Code. Pokud jste už vyčistili prostředky na konci tohoto článku, projděte si kroky znovu a znovu vytvořte aplikaci funkcí a související prostředky v Azure.

Než začnete, musíte dokončit rychlý start: Vytvoření funkce JavaScriptu v Azure pomocí editoru Visual Studio Code. Pokud jste už vyčistili prostředky na konci tohoto článku, projděte si kroky znovu a znovu vytvořte aplikaci funkcí a související prostředky v Azure.

Poznámka:

Tento článek aktuálně podporuje pouze Node.js v3 pro funkce.

Než začnete, musíte dokončit rychlý start: Vytvoření funkce Pythonu v Azure pomocí editoru Visual Studio Code. Pokud jste už vyčistili prostředky na konci tohoto článku, projděte si kroky znovu a znovu vytvořte aplikaci funkcí a související prostředky v Azure.

Konfigurujte své prostředí

Než začnete, nezapomeňte nainstalovat rozšíření Azure Databases pro Visual Studio Code.

Vytvoření účtu služby Azure Cosmos DB

Teď vytvoříte účet služby Azure Cosmos DB jako typ bezserverového účtu. Díky tomuto režimu založenému na spotřebě je Azure Cosmos DB silnou možností pro bezserverové úlohy.

1. V editoru Visual Studio Code vyberte Zobrazit>paletu příkazů... pak na paletě příkazů vyhledejteAzure Databases: Create Server...

2. Podle pokynů na obrazovce zadejte tyto informace:

   Instrukce	Výběr
   Výběr databázového serveru Azure	Zvolte Core (NoSQL) a vytvořte databázi dokumentů, na kterou můžete dotazovat pomocí syntaxe SQL nebo dotazu Copilot (Preview), který převádí výzvy přirozeného jazyka na dotazy. Přečtěte si další informace o službě Azure Cosmos DB.
   Název účtu	Zadejte jedinečný název, který identifikuje váš účet služby Azure Cosmos DB. Název účtu může používat jenom malá písmena, číslice a pomlčky (-) a musí mít délku 3 až 31 znaků.
   Výběr modelu kapacity	Vyberte Bezserverový účet a vytvořte účet v bezserverovém režimu.
   Výběr skupiny prostředků pro nové prostředky	Zvolte skupinu prostředků, ve které jste vytvořili aplikaci funkcí v předchozím článku.
   Výběr umístění pro nové prostředky	Vyberte zeměpisné umístění, ve kterém chcete účet služby Azure Cosmos DB hostovat. Použijte umístění, které je vám nebo vašim uživatelům nejblíže, abyste získali nejrychlejší přístup k vašim datům.

   Po zřízení nového účtu se v oznamovací oblasti zobrazí zpráva.

Vytvoření databáze a kontejneru Azure Cosmos DB

1. Na panelu aktivit vyberte ikonu Azure, rozbalte položku Prostředky>Azure Cosmos DB, klikněte pravým tlačítkem (Ctrl+vyberte v systému macOS) svůj účet a vyberte Vytvořit databázi....

2. Podle pokynů na obrazovce zadejte tyto informace:

   Instrukce	Výběr
   Název databáze	Zadejte my-database.
   Zadejte a ID kolekce.	Zadejte my-container.
   Zadejte klíč oddílu pro kolekci.	Zadejte /id jako klíč oddílu.

3. Vyberte OK a vytvořte kontejner a databázi.

Aktualizace nastavení aplikace funkcí

V předchozím článku rychlého startu jste vytvořili aplikaci funkcí v Azure. V tomto článku aktualizujete aplikaci tak, aby zapisuje dokumenty JSON do kontejneru Azure Cosmos DB, který jste vytvořili. Pokud se chcete připojit ke svému účtu služby Azure Cosmos DB, musíte do nastavení aplikace přidat jeho připojovací řetězec. Pak si nové nastavení stáhnete do souboru local.settings.json, abyste se mohli připojit ke svému účtu služby Azure Cosmos DB při místním spuštění.

1. V editoru Visual Studio Code klikněte pravým tlačítkem myši (Ctrl+vyberte v systému macOS) na nový účet služby Azure Cosmos DB a vyberte Kopírovat Připojení ion String.

   

2. Stisknutím klávesy F1 otevřete paletu příkazů a pak vyhledejte a spusťte příkaz Azure Functions: Add New Setting....

3. Zvolte aplikaci funkcí, kterou jste vytvořili v předchozím článku. Podle pokynů na obrazovce zadejte tyto informace:

   Instrukce	Výběr
   Zadejte název nového nastavení aplikace.	Zadejte CosmosDbConnectionSetting.
   Zadejte hodnotu pro CosmosDb Připojení ionSetting.	Vložte připojovací řetězec zkopírovaného účtu služby Azure Cosmos DB. Identitu Microsoft Entra můžete také nakonfigurovat jako alternativu.

   Tím se v aplikaci funkcí v Azure vytvoří nastavení aplikace s názvem připojení CosmosDbConnectionSetting . Teď si toto nastavení můžete stáhnout do souboru local.settings.json.

4. Opětovným stisknutím klávesy F1 otevřete paletu příkazů a pak vyhledejte a spusťte příkaz Azure Functions: Download Remote Settings....

5. Zvolte aplikaci funkcí, kterou jste vytvořili v předchozím článku. Chcete-li přepsat stávající místní nastavení, vyberte možnost Ano.

Tím se stáhne všechna nastavení z Azure do místního projektu, včetně nového nastavení připojovací řetězec. Většina stažených nastavení se při místním spuštění nepoužívá.

Registrace rozšíření vazeb

Vzhledem k tomu, že používáte výstupní vazbu Azure Cosmos DB, musíte mít před spuštěním projektu nainstalované odpovídající rozšíření vazeb.

Kromě triggerů HTTP a časovače se vazby implementují jako balíčky rozšíření. Spuštěním následujícího příkazu dotnet add package v okně terminálu přidejte do projektu balíček rozšíření Azure Cosmos DB.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

Váš projekt je nakonfigurovaný tak, aby používal sady rozšíření, které automaticky nainstaluje předdefinovanou sadu balíčků rozšíření.

Využití sad rozšíření je povolené v souboru host.json v kořenovém adresáři projektu, který se zobrazí takto:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  } 
}

Teď můžete do projektu přidat výstupní vazbu Azure Cosmos DB.

Přidání výstupní vazby

V projektu knihovny tříd jazyka C# jsou vazby definovány jako atributy vazby v metodě funkce.

Otevřete soubor projektu HttpExample.cs a přidejte následující třídy:

public class MultiResponse
{
    [CosmosDBOutput("my-database", "my-container",
        Connection = "CosmosDbConnectionSetting", CreateIfNotExists = true)]
    public MyDocument Document { get; set; }
    public HttpResponseData HttpResponse { get; set; }
}
public class MyDocument {
    public string id { get; set; }
    public string message { get; set; }
}

Třída MyDocument definuje objekt, který se zapíše do databáze. Vlastnost nastaví Connection připojovací řetězec pro účet úložiště. V tomto případě byste mohli vynechat Connection , protože už používáte výchozí účet úložiště.

Třída MultiResponse umožňuje jak zapisovat do zadané kolekce ve službě Azure Cosmos DB, tak vrátit zprávu o úspěchu protokolu HTTP. Protože potřebujete vrátit MultiResponse objekt, musíte také aktualizovat podpis metody.

Konkrétní atributy určují název kontejneru a název nadřazené databáze. Připojovací řetězec pro váš účet služby Azure Cosmos DB je nastavena nástrojem CosmosDbConnectionSetting.

Atributy vazby jsou definovány přímo v souboru function.json . V závislosti na typu vazby mohou být vyžadovány další vlastnosti. Konfigurace výstupu služby Azure Cosmos DB popisuje pole požadovaná pro výstupní vazbu Azure Cosmos DB. Rozšíření usnadňuje přidávání vazeb do souboru function.json .

Pokud chcete vytvořit vazbu, klikněte pravým tlačítkem myši (Ctrl+vyberte v systému macOS) na soubor function.json ve složce HttpTrigger a zvolte Přidat vazbu.... Podle pokynů definujte následující vlastnosti vazby pro novou vazbu:

Instrukce	Hodnota	Popis
Výběr směru vazby	out	Vazba je výstupní vazba.
Výběr vazby se směrem "out"	Azure Cosmos DB	Vazba je vazba Azure Cosmos DB.
Název použitý k identifikaci této vazby v kódu	outputDocument	Název, který identifikuje parametr vazby odkazovaný v kódu.
Databáze Azure Cosmos DB, ve které se budou zapisovat data	my-database	Název databáze Azure Cosmos DB obsahující cílový kontejner.
Kolekce databází, ve které se budou zapisovat data	my-container	Název kontejneru Azure Cosmos DB, do kterého se zapíšou dokumenty JSON.
Pokud je hodnota true, vytvoří databázi a kolekci Azure Cosmos DB.	false	Cílová databáze a kontejner již existují.
Výběr nastavení z local.setting.json	CosmosDbConnectionSetting	Název nastavení aplikace, které obsahuje připojovací řetězec pro účet služby Azure Cosmos DB.
Klíč oddílu (volitelné)	nechejte prázdné	Vyžaduje se pouze v případě, že výstupní vazba vytvoří kontejner.
Propustnost kolekce (nepovinné)	nechejte prázdné	Vyžaduje se pouze v případě, že výstupní vazba vytvoří kontejner.

Do pole v function.json se přidá bindings vazba, která by po odebrání všech undefined hodnot měla vypadat takto:

{
    "type": "cosmosDB",
    "direction": "out",
    "name": "outputDocument",
    "databaseName": "my-database",
    "containerName": "my-container",
    "createIfNotExists": "false",
    "connection": "CosmosDbConnectionSetting"
}

Atributy vazby jsou definovány přímo v souboru function_app.py . Dekorátor použijete cosmos_db_output k přidání výstupní vazby Azure Cosmos DB:

@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", 
    container_name="my-container", connection="CosmosDbConnectionSetting")

V tomto kódu identifikuje parametr vazby, na který odkazuje váš kód, database_name a container_name jedná se o názvy databází a kolekcí, do kterých se vazba zapisuje, a connection je název nastavení aplikace, arg_name které obsahuje připojovací řetězec pro účet služby Azure Cosmos DB, který je v CosmosDbConnectionSetting nastavení v souboru local.settings.json.

Přidání kódu, který používá výstupní vazbu

Nahraďte existující metodu Run následujícím kódem:

[Function("HttpExample")]
public static MultiResponse Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger("HttpExample");
    logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = "Welcome to Azure Functions!";

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString(message);

    // Return a response to both HTTP trigger and Azure Cosmos DB output binding.
    return new MultiResponse()
    {
         Document = new MyDocument
        {
            id = System.Guid.NewGuid().ToString(),
            message = message
        },
        HttpResponse = response
    };
}

Přidejte kód, který používá outputDocument objekt context.bindings výstupní vazby k vytvoření dokumentu JSON. Přidejte tento kód před context.res příkaz.

if (name) {
    context.bindings.outputDocument = JSON.stringify({
        // create a random ID
        id: new Date().toISOString() + Math.random().toString().substring(2, 10),
        name: name
    });
}

V tomto okamžiku by vaše funkce měla vypadat takto:

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    const name = (req.query.name || (req.body && req.body.name));
    const responseMessage = name
        ? "Hello, " + name + ". This HTTP triggered function executed successfully."
        : "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.";

    if (name) {
        context.bindings.outputDocument = JSON.stringify({
            // create a random ID
            id: new Date().toISOString() + Math.random().toString().substring(2, 10),
            name: name
        });
    }

    context.res = {
        // status: 200, /* Defaults to 200 */
        body: responseMessage
    };
}

Tento kód teď vrátí MultiResponse objekt, který obsahuje dokument i odpověď HTTP.

Aktualizujte httpExample\function_app.py tak, aby odpovídaly následujícímu kódu. outputDocument Přidejte parametr do definice funkce a outputDocument.set() pod if name: příkaz:

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", container_name="my-container", connection="CosmosDbConnectionSetting")
def test_function(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
    outputDocument: func.Out[func.Document]) -> func.HttpResponse:
     logging.info('Python HTTP trigger function processed a request.')
     logging.info('Python Cosmos DB trigger function processed a request.')
     name = req.params.get('name')
     if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

     if name:
        outputDocument.set(func.Document.from_dict({"id": name}))
        msg.set(name)
        return func.HttpResponse(f"Hello {name}!")
     else:
        return func.HttpResponse(
                    "Please pass a name on the query string or in the request body",
                    status_code=400
                )

Dokument {"id": "name"} se vytvoří v kolekci databáze zadané v vazbě.

Místní spuštění funkce

Visual Studio Code se integruje s nástroji Azure Functions Core, které vám umožní spustit tento projekt na místním vývojovém počítači před publikováním do Azure. Pokud ještě nemáte nástroje Core Tools nainstalované místně, zobrazí se výzva k jeho instalaci při prvním spuštění projektu.

1. Pokud chcete volat funkci, stisknutím klávesy F5 spusťte projekt aplikace funkcí. Na panelu Terminálu se zobrazí výstup nástrojů Core Tools. Aplikace se spustí na panelu Terminálu . Zobrazí se koncový bod adresy URL funkce aktivované protokolem HTTP spuštěné místně.

   

   Pokud ještě nemáte nainstalované Nástroje Core Tools, po zobrazení výzvy k instalaci nástrojů Core Tools vyberte Nainstalovat .
   Pokud máte potíže se spuštěním ve Windows, ujistěte se, že výchozí terminál pro Visual Studio Code není nastavený na WSL Bash.

2. Se spuštěnými nástroji Core Tools přejděte do oblasti Azure: Functions . V části Funkce rozbalte položku Místní projektové>funkce. Klikněte pravým tlačítkem myši (Windows) nebo Ctrl – klikněte na funkci (macOS) HttpExample a zvolte Spustit funkci nyní....

   

3. V textu požadavku Enter stiskněte Enter a odešlete do funkce zprávu požadavku.

4. Když se funkce spustí místně a vrátí odpověď, v editoru Visual Studio Code se vyvolá oznámení. Informace o provádění funkce se zobrazují na panelu Terminálu .

5. Stisknutím kombinace kláves Ctrl+C zastavte nástroje Core Tools a odpojte ladicí program.

Místní spuštění funkce

1. Stejně jako v předchozím článku spusťte stisknutím klávesy F5 projekt aplikace funkcí a nástroje Core Tools.

2. Se spuštěnými nástroji Core Tools přejděte do oblasti Azure: Functions . V části Funkce rozbalte položku Místní projektové>funkce. Klikněte pravým tlačítkem myši (ctrl klikněte na Mac) HttpExample funkci a zvolte Spustit funkci nyní....

   

3. V části Zadejte text požadavku uvidíte textovou hodnotu { "name": "Azure" }zprávy požadavku . Stisknutím klávesy Enter odešlete tuto zprávu požadavku do funkce.

4. Po vrácení odpovědi stiskněte Ctrl+C a zastavte nástroje Core Tools.

Ověření vytvoření dokumentu JSON

1. Na webu Azure Portal se vraťte ke svému účtu služby Azure Cosmos DB a vyberte Průzkumník dat.

2. Rozbalte databázi a kontejner a vyberte Položky , které zobrazí seznam dokumentů vytvořených v kontejneru.

3. Ověřte, že výstupní vazba vytvořila nový dokument JSON.

   

Opětovné nasazení a ověření aktualizované aplikace

1. V editoru Visual Studio Code stisknutím klávesy F1 otevřete paletu příkazů. Na paletě příkazů vyhledejte a vyberte Azure Functions: Deploy to function app....

2. Zvolte aplikaci funkcí, kterou jste vytvořili v prvním článku. Vzhledem k tomu, že projekt znovu nasazujete do stejné aplikace, zavřete upozornění na přepsání souborů výběrem možnosti Deploy (Nasadit ).

3. Po dokončení nasazení můžete znovu použít funkci Execute Function Now... k aktivaci funkce v Azure.

4. Znovu zkontrolujte dokumenty vytvořené v kontejneru Azure Cosmos DB a ověřte, že výstupní vazba znovu vygeneruje nový dokument JSON.

Vyčištění prostředků

Prostředky v Azure odkazují na aplikace funkcí, funkce, účty úložiště atd. Jsou seskupené do skupin prostředků a můžete odstranit všechno ve skupině odstraněním skupiny.

Vytvořili jste prostředky k dokončení těchto rychlých startů. Tyto prostředky se vám můžou účtovat v závislosti na stavu vašeho účtu a cenách služeb. Pokud prostředky už nepotřebujete, můžete k jejich odstranění použít tento postup:

1. V editoru Visual Studio Code stisknutím klávesy F1 otevřete paletu příkazů. Na paletě příkazů vyhledejte a vyberte Azure: Open in portal.

2. Zvolte aplikaci funkcí a stiskněte Enter. Otevře se stránka aplikace funkcí na webu Azure Portal.

3. Na kartě Přehled vyberte pojmenovaný odkaz vedle skupiny prostředků.

   

4. Na stránce Skupina prostředků zkontrolujte seznam zahrnutých prostředků a ověřte, že se jedná o prostředky, které chcete odstranit.

5. Vyberte Odstranit skupinu prostředků a postupujte podle pokynů.

   Odstranění může trvat několik minut. Po jeho dokončení se na několik sekund zobrazí oznámení. K zobrazení tohoto oznámení můžete také vybrat ikonu zvonku v horní části stránky.

Další kroky

Aktualizovali jste funkci aktivovanou protokolem HTTP tak, aby zapisovala dokumenty JSON do kontejneru Azure Cosmos DB. Teď se můžete dozvědět více o vývoji funkcí pomocí editoru Visual Studio Code:

• Vývoj azure Functions pomocí editoru Visual Studio Code

• Triggery a vazby Azure Functions

• Příklady kompletních projektů funkcí v jazyce C#.

• Referenční informace pro vývojáře v jazyce C# pro Azure Functions

• Příklady kompletních projektů funkcí v JavaScriptu

• Azure Functions – Příručka pro vývojáře v JavaScriptu

• Příklady kompletních projektů funkcí v Pythonu

• Azure Functions – Příručka pro vývojáře v Pythonu