Overzicht van Azure Cosmos DB-triggers en -bindingen voor Azure Functions 2.x en hoger

• Versie 1
• Versie 2 en hoger

In deze reeks artikelen wordt uitgelegd hoe u kunt werken met Azure Cosmos DB-bindingen in Azure Functions 2.x en hoger. Azure Functions ondersteunt trigger-, invoer- en uitvoerbindingen voor Azure Cosmos DB.

Actie	Type
Een functie uitvoeren wanneer een Azure Cosmos DB-document wordt gemaakt of gewijzigd	Trigger
Een Azure Cosmos DB-document lezen	Invoerbinding
Wijzigingen opslaan in een Azure Cosmos DB-document	Uitvoerbinding

Notitie

Deze verwijzing is voor Azure Functions versie 2.x en hoger. Zie Azure Cosmos DB-bindingen voor Azure Functions 1.x voor informatie over het gebruik van deze bindingen in Functions 1.x.

Deze binding heette oorspronkelijk DocumentDB. In Azure Functions versie 2.x en hoger hebben de trigger, bindingen en het pakket allemaal de naam Azure Cosmos DB.

Ondersteunde API's

Azure Cosmos DB-bindingen worden alleen ondersteund voor gebruik met Azure Cosmos DB voor NoSQL. Ondersteuning voor Azure Cosmos DB voor Table wordt geleverd met behulp van de Table Storage-bindingen, te beginnen met extensie 5.x. Voor alle andere Azure Cosmos DB-API's hebt u toegang tot de database vanuit uw functie met behulp van de statische client voor uw API, waaronder Azure Cosmos DB voor MongoDB, Azure Cosmos DB voor Cassandra en Azure Cosmos DB voor Apache Gremlin.

De extensie installeren

Het NuGet-extensiepakket dat u installeert, is afhankelijk van de C#-modus die u gebruikt in uw functie-app:

Geïsoleerde werkrolmodel

Functies worden uitgevoerd in een geïsoleerd C#-werkproces. Zie De handleiding voor het uitvoeren van C# Azure Functions in een geïsoleerd werkproces voor meer informatie.

Model in proces

Belangrijk

De ondersteuning wordt beëindigd voor het in-process model op 10 november 2026. We raden u ten zeerste aan uw apps te migreren naar het geïsoleerde werkrolmodel voor volledige ondersteuning.

Functies worden uitgevoerd in hetzelfde proces als de Functions-host. Zie C#-klassebibliotheekfuncties ontwikkelen met behulp van Azure Functions voor meer informatie.

In een variatie van dit model kunnen functies worden uitgevoerd met behulp van C#-scripting. Dit wordt voornamelijk ondersteund voor het bewerken van de C#-portal. Zie Uw extensies bijwerken als u bestaande bindingsextensies wilt bijwerken voor C#-script-apps die worden uitgevoerd in de portal zonder dat u de functie-app opnieuw hoeft te publiceren.

Het proces voor het installeren van de extensie varieert afhankelijk van de extensieversie:

Extensie 4.x+

In deze sectie wordt beschreven hoe u een klassebibliotheek gebruikt. Voor C#-scripts moet u in plaats daarvan de extensiebundel, versie 4.x, installeren.

Deze versie van de Azure Cosmos DB bindings-extensie introduceert de mogelijkheid om verbinding te maken met behulp van een identiteit in plaats van een geheim. Zie de zelfstudie over het maken van een functie-app met op identiteit gebaseerde verbindingen voor een zelfstudie over het configureren van uw functie-apps met beheerde identiteiten.

In deze versie worden ook de typen gewijzigd waarmee u verbinding kunt maken, waarbij u de typen van de v2 SDK Microsoft.Azure.DocumentDB vervangt door nieuwere typen van de v3 SDK Microsoft.Azure.Cosmos. Meer informatie over hoe deze nieuwe typen verschillen en hoe u ernaar kunt migreren vanuit de SDK-migratiehandleiding, trigger, invoerbinding en uitvoerbindingsvoorbeelden .

Deze extensieversie is beschikbaar als een NuGet-pakket, versie 4.x.

Functions 2.x+

In deze sectie wordt beschreven hoe u een klassebibliotheek gebruikt. Voor C#-scripts moet u in plaats daarvan de extensiebundel, versie 2.x of 3.x installeren.

Als u met de trigger en bindingen werkt, moet u verwijzen naar het juiste NuGet-pakket. Installeer het NuGet-pakket, versie 3.x.

Extensie 4.x+

Deze versie van de Azure Cosmos DB bindings-extensie introduceert de mogelijkheid om verbinding te maken met behulp van een identiteit in plaats van een geheim. Zie de zelfstudie over het maken van een functie-app met op identiteit gebaseerde verbindingen voor een zelfstudie over het configureren van uw functie-apps met beheerde identiteiten.

Voeg de extensie toe aan uw project door het NuGet-pakket versie 4.x te installeren.

Als u uw toepassing schrijft met F#, moet u deze extensie ook configureren als onderdeel van de opstartconfiguratie van de app. Voeg in de aanroep naar ConfigureFunctionsWorkerDefaults() of ConfigureFunctionsWebApplication()een gemachtigde toe die een IFunctionsWorkerApplication parameter gebruikt. Roep vervolgens binnen de hoofdtekst van die gemachtigde ConfigureCosmosDBExtension() het object aan:

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

Functions 2.x+

Voeg de extensie toe aan uw project door het NuGet-pakket, versie 3.x, te installeren.

Bundel installeren

De Azure Cosmos DB-bindingsextensie maakt deel uit van een extensiebundel, die is opgegeven in uw host.json projectbestand. Mogelijk moet u deze bundel wijzigen om de versie van de binding te wijzigen of als bundels nog niet zijn geïnstalleerd. Zie uitbreidingsbundel voor meer informatie.

Vanwege schemawijzigingen in de Azure Cosmos DB SDK vereist versie 4.x van de Azure Cosmos DB-extensie azure-functions-java-library V3.0.0 voor Java-functies.

Bundel v4.x

Deze versie van de bundel bevat versie 4.x van de Azure Cosmos DB-bindingsextensie waarmee u verbinding kunt maken met behulp van een identiteit in plaats van een geheim. Zie de zelfstudie over het maken van een functie-app met op identiteit gebaseerde verbindingen voor een zelfstudie over het configureren van uw functie-apps met beheerde identiteiten.

U kunt deze versie van de extensie toevoegen vanuit de preview-extensiebundel v4 door de volgende code toe te voegen of te vervangen in uw host.json bestand:

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

Zie Uw extensies bijwerken voor meer informatie.

Bundel v2.x en v3.x

U kunt deze versie van de extensie installeren in uw functie-app door de extensiebundel, versie 2.x of 3.x te registreren.

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

Bindingstypen

De bindingstypen die worden ondersteund voor .NET zijn afhankelijk van zowel de extensieversie als de C#-uitvoeringsmodus. Dit kan een van de volgende zijn:

Geïsoleerde werkrolmodel

Een geïsoleerde werkprocesklassebibliotheek gecompileerde C#-functie wordt uitgevoerd in een proces dat is geïsoleerd van de runtime.

Model in proces

Een in-process-klassebibliotheek is een gecompileerde C#-functie die wordt uitgevoerd in hetzelfde proces als de Functions-runtime.

Kies een versie om de details van het bindingstype voor de modus en versie weer te geven.

Extensie 4.x+

De Azure Cosmos DB-extensie ondersteunt parametertypen volgens de onderstaande tabel.

Bindingsscenario	Parametertypen
Cosmos DB-trigger (één document)	JSON serialiseerbare typen1
Cosmos DB-trigger (batch documenten)	IEnumerable<T>waarbij T een JSON serialiseerbaar type1 is
Cosmos DB-invoer (één document)	JSON serialiseerbare typen1
Cosmos DB-invoer (query die meerdere documenten retourneert)	CosmosClient IEnumerable<T> waarbij T een JSON serialiseerbaar type1 is
Cosmos DB-uitvoer (één document)	JSON serialiseerbare typen1
Cosmos DB-uitvoer (meerdere documenten)	ICollector<T> of IAsyncCollector<T> waar T is een JSON serialiseerbare type1

¹ Documenten die JSON-gegevens bevatten, kunnen worden gedeserialiseerd in bekende niet-oude CLR-objecttypen (POCO).

Functions 2.x+

Eerdere versies van de extensie weergegeven typen uit de nu afgeschafte Microsoft.Azure.Documents-naamruimte . Nieuwere typen van Microsoft.Azure.Cosmos zijn exclusief voor extensie 4.x en hoger.

Extensie 4.x+

Het geïsoleerde werkproces ondersteunt parametertypen volgens de onderstaande tabellen. Ondersteuning voor binding met typen van Microsoft.Azure.Cosmosis in preview.

Cosmos DB-trigger

Wanneer u wilt dat de functie één document verwerkt, kan de Cosmos DB-trigger worden gekoppeld aan de volgende typen:

Type	Description
JSON serialiseerbare typen	Functions probeert de JSON-gegevens van het document uit de Cosmos DB-wijzigingenfeed te deserialiseren naar een poCO-type (plain-old CLR object).

Wanneer u wilt dat de functie een batch documenten verwerkt, kan de Cosmos DB-trigger verbinding maken met de volgende typen:

Type	Description
IEnumerable<T>waarbij T een type JSON serialiseerbaar is	Een opsomming van entiteiten die zijn opgenomen in de batch. Elke vermelding vertegenwoordigt één document uit de Cosmos DB-wijzigingenfeed.

Cosmos DB-invoerbinding

Wanneer u wilt dat de functie één document verwerkt, kan de Cosmos DB-invoerbinding worden gekoppeld aan de volgende typen:

Type	Description
JSON serialiseerbare typen	Functions probeert de JSON-gegevens van het document te deserialiseren in een niet-oud CLR-objecttype (POCO).

Wanneer u wilt dat de functie meerdere documenten uit een query verwerkt, kan de Cosmos DB-invoerbinding worden gekoppeld aan de volgende typen:

Type	Description
IEnumerable<T>waarbij T een type JSON serialiseerbaar is	Een opsomming van entiteiten die door de query worden geretourneerd. Elke vermelding vertegenwoordigt één document.
CosmosClient1	Een client die is verbonden met het Cosmos DB-account.
Database1	Een client die is verbonden met de Cosmos DB-database.
Container1	Een client die is verbonden met de Cosmos DB-container.

¹ Als u deze typen wilt gebruiken, moet u verwijzen naar Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 of hoger en de algemene afhankelijkheden voor SDK-typebindingen.

Cosmos DB-uitvoerbinding

Wanneer u wilt dat de functie naar één document schrijft, kan de Cosmos DB-uitvoerbinding worden gekoppeld aan de volgende typen:

Type	Description
JSON serialiseerbare typen	Een object dat de JSON-inhoud van een document vertegenwoordigt. Functions probeert een normaal oud CLR-objecttype (POCO) te serialiseren in JSON-gegevens.

Wanneer u wilt dat de functie naar meerdere documenten schrijft, kan de Cosmos DB-uitvoerbinding worden gekoppeld aan de volgende typen:

Type	Description
T[] waar T is JSON serialiseerbare type	Een matrix met meerdere documenten. Elke vermelding vertegenwoordigt één document.

Voor andere uitvoerscenario's maakt en gebruikt u rechtstreeks typen van Microsoft.Azure.Cosmos .

Functions 2.x+

Eerdere versies van extensies in het geïsoleerde werkproces ondersteunen alleen binding met serialiseerbare JSON-typen. Er zijn extra opties beschikbaar voor extensie 4.x en hoger.

Uitzonderingen en retourcodes

Binding	Verwijzing
Azure Cosmos DB	HTTP-statuscodes voor Azure Cosmos DB

host.json-instellingen

In deze sectie worden de configuratie-instellingen beschreven die beschikbaar zijn voor deze binding in versie 2.x en hoger. Instellingen in het bestand host.json zijn van toepassing op alle functies in een exemplaar van een functie-app. Het onderstaande voorbeeld host.json bestand bevat alleen de instellingen voor versie 2.x+ voor deze binding. Zie host.json naslaginformatie voor Azure Functions voor meer informatie over configuratie-instellingen voor functie-apps in versies 2.x en latere versies.

Extensie 4.x+

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

Eigenschappen	Standaard	Beschrijving
connectionMode	Gateway	De verbindingsmodus die door de functie wordt gebruikt bij het maken van verbinding met de Azure Cosmos DB-service. Opties zijn Direct en Gateway
userAgentSuffix	N.v.t.	Hiermee voegt u de opgegeven tekenreekswaarde toe aan alle aanvragen die door de trigger of binding aan de service zijn gedaan. Hierdoor kunt u de activiteit in Azure Monitor gemakkelijker bijhouden op basis van een specifieke functie-app en filteren User Agentop.

Functions 2.x+

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

Eigenschappen	Standaard	Beschrijving
connectionMode	Gateway	De verbindingsmodus die door de functie wordt gebruikt bij het maken van verbinding met de Azure Cosmos DB-service. Opties zijn Direct en Gateway
protocol	Https	Het verbindingsprotocol dat door de functie wordt gebruikt wanneer verbinding wordt gemaakt met de Azure Cosmos DB-service. Lees hier voor een uitleg van beide modi.
leasePrefix	N.v.t.	Leasevoorvoegsel voor gebruik in alle functies in een app.

Volgende stappen

• Een functie uitvoeren wanneer een Azure Cosmos DB-document wordt gemaakt of gewijzigd (trigger)
• Een Azure Cosmos DB-document lezen (invoerbinding)
• Wijzigingen opslaan in een Azure Cosmos DB-document (uitvoerbinding)