Azure Cosmos DB-utlösare och bindningar för Azure Functions 2.x och senare översikt

• Version 1
• Version 2 och senare

Den här uppsättningen artiklar beskriver hur du arbetar med Azure Cosmos DB-bindningar i Azure Functions 2.x och senare. Azure Functions stöder bindningar för utlösare, indata och utdata för Azure Cosmos DB.

Åtgärd	Typ
Kör en funktion när ett Azure Cosmos DB-dokument skapas eller ändras	Utlösare
Läsa ett Azure Cosmos DB-dokument	Indatabindning
Spara ändringar i ett Azure Cosmos DB-dokument	Utdatabindning

Kommentar

Den här referensen gäller för Azure Functions version 2.x och senare. Information om hur du använder dessa bindningar i Functions 1.x finns i Azure Cosmos DB-bindningar för Azure Functions 1.x.

Den här bindningen hette ursprungligen DocumentDB. I Azure Functions version 2.x och senare heter alla utlösare, bindningar och paket Azure Cosmos DB.

API:er som stöds

Azure Cosmos DB-bindningar stöds endast för användning med Azure Cosmos DB för NoSQL. Stöd för Azure Cosmos DB for Table tillhandahålls med hjälp av Table Storage-bindningar, från och med tillägg 5.x. För alla andra Azure Cosmos DB-API:er bör du komma åt databasen från din funktion med hjälp av den statiska klienten för ditt API, inklusive Azure Cosmos DB för MongoDB, Azure Cosmos DB för Cassandra och Azure Cosmos DB för Apache Gremlin.

Installera tillägget

Vilket NuGet-tilläggspaket du installerar beror på vilket C#-läge du använder i funktionsappen:

Isolerad arbetsmodell

Funktioner körs i en isolerad C#-arbetsprocess. Mer information finns i Guide för att köra C# Azure Functions i en isolerad arbetsprocess.

Processmodell

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.

Funktioner körs i samma process som Functions-värden. Mer information finns i Utveckla C#-klassbiblioteksfunktioner med Hjälp av Azure Functions.

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. Information om hur du uppdaterar befintliga bindningstillägg för C#-skriptappar som körs i portalen utan att behöva publicera om funktionsappen finns i Uppdatera dina tillägg.

Processen för att installera tillägget varierar beroende på tilläggsversionen:

Tillägg 4.x+

I det här avsnittet beskrivs hur du använder ett klassbibliotek. För C#-skript måste du i stället installera tilläggspaketet version 4.x.

Den här versionen av Azure Cosmos DB-bindningstillägget ger möjlighet att ansluta med hjälp av en identitet i stället för en hemlighet. En självstudiekurs om hur du konfigurerar dina funktionsappar med hanterade identiteter finns i självstudien skapa en funktionsapp med identitetsbaserade anslutningar.

Den här versionen ändrar också de typer som du kan binda till och ersätter typerna från v2 SDK Microsoft.Azure.DocumentDB med nyare typer från v3 SDK Microsoft.Azure.Cosmos. Läs mer om hur dessa nya typer skiljer sig och hur du migrerar till dem från SDK-migreringsguiden, utlösare, indatabindning och utdatabindningsexempel.

Den här tilläggsversionen är tillgänglig som ett NuGet-paket, version 4.x.

Functions 2.x+

I det här avsnittet beskrivs hur du använder ett klassbibliotek. För C#-skript måste du i stället installera tilläggspaketet, version 2.x eller 3.x.

När du arbetar med utlösaren och bindningarna måste du referera till lämpligt NuGet-paket. Installera NuGet-paketet version 3.x.

Tillägg 4.x+

Den här versionen av Azure Cosmos DB-bindningstillägget ger möjlighet att ansluta med hjälp av en identitet i stället för en hemlighet. En självstudiekurs om hur du konfigurerar dina funktionsappar med hanterade identiteter finns i självstudien skapa en funktionsapp med identitetsbaserade anslutningar.

Lägg till tillägget i projektet genom att installera NuGet-paketet version 4.x.

Om du skriver ditt program med hjälp av F# måste du också konfigurera det här tillägget som en del av appens startkonfiguration. I anropet till eller ConfigureFunctionsWebApplication()lägger du till ConfigureFunctionsWorkerDefaults() ett ombud som tar en IFunctionsWorkerApplication parameter. Anropa sedan objektet i brödtexten för ombudet ConfigureCosmosDBExtension() :

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Functions 2.x+

Lägg till tillägget i projektet genom att installera NuGet-paketet version 3.x.

Installera paket

Azure Cosmos DB-bindningstillägget är en del av ett tilläggspaket som anges i din host.json projektfil. Du kan behöva ändra det här paketet för att ändra versionen av bindningen, eller om paket inte redan är installerade. Mer information finns i tilläggspaketet.

På grund av schemaändringar i Azure Cosmos DB SDK kräver version 4.x av Azure Cosmos DB-tillägget azure-functions-java-library V3.0.0 för Java-funktioner.

Paket v4.x

Den här versionen av paketet innehåller version 4.x av Azure Cosmos DB-bindningstillägget som introducerar möjligheten att ansluta med hjälp av en identitet i stället för en hemlighet. En självstudiekurs om hur du konfigurerar dina funktionsappar med hanterade identiteter finns i självstudien skapa en funktionsapp med identitetsbaserade anslutningar.

Du kan lägga till den här versionen av tillägget från förhandsgranskningstilläggspaketet v4 genom att lägga till eller ersätta följande kod i host.json filen:

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

Mer information finns i Uppdatera dina tillägg.

Paket v2.x och v3.x

Du kan installera den här versionen av tillägget i funktionsappen genom att registrera tilläggspaketet, version 2.x eller 3.x.

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

Bindningstyper

Vilka bindningstyper som stöds för .NET beror på både tilläggsversionen och C#-körningsläget, vilket kan vara något av följande:

Isolerad arbetsmodell

Ett isolerat arbetsprocessklassbibliotek kompilerade C#-funktioner körs i en process som är isolerad från körningen.

Processmodell

Ett kursbibliotek i processen är en kompilerad C#-funktion som körs i samma process som Functions-körningen.

Välj en version för att se information om bindningstyp för läget och versionen.

Tillägg 4.x+

Azure Cosmos DB-tillägget stöder parametertyper enligt tabellen nedan.

Bindningsscenario	Parametertyper
Cosmos DB-utlösare (enskilt dokument)	JSON serialiserbara typer1
Cosmos DB-utlösare (batch med dokument)	IEnumerable<T>där T är en JSON-serialiserbar typ1
Cosmos DB-indata (enskilt dokument)	JSON serialiserbara typer1
Cosmos DB-indata (fråga som returnerar flera dokument)	CosmosClient IEnumerable<T> där T är en JSON-serialiserbar typ1
Cosmos DB-utdata (enskilt dokument)	JSON serialiserbara typer1
Cosmos DB-utdata (flera dokument)	ICollector<T> eller IAsyncCollector<T> där T är en JSON-serialiserbar typ1

¹ Dokument som innehåller JSON-data kan deserialiseras till kända Oformaterade CLR-objekttyper (POCO).

Functions 2.x+

Tidigare versioner av tillägget exponerade typer från det nu inaktuella namnområdet Microsoft.Azure.Documents . Nyare typer från Microsoft.Azure.Cosmos är exklusiva för tillägg 4.x och senare.

Tillägg 4.x+

Den isolerade arbetsprocessen stöder parametertyper enligt tabellerna nedan. Stöd för bindning till typer från Microsoft.Azure.Cosmosfinns i förhandsversionen.

Cosmos DB-utlösare

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

Typ	Beskrivning
JSON-serialiserbara typer	Functions försöker deserialisera JSON-data i dokumentet från Cosmos DB-ändringsflödet till en vanlig CLR-objekttyp (POCO).

När du vill att funktionen ska bearbeta en batch med dokument kan Cosmos DB-utlösaren binda till följande typer:

Typ	Beskrivning
IEnumerable<T>där T är en JSON-serialiserbar typ	En uppräkning av entiteter som ingår i batchen. Varje post representerar ett dokument från Cosmos DB-ändringsflödet.

Cosmos DB-indatabindning

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

Typ	Beskrivning
JSON-serialiserbara typer	Functions försöker deserialisera JSON-data i dokumentet till en oformaterad TYP av CLR-objekt (POCO).

När du vill att funktionen ska bearbeta flera dokument från en fråga kan Cosmos DB-indatabindningen binda till följande typer:

Typ	Beskrivning
IEnumerable<T>där T är en JSON-serialiserbar typ	En uppräkning av entiteter som returneras av frågan. Varje post representerar ett dokument.
CosmosClient1	En klient som är ansluten till Cosmos DB-kontot.
Databas1	En klient som är ansluten till Cosmos DB-databasen.
Container1	En klient som är ansluten till Cosmos DB-containern.

¹ Om du vill använda dessa typer måste du referera till Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 eller senare och de vanliga beroendena för SDK-typbindningar.

Cosmos DB-utdatabindning

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 typer från Microsoft.Azure.Cosmos direkt.

Functions 2.x+

Tidigare versioner av tillägg i den isolerade arbetsprocessen stöder endast bindning till JSON-serialiserbara typer. Ytterligare alternativ är tillgängliga för tillägg 4.x och senare.

Undantag och returkoder

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

host.json inställningar

I det här avsnittet beskrivs de konfigurationsinställningar som är tillgängliga för den här bindningen i version 2.x och senare. Inställningar i filen host.json gäller för alla funktioner i en funktionsappinstans. Exemplet host.json filen nedan innehåller endast version 2.x+-inställningarna för den här bindningen. Mer information om konfigurationsinställningar för funktionsappar i version 2.x och senare versioner finns i host.json referens för Azure Functions.

Tillägg 4.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

Property	Standardvärde	beskrivning
connectionMode	Gateway	Anslutningsläget som används av funktionen när du ansluter till Azure Cosmos DB-tjänsten. Alternativen är Direct och Gateway
userAgentSuffix	saknas	Lägger till det angivna strängvärdet för alla begäranden som görs av utlösaren eller bindningen till tjänsten. Det gör det enklare för dig att spåra aktiviteten i Azure Monitor, baserat på en specifik funktionsapp och filtrering efter User Agent.

Functions 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

Property	Standardvärde	beskrivning
connectionMode	Gateway	Anslutningsläget som används av funktionen när du ansluter till Azure Cosmos DB-tjänsten. Alternativen är Direct och Gateway
Protokollet	Https	Anslutningsprotokollet som används av funktionen när du ansluter till Azure Cosmos DB-tjänsten. Läs här för en förklaring av båda lägena.
leasePrefix	saknas	Låneprefix som ska användas för alla funktioner i en app.

Nästa steg

• Kör en funktion när ett Azure Cosmos DB-dokument skapas eller ändras (utlösare)
• Läsa ett Azure Cosmos DB-dokument (indatabindning)
• Spara ändringar i ett Azure Cosmos DB-dokument (utdatabindning)