Dela via

Översikt över Azure Cosmos DB-utlösare och bindningar för Azure Functions

Den här uppsättningen artiklar beskriver hur du arbetar med Azure Cosmos DB-bindningar i Azure Functions. 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

Viktigt!

Den här versionen av Azure Cosmos DB-bindningstillägget stöder Azure Functions version 4.x. Om din app fortfarande använder version 1.x av Functions-körningen läser du i stället Azure Cosmos DB-bindningar för Azure Functions 1.x. I Functions v1.x-körningen hette DocumentDBden här bindningen ursprungligen .

API:er som stöds

Den här tabellen anger hur du ansluter till de olika Azure Cosmos DB-API:erna från funktionskoden:

API Recommendation
Azure Cosmos DB för NoSQL Använda Azure Cosmos DB-bindningstillägget
Azure Cosmos DB för MongoDB (virtuell kärna) Använd bindningstillägget Azure Cosmos DB for MongoDB, som för närvarande är i förhandsversion.
Azure Cosmos DB för tabell Använd version 5.x eller senare av Azure Tables-bindningstillägget.
Azure Cosmos DB för Apache Cassandra Använd en intern klient-SDK.
Azure Cosmos DB för Apache Gremlin (Graph API) Använda en intern klient-SDK
Azure Cosmos DB för PostgreSQL Använd en intern klient-SDK.

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 ConfigureFunctionsWorkerDefaults()lägger du till ConfigureFunctionsWebApplication() 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

För att kunna använda det här bindningstillägget i din app kontrollerar du att denhost.json filen i projektets rot innehåller den här extensionBundle referensen:

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

I det här exemplet version instruerar värdet [4.0.0, 5.0.0) för Functions-värden att använda en paketversion som är minst 4.0.0 men mindre än 5.0.0, som innehåller alla potentiella versioner av 4.x. Den här notationen underhåller appen på den senaste tillgängliga delversionen av v4.x-tilläggspaketet.

När det är möjligt bör du använda den senaste huvudversionen av tilläggspaketet och låta körningen automatiskt behålla den senaste delversionen. Du kan visa innehållet i det senaste paketet på versionssidan för tilläggspaket. Mer information finns i Azure Functions-tilläggspaket.

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.

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

SDK-bindningstyper

SDK-typstöd för Azure Cosmos finns i förhandsversion. Följ Python SDK-bindningar för CosmosDB-exemplet för att komma igång med SDK-typer för Cosmos i Python.

Viktigt!

Om du använder SDK-typbindningar krävs programmeringsmodellen Python v2.

Bindning Parametertyper Exempel
CosmosDB-indata ContainerProxy,
CosmosClient,
DatabaseProxy
 ContainerProxy,
CosmosClient,
DatabaseProxy

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. Mer information om konfigurationsinställningar för funktionsappar finns ihost.json referens för Azure Functions.

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}
Fastighet Standardvärde Beskrivning
connectionMode Gateway Anslutningsläget som används av funktionen när du ansluter till Azure Cosmos DB-tjänsten. Alternativ: Direct ansluter direkt till serverdelsrepliker via TCP och kan ge kortare svarstid och Gateway dirigerar begäranden via en klientdelsgateway via HTTPS. Mer information finns i Anslutningslägen för Azure Cosmos DB SDK.
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