Výstupní vazba Azure Cosmos DB pro Azure Functions 2.x a vyšší

  • Článek

Výstupní vazba Služby Azure Cosmos DB umožňuje napsat nový dokument do databáze Azure Cosmos DB pomocí rozhraní SQL API.

Informace o nastavení a konfiguraci najdete v přehledu.

Důležité

Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Azure Functions podporuje dva programovací modely pro Python. Způsob, jakým definujete vazby, závisí na zvoleném programovacím modelu.

Programovací model Pythonu v2 umožňuje definovat vazby pomocí dekorátorů přímo v kódu funkce Pythonu. Další informace najdete v příručce pro vývojáře Pythonu.

Tento článek podporuje oba programovací modely.

Funkci jazyka C# je možné vytvořit pomocí jednoho z následujících režimů jazyka C#:

  • Izolovaný model pracovního procesu: Kompilovaná funkce jazyka C#, která běží v pracovním procesu, který je izolovaný od modulu runtime. Izolovaný pracovní proces je nutný pro podporu funkcí C# spuštěných na LTS a jiných verzích než LTS .NET a rozhraní .NET Framework. Rozšíření pro izolované funkce pracovních procesů používají Microsoft.Azure.Functions.Worker.Extensions.* obory názvů.
  • Model v procesu: Zkompilovaná funkce jazyka C#, která běží ve stejném procesu jako modul runtime služby Functions. Ve variantě tohoto modelu je možné spouštět funkce pomocí skriptování jazyka C#, což je podporováno především pro úpravy portálu C#. Rozšíření pro procesní funkce používají Microsoft.Azure.WebJobs.Extensions.* obory názvů.

Důležité

Podpora modelu v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovního procesu pro plnou podporu.

Příklad

Pokud není uvedeno jinak, příklady v tomto článku cílí na verzi 3.x rozšíření Azure Cosmos DB. Pro použití s rozšířením verze 4.x je nutné nahradit řetězec collection v názvech vlastností a atributů .containerconnection_string_settingconnection

Následující kód definuje MyDocument typ:

public class MyDocument
{
    public string Id { get; set; }

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

V následujícím příkladu je návratový IReadOnlyList<T>typ , což je upravený seznam dokumentů z parametru vazby triggeru:

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

namespace SampleApp
{
    public class CosmosDBFunction
    {
        private readonly ILogger<CosmosDBFunction> _logger;

        public CosmosDBFunction(ILogger<CosmosDBFunction> logger)
        {
            _logger = logger;
        }

        //<docsnippet_exponential_backoff_retry_example>
        [Function(nameof(CosmosDBFunction))]
        [ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
        [CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
        public object Run(
            [CosmosDBTrigger(
                "%CosmosDb%",
                "%CosmosContainerIn%",
                Connection = "CosmosDBConnection",
                LeaseContainerName = "leases",
                CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
            FunctionContext context)
        {
            if (input != null && input.Any())
            {
                foreach (var doc in input)
                {
                    _logger.LogInformation("Doc Id: {id}", doc.Id);
                }

                // Cosmos Output
                return input.Select(p => new { id = p.Id });
            }

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

Trigger fronty, uložení zprávy do databáze prostřednictvím návratové hodnoty

Následující příklad ukazuje funkci Java, která přidá dokument do databáze s daty ze zprávy ve službě Queue Storage.

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

Trigger HTTP, uložení jednoho dokumentu do databáze prostřednictvím návratové hodnoty

Následující příklad ukazuje funkci Java, jejíž podpis je opatřen poznámkami @CosmosDBOutput a má návratovou hodnotu typu String. Dokument JSON vrácený funkcí se automaticky zapíše do odpovídající kolekce Azure Cosmos DB.

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

Trigger HTTP, uložení jednoho dokumentu do databáze přes OutputBinding

Následující příklad ukazuje funkci Java, která zapisuje dokument do služby Azure Cosmos DB prostřednictvím výstupního parametru OutputBinding<T> . V tomto příkladu outputItem musí být parametr opatřen poznámkami @CosmosDBOutput, nikoli podpisem funkce. Použití OutputBinding<T> umožňuje funkci využít vazbu k zápisu dokumentu do služby Azure Cosmos DB a zároveň umožnit vrácení jiné hodnoty volajícímu funkce, jako je dokument JSON nebo XML.

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

Trigger HTTP, uložení více dokumentů do databáze prostřednictvím outputBinding

Následující příklad ukazuje funkci Java, která zapisuje více dokumentů do služby Azure Cosmos DB prostřednictvím výstupního parametru OutputBinding<T> . V tomto příkladu outputItem je parametr opatřen poznámkami, nikoli podpisem @CosmosDBOutputfunkce. Výstupní parametr outputItem má seznam ToDoItem objektů jako typ parametru šablony. Funkce OutputBinding<T> umožňuje využít vazbu k zápisu dokumentů do služby Azure Cosmos DB a zároveň umožnit vrácení jiné hodnoty volajícímu funkce, jako je dokument JSON nebo XML.

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

V knihovně modulu runtime funkcí Java použijte poznámku @CosmosDBOutput k parametrům, které budou zapsány do služby Azure Cosmos DB. Typ parametru poznámky by měl být OutputBinding<T>, kde T je buď nativním typem Javy, nebo POJO.

Následující příklad ukazuje frontu úložiště aktivovanou funkcí TypeScript pro frontu, která přijímá JSON v následujícím formátu:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Funkce pro každý záznam vytvoří dokumenty Azure Cosmos DB v následujícím formátu:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Tady je kód TypeScriptu:

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

interface MyQueueItem {
    name: string;
    employeeId: string;
    address: string;
}

interface MyCosmosItem {
    id: string;
    name: string;
    employeeId: string;
    address: string;
}

export async function storageQueueTrigger1(queueItem: MyQueueItem, context: InvocationContext): Promise<MyCosmosItem> {
    return {
        id: `${queueItem.name}-${queueItem.employeeId}`,
        name: queueItem.name,
        employeeId: queueItem.employeeId,
        address: queueItem.address,
    };
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: output.cosmosDB({
        databaseName: 'MyDatabase',
        collectionName: 'MyCollection',
        createIfNotExists: true,
        connectionStringSetting: 'MyAccount_COSMOSDB',
    }),
    handler: storageQueueTrigger1,
});

Pokud chcete vytvořit výstup více dokumentů, vraťte místo jednoho objektu pole. Příklad:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

Následující příklad ukazuje funkci JavaScriptu aktivovanou frontou úložiště pro frontu, která přijímá JSON v následujícím formátu:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Funkce pro každý záznam vytvoří dokumenty Azure Cosmos DB v následujícím formátu:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Tady je javascriptový kód:

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

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: true,
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: cosmosOutput,
    handler: (queueItem, context) => {
        return {
            id: `${queueItem.name}-${queueItem.employeeId}`,
            name: queueItem.name,
            employeeId: queueItem.employeeId,
            address: queueItem.address,
        };
    },
});

Pokud chcete vytvořit výstup více dokumentů, vraťte místo jednoho objektu pole. Příklad:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

Následující příklad ukazuje, jak zapisovat data do služby Azure Cosmos DB pomocí výstupní vazby. Vazba je deklarována v konfiguračním souboru funkce (functions.json) a přebírá data ze zprávy fronty a zapisuje se do dokumentu azure Cosmos DB.

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
}

V souboru run.ps1 je objekt vrácený z funkce mapován na EmployeeDocument objekt, který je trvalý v databázi.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

Následující příklad ukazuje, jak napsat dokument do databáze Azure Cosmos DB jako výstup funkce. Tento příklad závisí na tom, jestli používáte programovací model v1 nebo v2 Pythonu.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

Atributy

Knihovny C# v procesu i izolovaného pracovního procesu používají atributy k definování funkce. Skript jazyka C# místo toho používá konfigurační soubor function.json, jak je popsáno v průvodci skriptováním jazyka C#.

Vlastnost atributu Popis
Připojení Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k monitorovanému účtu služby Azure Cosmos DB. Další informace najdete v tématu Připojení iony.
Databasename Název databáze Azure Cosmos DB s monitorovaným kontejnerem.
Název kontejneru Název monitorovaného kontejneru.
CreateIfNotExists Logická hodnota označující, jestli se kontejner vytvoří, když neexistuje. Výchozí hodnota je false , protože se vytvoří nové kontejnery s rezervovanou propustností, což má vliv na náklady. Další informace naleznete v části Stránka s cenami.
PartitionKey Pokud CreateIfNotExists je hodnota true, definuje cestu klíče oddílu pro vytvořený kontejner. Může obsahovat parametry vazby.
ContainerThroughput Pokud CreateIfNotExists je hodnota true, definuje propustnost vytvořeného kontejneru.
PreferredLocations (Volitelné) Definuje upřednostňovaná umístění (oblasti) pro geograficky replikované databázové účty ve službě Azure Cosmos DB. Hodnoty by měly být oddělené čárkami. Například East US,South Central US,North Europe.

Dekoratéry

Platí pouze pro programovací model Pythonu v2.

Pro funkce Pythonu v2 definované pomocí dekorátoru následující vlastnosti:cosmos_db_output

Vlastnost Popis
arg_name Název proměnné použitý v kódu funkce, který představuje seznam dokumentů se změnami.
database_name Název databáze Azure Cosmos DB s monitorovanou kolekcí.
collection_name Název monitorované kolekce Azure Cosmos DB.
create_if_not_exists Logická hodnota, která označuje, jestli se má databáze a kolekce vytvořit, pokud neexistují.
connection_string_setting Monitorovaná připojovací řetězec služby Azure Cosmos DB.

Informace o funkcích Pythonu definovaných pomocí function.json najdete v části Konfigurace .

Poznámky

V knihovně modulu runtime funkcí Java použijte poznámku @CosmosDBOutput k parametrům, které zapisuje do služby Azure Cosmos DB. Poznámka podporuje následující vlastnosti:

Konfigurace

Platí pouze pro programovací model Pythonu v1.

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě output.cosmosDB() . Funkce type, directiona name vlastnosti se nevztahují na model v4.

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json , kde se vlastnosti liší podle verze rozšíření:

vlastnost function.json Popis
Připojení Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k monitorovanému účtu služby Azure Cosmos DB. Další informace najdete v tématu Připojení iony.
Databasename Název databáze Azure Cosmos DB s monitorovaným kontejnerem.
containerName Název monitorovaného kontejneru.
createIfNotExists Logická hodnota označující, jestli se kontejner vytvoří, když neexistuje. Výchozí hodnota je false , protože se vytvoří nové kontejnery s rezervovanou propustností, což má vliv na náklady. Další informace naleznete v části Stránka s cenami.
partitionKey Pokud createIfNotExists je hodnota true, definuje cestu klíče oddílu pro vytvořený kontejner. Může obsahovat parametry vazby.
containerThroughput Pokud createIfNotExists je hodnota true, definuje propustnost vytvořeného kontejneru.
preferredLocations (Volitelné) Definuje upřednostňovaná umístění (oblasti) pro geograficky replikované databázové účty ve službě Azure Cosmos DB. Hodnoty by měly být oddělené čárkami. Například East US,South Central US,North Europe.

Kompletní příklady najdete v části Příklad.

Využití

Ve výchozím nastavení se při zápisu do výstupního parametru ve funkci vytvoří dokument ve vaší databázi. ID dokumentu výstupního dokumentu byste měli zadat zadáním id vlastnosti v objektu JSON předaného výstupnímu parametru.

Poznámka:

Když zadáte ID existujícího dokumentu, přepíše se novým výstupním dokumentem.

Typ parametru podporovaný výstupní vazbou Cosmos DB závisí na verzi modulu runtime služby Functions, verzi balíčku rozšíření a použitém režimu jazyka C#.

Pokud chcete, aby funkce zapisuje do jednoho dokumentu, výstupní vazba Cosmos DB může svázat s následujícími typy:

Typ Popis
Serializovatelné typy JSON Objekt představující obsah JSON dokumentu. Funkce se pokusí serializovat prostý starý typ objektu CLR (POCO) do dat JSON.

Pokud chcete, aby funkce zapisovat do více dokumentů, výstupní vazba Cosmos DB může svázat s následujícími typy:

Typ Popis
T[] where T is JSON serializable type Pole obsahující více dokumentů. Každá položka představuje jeden dokument.

V případě jiných výstupních scénářů vytvořte a používejte typy přímo z Microsoft.Azure.Cosmos .

Propojení

leaseConnectionleaseConnectionStringSetting/Vlastnosti connectionStringSetting/connection jsou odkazy na konfiguraci prostředí, která určuje, jak se má aplikace připojit ke službě Azure Cosmos DB. Můžou zadat:

Pokud je nakonfigurovaná hodnota přesná shoda pro jedno nastavení i shodu předpony pro jiná nastavení, použije se přesná shoda.

Connection string

Připojovací řetězec pro váš databázový účet by měl být uložen v nastavení aplikace s názvem, který odpovídá hodnotě určené vlastností připojení konfigurace vazby.

Připojení založená na identitách

Pokud používáte rozšíření verze 4.x nebo vyšší, můžete místo použití připojovací řetězec s tajným kódem použít aplikaci identitu Microsoft Entra. Uděláte to tak, že nastavení definujete pod společnou předponou, která je v konfiguraci triggeru a vazeb namapovaná na vlastnost připojení.

V tomto režimu rozšíření vyžaduje následující vlastnosti:

Vlastnost Šablona proměnné prostředí Popis Příklad hodnoty
Koncový bod účtu <CONNECTION_NAME_PREFIX>__accountEndpoint Identifikátor URI koncového bodu účtu služby Azure Cosmos DB. <https:// database_account_name.documents.azure.com:443/>

Pro přizpůsobení připojení je možné nastavit další vlastnosti. Viz Běžné vlastnosti pro připojení založená na identitě.

Při hostovaní ve službě Azure Functions používají připojení založená na identitách spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když je možné zadat identitu přiřazenou uživatelem s vlastnostmi a clientID vlastnostmicredential. Všimněte si, že konfigurace identity přiřazené uživatelem s ID prostředku se nepodporuje . Při spuštění v jiných kontextech, jako je místní vývoj, se místo toho použije vaše identita vývojáře, i když je možné ji přizpůsobit. Viz Místní vývoj s připojeními založenými na identitách.

Udělení oprávnění identitě

Jakákoli identita, kterou používáte, musí mít oprávnění k provedení zamýšlených akcí. U většiny služeb Azure to znamená, že potřebujete přiřadit roli v Azure RBAC pomocí předdefinovaných nebo vlastních rolí, které tato oprávnění poskytují.

Důležité

Cílová služba může zpřístupnit některá oprávnění, která nejsou nutná pro všechny kontexty. Pokud je to možné, dodržujte zásadu nejnižšího oprávnění a udělte identitě pouze požadovaná oprávnění. Pokud například aplikace potřebuje jen číst ze zdroje dat, použijte roli, která má oprávnění jen ke čtení. Přiřazení role, která také umožňuje zápis do této služby, by bylo nevhodné, protože by to bylo nadměrné oprávnění pro operaci čtení. Podobně byste chtěli zajistit, aby přiřazení role bylo vymezeno pouze nad prostředky, které je potřeba číst.

Cosmos DB nepoužívá Azure RBAC pro operace s daty. Místo toho používá integrovaný systém RBAC služby Cosmos DB, který je založený na podobných konceptech. Budete muset vytvořit přiřazení role, které poskytuje přístup k vašemu databázovému účtu za běhu. Role správy Azure RBAC, jako je vlastník , nestačí. Následující tabulka ukazuje předdefinované role, které se doporučují při použití rozšíření Azure Cosmos DB v normálním provozu. Vaše aplikace může vyžadovat další oprávnění na základě kódu, který napíšete.

Typ vazby Příklad předdefinovaných rolí1
Aktivační událost2 Integrovaný přispěvatel dat ve službě Cosmos DB
Vstupní vazba Integrovaná čtečka dat ve službě Cosmos DB
Výstupní vazba Integrovaný přispěvatel dat ve službě Cosmos DB

1 Tyto role nelze použít v přiřazení role Azure RBAC. Podrobnosti o přiřazování těchto rolí najdete v integrované dokumentaci k systému RBAC služby Cosmos DB.

2 Při použití identity služba Cosmos DB považuje vytvoření kontejneru za operaci správy. Není k dispozici jako operace roviny dat pro trigger. Před nastavením funkce budete muset zajistit, abyste vytvořili kontejnery potřebné triggerem (včetně kontejneru zapůjčení).

Výjimky a návratové kódy

Vazba Reference
Azure Cosmos DB Stavové kódy HTTP pro službu Azure Cosmos DB

Další kroky