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

Článek
06/13/2024

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ů .container connection_string_setting connection

Izolovaný model pracovního procesu
Model v procesu

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

Tato část obsahuje následující příklady:

Trigger fronty, napsání jednoho dokumentu
Trigger fronty, napsání jednoho dokumentu (rozšíření v4)
Trigger fronty, zápis dokumentů pomocí IAsyncCollectoru

Příklady odkazují na jednoduchý ToDoItem typ:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

Trigger fronty, napsání jednoho dokumentu

Následující příklad ukazuje funkci jazyka C#, která přidá dokument do databáze pomocí dat zadaných ve zprávě z Queue Storage.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Trigger fronty, napsání jednoho dokumentu (rozšíření v4)

Aplikace používající rozšíření Azure Cosmos DB verze 4.x nebo vyšší budou mít různé vlastnosti atributů, které jsou uvedené níže. Následující příklad ukazuje funkci jazyka C#, která přidá dokument do databáze pomocí dat zadaných ve zprávě z Queue Storage.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Trigger fronty, zápis dokumentů pomocí IAsyncCollectoru

Následující příklad ukazuje funkci jazyka C#, která přidá kolekci dokumentů do databáze pomocí dat zadaných ve formátu JSON zprávy fronty.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

Trigger fronty, uložení zprávy do databáze prostřednictvím návratové hodnoty
Trigger HTTP, uložení jednoho dokumentu do databáze prostřednictvím návratové hodnoty
Trigger HTTP, uložení jednoho dokumentu do databáze přes OutputBinding
Trigger HTTP, uložení více dokumentů do databáze prostřednictvím outputBinding

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.

Model v4
Model v3

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',
    },
];

Model v4
Model v3

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 výstupní vazbu Azure Cosmos DB v souboru function.json a funkci JavaScriptu, která používá vazbu. Funkce používá vstupní vazbu fronty 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 jsou data vazby v souboru function.json :

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

Oddíl konfigurace vysvětluje tyto vlastnosti.

Tady je javascriptový kód:

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

V případě hromadného vložení nejprve vytvořte objekty a spusťte funkci stringify. Tady je javascriptový kód:

    module.exports = async function (context) {

        context.bindings.employeeDocument = JSON.stringify([
        {
            "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'

Definice vazby je definována v function.json kde typ je nastaven na cosmosDB.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

Chcete-li zapisovat do databáze, předejte objekt set dokumentu metodě parametru databáze.

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.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í.
Název databáze	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`.

Vlastnost atributu	Popis
ConnectionStringSetting	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í.
Název databáze	Název databáze Azure Cosmos DB s monitorovanou kolekcí.
Název kolekce	Název monitorované kolekce.
CreateIfNotExists	Logická hodnota označující, jestli se kolekce vytvoří, když neexistuje. Výchozí hodnota je false , protože se vytvářejí nové kolekce 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řenou kolekci. Může obsahovat parametry vazby.
CollectionThroughput	Pokud `CreateIfNotExists` je hodnota true, definuje propustnost vytvořené kolekce.
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`.
UseMultipleWriteLocations	(Volitelné) Pokud je tato možnost nastavená na `true` spolu s `PreferredLocations`, podporuje zápisy do více oblastí ve službě Azure Cosmos DB.

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í.
Název databáze	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`.

Vlastnost atributu	Popis
ConnectionStringSetting	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í.
Název databáze	Název databáze Azure Cosmos DB s monitorovanou kolekcí.
Název kolekce	Název monitorované kolekce.
CreateIfNotExists	Logická hodnota označující, jestli se kolekce vytvoří, když neexistuje. Výchozí hodnota je false , protože se vytvářejí nové kolekce 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řenou kolekci. Může obsahovat parametry vazby.
CollectionThroughput	Pokud `CreateIfNotExists` je hodnota true, definuje propustnost vytvořené kolekce.
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`.
UseMultipleWriteLocations	(Volitelné) Pokud je tato možnost nastavená na `true` spolu s `PreferredLocations`, podporuje zápisy do více oblastí ve službě Azure Cosmos DB.

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.

Model v4
Model v3

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í:

Rozšíření 4.x+
Funkce 2.x+

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í.
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`.

vlastnost function.json	Popis
connectionStringSetting	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í.
databaseName	Název databáze Azure Cosmos DB s monitorovanou kolekcí.
collectionName	Název monitorované kolekce.
createIfNotExists	Logická hodnota označující, jestli se kolekce vytvoří, když neexistuje. Výchozí hodnota je false , protože se vytvářejí nové kolekce 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řenou kolekci. Může obsahovat parametry vazby.
collectionThroughput	Pokud `createIfNotExists` je hodnota true, definuje propustnost vytvořené kolekce.
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`.
useMultipleWriteLocations	(Volitelné) Pokud je tato možnost nastavená na `true` spolu s `preferredLocations`, podporuje zápisy do více oblastí ve službě Azure Cosmos DB.

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í

leaseConnection leaseConnectionStringSetting/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:

Název nastavení aplikace obsahující připojovací řetězec
Název sdílené předpony pro více nastavení aplikace, společně definující připojení založené na identitě. Tato možnost je k dispozici pouze pro connection verze a leaseConnection verze z verze 4.x nebo vyšší rozšíření.

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í¹
Aktivační událost²	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

¹ 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.

² 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

Sdílet prostřednictvím

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

Příklad

Trigger fronty, napsání jednoho dokumentu

Trigger fronty, napsání jednoho dokumentu (rozšíření v4)

Trigger fronty, zápis dokumentů pomocí IAsyncCollectoru

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

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

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

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

Atributy

Dekoratéry

Poznámky

Konfigurace

Využití

Propojení

Connection string

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

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

Výjimky a návratové kódy

Další kroky

Váš názor

Další materiály