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

  • Artikel

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:

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.

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

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

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.

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.

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:

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

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

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.

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

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

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

Volgende stappen