Dela via

Azure Cosmos DB-utdatabindning för Azure Functions 2.x och senare

  • Artikel

Med Azure Cosmos DB-utdatabindningen kan du skriva ett nytt dokument till en Azure Cosmos DB-databas med sql-API:et.

Information om konfiguration och konfigurationsinformation finns i översikten.

Viktigt!

Den här artikeln använder flikar för att stödja flera versioner av Node.js programmeringsmodellen. V4-modellen är allmänt tillgänglig och är utformad för att ha en mer flexibel och intuitiv upplevelse för JavaScript- och TypeScript-utvecklare. Mer information om hur v4-modellen fungerar finns i utvecklarguiden för Azure Functions Node.js. Mer information om skillnaderna mellan v3 och v4 finns i migreringsguiden.

Azure Functions stöder två programmeringsmodeller för Python. Hur du definierar dina bindningar beror på din valda programmeringsmodell.

Med programmeringsmodellen Python v2 kan du definiera bindningar med hjälp av dekoratörer direkt i python-funktionskoden. Mer information finns i utvecklarguiden för Python.

Den här artikeln stöder båda programmeringsmodellerna.

En C#-funktion kan skapas med något av följande C#-lägen:

  • Isolerad arbetsmodell: Kompilerad C#-funktion som körs i en arbetsprocess som är isolerad från körningen. Isolerad arbetsprocess krävs för att stödja C#-funktioner som körs på LTS- och icke-LTS-versioner .NET och .NET Framework. Tillägg för isolerade arbetsprocessfunktioner använder Microsoft.Azure.Functions.Worker.Extensions.* namnområden.
  • Processmodell: Kompilerad C#-funktion som körs i samma process som Functions-körningen. I en variant av den här modellen kan Functions köras med C#-skript, vilket främst stöds för redigering av C#-portalen. Tillägg för in-process-funktioner använder Microsoft.Azure.WebJobs.Extensions.* namnområden.

Viktigt!

Supporten upphör för den pågående modellen den 10 november 2026. Vi rekommenderar starkt att du migrerar dina appar till den isolerade arbetsmodellen för fullt stöd.

Exempel

Om inget annat anges är exempel i den här artikeln målversion 3.x av Azure Cosmos DB-tillägget. För användning med tilläggsversion 4.x måste du ersätta strängen collection i egenskaps- och attributnamn med container och connection_string_setting med connection.

Följande kod definierar en 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; }
}

I följande exempel är returtypen en IReadOnlyList<T>, som är en ändrad lista över dokument från utlösarbindningsparametern:

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

Köutlösare, spara meddelande till databasen via returvärde

I följande exempel visas en Java-funktion som lägger till ett dokument i en databas med data från ett meddelande i 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 + " }";
   }

HTTP-utlösare, spara ett dokument i databasen via returvärde

I följande exempel visas en Java-funktion vars signatur kommenteras med @CosmosDBOutput och har returvärdet av typen String. JSON-dokumentet som returneras av funktionen skrivs automatiskt till motsvarande Azure Cosmos DB-samling.

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

HTTP-utlösare, spara ett dokument i databasen via OutputBinding

I följande exempel visas en Java-funktion som skriver ett dokument till Azure Cosmos DB via en utdataparameter OutputBinding<T> . I det här exemplet måste parametern outputItem kommenteras med @CosmosDBOutput, inte funktionssignaturen. Med hjälp OutputBinding<T> av kan din funktion dra nytta av bindningen för att skriva dokumentet till Azure Cosmos DB samtidigt som du kan returnera ett annat värde till funktionsanroparen, till exempel ett JSON- eller XML-dokument.

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

HTTP-utlösare, spara flera dokument i databasen via OutputBinding

I följande exempel visas en Java-funktion som skriver flera dokument till Azure Cosmos DB via en utdataparameter OutputBinding<T> . I det här exemplet kommenteras parametern outputItem med @CosmosDBOutput, inte funktionssignaturen. Utdataparametern outputItem har en lista med ToDoItem objekt som mallparametertyp. Med hjälp OutputBinding<T> av kan din funktion dra nytta av bindningen för att skriva dokumenten till Azure Cosmos DB samtidigt som du kan returnera ett annat värde till funktionsanroparen, till exempel ett JSON- eller XML-dokument.

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

I Java Functions-körningsbiblioteket använder du anteckningen @CosmosDBOutput för parametrar som ska skrivas till Azure Cosmos DB. Kommentarsparametertypen ska vara OutputBinding<T>, där T är antingen en inbyggd Java-typ eller en POJO.

I följande exempel visas en utlös TypeScript-funktion i lagringskö för en kö som tar emot JSON i följande format:

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

Funktionen skapar Azure Cosmos DB-dokument i följande format för varje post:

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

Här är TypeScript-koden:

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

Om du vill mata ut flera dokument returnerar du en matris i stället för ett enda objekt. Till exempel:

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

I följande exempel visas en javaScript-funktion som utlöses av en lagringskö för en kö som tar emot JSON i följande format:

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

Funktionen skapar Azure Cosmos DB-dokument i följande format för varje post:

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

Här är JavaScript-koden:

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

Om du vill mata ut flera dokument returnerar du en matris i stället för ett enda objekt. Till exempel:

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

I följande exempel visas hur du skriver data till Azure Cosmos DB med hjälp av en utdatabindning. Bindningen deklareras i funktionens konfigurationsfil (functions.json) och tar data från ett kömeddelande och skriver ut till ett Azure Cosmos DB-dokument.

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

I filen run.ps1 mappas objektet som returneras från funktionen till ett EmployeeDocument objekt som sparas i databasen.

param($QueueItem, $TriggerMetadata) 

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

I följande exempel visas hur du skriver ett dokument till en Azure Cosmos DB-databas som utdata från en funktion. Exemplet beror på om du använder python-programmeringsmodellen v1 eller v2.

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'

Attribut

C#-bibliotek i både processprocess och isolerad arbetsprocess använder attribut för att definiera funktionen. C#-skriptet använder i stället en function.json konfigurationsfil enligt beskrivningen i C#-skriptguiden.

Attributegenskap beskrivning
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till det Azure Cosmos DB-konto som övervakas. Mer information finns i Anslutningar.
DatabaseName Namnet på Azure Cosmos DB-databasen med containern som övervakas.
ContainerName Namnet på containern som övervakas.
CreateIfNotExists Ett booleskt värde som anger om containern skapas när den inte finns. Standardvärdet är falskt eftersom nya containrar skapas med reserverat dataflöde, vilket har kostnadskonsekvenser. Mer information, se prissidan.
PartitionKey När CreateIfNotExists är sant definierar den partitionsnyckelsökvägen för den skapade containern. Kan innehålla bindningsparametrar.
ContainerThroughput När CreateIfNotExists är sant definierar det dataflödet för den skapade containern.
PreferredLocations (Valfritt) Definierar önskade platser (regioner) för geo-replikerade databaskonton i Azure Cosmos DB-tjänsten. Värden bör kommaavgränsas. Exempel: East US,South Central US,North Europe

Dekoratörer

Gäller endast för python v2-programmeringsmodellen.

För Python v2-funktioner som definierats med hjälp av en dekoratör, följande egenskaper på cosmos_db_output:

Property beskrivning
arg_name Variabelnamnet som används i funktionskoden som representerar listan över dokument med ändringar.
database_name Namnet på Azure Cosmos DB-databasen med samlingen som övervakas.
collection_name Namnet på Den Azure Cosmos DB-samling som övervakas.
create_if_not_exists Ett booleskt värde som anger om databasen och samlingen ska skapas om de inte finns.
connection_string_setting Den anslutningssträng av Azure Cosmos DB som övervakas.

Information om Python-funktioner som definierats med hjälp av function.json finns i avsnittet Konfiguration .

Kommentarer

Från Java Functions-körningsbiblioteket använder du anteckningen @CosmosDBOutput på parametrar som skriver till Azure Cosmos DB. Kommentaren stöder följande egenskaper:

Konfiguration

Gäller endast programmeringsmodellen Python v1.

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas output.cosmosDB() till metoden. Egenskaperna type, directionoch name gäller inte för v4-modellen.

I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i filen function.json , där egenskaperna skiljer sig åt efter tilläggsversion:

function.json egenskap beskrivning
samband Namnet på en appinställning eller inställningssamling som anger hur du ansluter till det Azure Cosmos DB-konto som övervakas. Mer information finns i Anslutningar.
databaseName Namnet på Azure Cosmos DB-databasen med containern som övervakas.
containerName Namnet på containern som övervakas.
createIfNotExists Ett booleskt värde som anger om containern skapas när den inte finns. Standardvärdet är falskt eftersom nya containrar skapas med reserverat dataflöde, vilket har kostnadskonsekvenser. Mer information, se prissidan.
partitionKey När createIfNotExists är sant definierar den partitionsnyckelsökvägen för den skapade containern. Kan innehålla bindningsparametrar.
containerThroughput När createIfNotExists är sant definierar det dataflödet för den skapade containern.
preferredLocations (Valfritt) Definierar önskade platser (regioner) för geo-replikerade databaskonton i Azure Cosmos DB-tjänsten. Värden bör kommaavgränsas. Exempel: East US,South Central US,North Europe

Se avsnittet Exempel för fullständiga exempel.

Förbrukning

När du skriver till utdataparametern i funktionen skapas som standard ett dokument i databasen. Du bör ange dokument-ID för utdatadokumentet genom att id ange egenskapen i JSON-objektet som skickas till utdataparametern.

Kommentar

När du anger ID för ett befintligt dokument skrivs det över av det nya utdatadokumentet.

Parametertypen som stöds av Cosmos DB-utdatabindningen beror på functions-körningsversionen, tilläggspaketversionen och den C#-modalitet som används.

När du vill att funktionen ska skriva till ett enda dokument kan Cosmos DB-utdatabindningen binda till följande typer:

Typ Beskrivning
JSON-serialiserbara typer Ett objekt som representerar JSON-innehållet i ett dokument. Functions försöker serialisera en vanlig CLR-objekttyp (POCO) till JSON-data.

När du vill att funktionen ska skriva till flera dokument kan Cosmos DB-utdatabindningen binda till följande typer:

Typ Beskrivning
T[] där T är JSON serializable type En matris som innehåller flera dokument. Varje post representerar ett dokument.

För andra utdatascenarier skapar och använder du en CosmosClient med andra typer direkt från Microsoft.Azure.Cosmos . Se Registrera Azure-klienter för ett exempel på hur du använder beroendeinmatning för att skapa en klienttyp från Azure SDK.

anslutningar

Egenskaperna connectionStringSetting/connection och leaseConnectionStringSetting/leaseConnection är referenser till miljökonfigurationen som anger hur appen ska ansluta till Azure Cosmos DB. De kan ange:

Om det konfigurerade värdet både är en exakt matchning för en enskild inställning och en prefixmatchning för andra inställningar används den exakta matchningen.

Connection string

Anslutningssträng för ditt databaskonto ska lagras i en programinställning med ett namn som matchar värdet som anges av anslutningsegenskapen för bindningskonfigurationen.

Identitetsbaserade anslutningar

Om du använder version 4.x eller senare av tillägget kan du i stället för att använda en anslutningssträng med en hemlighet låta appen använda en Microsoft Entra-identitet. Gör detta genom att definiera inställningarna under ett vanligt prefix som mappas till anslutningsegenskapen i utlösaren och bindningskonfigurationen.

I det här läget kräver tillägget följande egenskaper:

Property Miljövariabelmall beskrivning Exempelvärde
Kontoslutpunkt <CONNECTION_NAME_PREFIX>__accountEndpoint Azure Cosmos DB-kontots slutpunkts-URI. <https:// database_account_name.documents.azure.com:443/>

Ytterligare egenskaper kan anges för att anpassa anslutningen. Se Vanliga egenskaper för identitetsbaserade anslutningar.

När identitetsbaserade anslutningar finns i Azure Functions-tjänsten använder de en hanterad identitet. Den systemtilldelade identiteten används som standard, även om en användartilldelad identitet kan anges med credential egenskaperna och clientID . Observera att det inte går att konfigurera en användartilldelad identitet med ett resurs-ID. När den körs i andra sammanhang, till exempel lokal utveckling, används utvecklaridentiteten i stället, även om den kan anpassas. Se Lokal utveckling med identitetsbaserade anslutningar.

Bevilja behörighet till identiteten

Den identitet som används måste ha behörighet att utföra de avsedda åtgärderna. För de flesta Azure-tjänster innebär det att du måste tilldela en roll i Azure RBAC med hjälp av antingen inbyggda eller anpassade roller som ger dessa behörigheter.

Viktigt!

Vissa behörigheter kan exponeras av måltjänsten som inte är nödvändiga för alla kontexter. Om möjligt följer du principen om minsta behörighet och beviljar identiteten endast nödvändiga privilegier. Om appen till exempel bara behöver kunna läsa från en datakälla använder du en roll som bara har behörighet att läsa. Det skulle vara olämpligt att tilldela en roll som också tillåter skrivning till tjänsten, eftersom detta skulle vara överdriven behörighet för en läsåtgärd. På samma sätt vill du se till att rolltilldelningen endast är begränsad till de resurser som behöver läsas.

Cosmos DB använder inte Azure RBAC för dataåtgärder. I stället använder den ett inbyggt RBAC-system i Cosmos DB som bygger på liknande begrepp. Du måste skapa en rolltilldelning som ger åtkomst till ditt databaskonto vid körning. Azure RBAC Management-roller som Ägare räcker inte. I följande tabell visas inbyggda roller som rekommenderas när du använder Azure Cosmos DB-tillägget i normal drift. Programmet kan kräva ytterligare behörigheter baserat på den kod du skriver.

Bindningstyp Exempel på inbyggda roller1
Utlösare2 Inbyggd Cosmos DB-datadeltagare
Indatabindning Inbyggd Cosmos DB-dataläsare
Utdatabindning Inbyggd Cosmos DB-datadeltagare

1 Dessa roller kan inte användas i en Azure RBAC-rolltilldelning. Mer information om hur du tilldelar dessa roller finns i den inbyggda RBAC-systemdokumentationen för Cosmos DB.

2 När du använder identitet behandlar Cosmos DB skapandet av containrar som en hanteringsåtgärd. Den är inte tillgänglig som en dataplansåtgärd för utlösaren. Du måste se till att du skapar de containrar som behövs av utlösaren (inklusive lånecontainern) innan du konfigurerar funktionen.

Undantag och returkoder

Bindning Referens
Azure Cosmos DB HTTP-statuskoder för Azure Cosmos DB

Nästa steg