Dela via


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

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:

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.

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

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

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.

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.

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:

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

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

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.

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

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 host.json-filen 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.

{
    "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.

Nästa steg