Freigeben über

Übersicht über Azure Cosmos DB-Trigger und -Bindungen für Azure Functions

In diesem Artikel wird erläutert, wie Sie mit Azure Cosmos DB-Bindungen in Azure Functions arbeiten. Azure Functions unterstützt Trigger sowie Ein- und Ausgabebindungen für Azure Cosmos DB.

Aktion type
Ausführen einer Funktion, wenn ein Azure Cosmos DB-Dokument erstellt oder geändert wird Auslösen
Lesen eines Azure Cosmos DB-Dokuments Eingabebindung
Speichern der Änderungen an einem Azure Cosmos DB-Dokument Ausgabebindung

Wichtig

Diese Version der Azure Cosmos DB-Bindungserweiterung unterstützt Azure Functions, Version 4.x. Wenn Ihre App weiterhin Version 1.x der Funktionslaufzeit verwendet, lesen Sie stattdessen Azure Cosmos DB-Bindungen für Azure Functions 1.x. In der Functions v1.x-Laufzeit wurde diese Bindung ursprünglich benannt DocumentDB.

Unterstützte APIs

Diese Tabelle gibt an, wie Sie über Ihren Funktionscode eine Verbindung mit den verschiedenen Azure Cosmos DB-APIs herstellen:

API Empfehlung
Azure Cosmos DB für NoSQL Verwenden der Azure Cosmos DB-Bindungserweiterung
Azure Cosmos DB für MongoDB Verwenden Sie ein systemeigenes Client-SDK.
Azure Cosmos DB für Tabelle Verwenden Sie Version 5.x oder höher der Azure Tables-Bindungserweiterung.
Azure Cosmos DB für Apache Cassandra Verwenden Sie ein systemeigenes Client-SDK.
Azure Cosmos DB für Apache Gremlin (Graph-API) Verwenden eines nativen Client-SDK
Azure Cosmos DB für PostgreSQL Verwenden Sie ein systemeigenes Client-SDK.

Installieren der Erweiterung

Das NuGet-Erweiterungspaket, das Sie installieren, hängt vom C#-Modus ab, den Sie in Ihrer Funktions-App verwenden:

Funktionen werden in einem isolierten C#-Workerprozess ausgeführt. Weitere Informationen finden Sie im Leitfaden zum Ausführen von Azure Functions (C#) in einem isolierten Workerprozess.

Der Prozess zum Installieren der Erweiterung ist abhängig von der Erweiterungsversion unterschiedlich:

Mit dieser Version der Bindungserweiterung für Azure Cosmos DB wird die Möglichkeit eingeführt, eine Verbindung mithilfe einer Identität anstelle eines Geheimnisses herzustellen. Ein Tutorial zum Konfigurieren Ihrer Funktions-Apps mit verwalteten Identitäten finden Sie im Tutorial zum Erstellen einer Funktions-App mit identitätsbasierten Verbindungen.

Fügen Sie ihrem Projekt die Erweiterung hinzu, indem Sie das NuGet-Paket, Version 4.x, installieren.

Wenn Sie Ihre Anwendung mit F# schreiben, müssen Sie diese Erweiterung auch als Teil der Startkonfiguration der App konfigurieren. Fügen Sie im Aufruf von ConfigureFunctionsWorkerDefaults() oder ConfigureFunctionsWebApplication() einen Delegate hinzu, der einen IFunctionsWorkerApplication-Parameter akzeptiert. Rufen Sie dann im Textkörper dieses Delegat ConfigureCosmosDBExtension() für das Objekt auf:

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

Installieren des Pakets

Um diese Bindungserweiterung in Ihrer App verwenden zu können, stellen Sie sicher, dass die host.json Datei im Stammverzeichnis Ihres Projekts diesen extensionBundle Verweis enthält:

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

In diesem Beispiel weist der version Wert des [4.0.0, 5.0.0) Funktionenhosts an, eine Bundleversion zu verwenden, die mindestens 4.0.0 aber kleiner ist als 5.0.0, die alle potenziellen Versionen von 4.x enthält. Diese Notation verwaltet Ihre App effektiv auf der neuesten verfügbaren Nebenversion des v4.x-Erweiterungspakets.

Wenn möglich, sollten Sie die neueste Hauptversion des Erweiterungspakets verwenden und der Laufzeit erlauben, die neueste Nebenversion automatisch zu verwalten. Sie können den Inhalt des neuesten Bundles auf der Releaseseite der Erweiterungspakete anzeigen. Weitere Informationen finden Sie unter Azure Functions-Erweiterungspakete.

Aufgrund von Schemaänderungen im Azure Cosmos DB-SDK ist azure-functions-java-library V3.0.0 für Java-Funktionen der Azure Cosmos DB-Erweiterung Version 4.x erforderlich.

Bindungstypen

Die für .NET unterstützten Bindungstypen hängen sowohl von der Erweiterungsversion als auch von dem C#-Ausführungsmodus ab, der einer der folgenden sein kann:

Eine Klassenbibliothek in einem isolierten Workerprozess ist eine kompilierte C#-Funktion, die in einem von der Runtime isolierten Prozess ausgeführt wird.

Wählen Sie eine Version aus, um für den Modus und die Version Details zum Bindungstyp anzuzeigen.

Der isolierte Workerprozess unterstützt Parametertypen gemäß den folgenden Tabellen. Unterstützung für die Bindung an Typen aus Microsoft.Azure.Cosmos befindet sich in der Vorschau.

Cosmos DB-Trigger

Wenn die Funktion ein einzelnes Dokument verarbeiten soll, kann der Cosmos DB-Trigger an die folgenden Typen gebunden werden:

type BESCHREIBUNG
Serialisierbare JSON-Typen Functions versucht, die JSON-Daten des Dokuments aus dem Cosmos DB-Änderungsfeed in einen POCO-Typ (Plain-Old CLR Object) zu deserialisieren.

Wenn die Funktion einen Batch von Dokumenten verarbeiten soll, kann der Cosmos DB-Trigger an die folgenden Typen gebunden werden:

type BESCHREIBUNG
IEnumerable<T>, wobei T ein serialisierbarer JSON-Typ ist. Eine Enumeration von Entitäten, die im Batch enthalten sind. Jeder Eintrag stellt ein Dokument aus dem Cosmos DB-Änderungsfeed dar.

Cosmos DB-Eingabebindung

Wenn die Funktion ein einzelnes Dokument verarbeiten soll, kann die Cosmos DB-Eingabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
Serialisierbare JSON-Typen Functions versucht, die JSON-Daten des Dokuments in einen POCO-Typ (Plain-Old CLR Object) zu deserialisieren.

Wenn die Funktion mehrere Dokumente aus einer Abfrage verarbeiten soll, kann die Cosmos DB-Eingabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
IEnumerable<T>, wobei T ein serialisierbarer JSON-Typ ist. Eine Enumeration von Entitäten, die von der Abfrage zurückgegeben werden. Jeder Eintrag stellt eine Entität dar.
CosmosClient1 Ein Client, der mit dem Cosmos DB-Konto verbunden ist.
Datenbank1 Ein Client, der mit der Cosmos DB-Datenbank verbunden ist.
Container1 Ein Client, der mit dem Cosmos DB-Container verbunden ist.

1 Um diese Typen zu verwenden, müssen Sie auf Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0-preview1 oder höher und die gemeinsamen Abhängigkeiten für SDK-Typbindungen verweisen.

Cosmos DB-Ausgabebindung

Wenn die Funktion in ein einzelnes Dokument schreiben soll, kann die Cosmos DB-Ausgabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
Serialisierbare JSON-Typen Ein Objekt, das den JSON-Inhalt eines Dokuments darstellt. Functions versucht, einen POCO-Typ (Plain-Old CLR Object) in JSON-Daten zu serialisieren.

Wenn die Funktion in mehrere Dokumente schreiben soll, kann die Cosmos DB-Ausgabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
T[], wobei T ein serialisierbarer JSON-Typ ist Ein Array, das mehrere Dokumente enthält. Jeder Eintrag stellt eine Entität dar.

Erstellen und verwenden Sie für andere Ausgabeszenarien einen CosmosClient mit anderen Typen von Microsoft.Azure.Cosmos direkt. Ein Beispiel für die Verwendung der Abhängigkeitsinjektion zum Erstellen eines Clienttyps aus dem Azure SDK finden Sie unter Registrieren von Azure-Clients .

SDK-Bindungstypen

Die SDK-Typunterstützung für Azure Cosmos befindet sich in der Vorschau. Folgen Sie dem Python SDK-Bindungen für CosmosDB-Beispiel , um mit SDK-Typen für Cosmos in Python zu beginnen.

Wichtig

Für die Verwendung von SDK-Typbindungen ist das Python v2-Programmiermodell erforderlich.

Bindung Parametertypen Beispiele
CosmosDB-Eingabe ContainerProxy,
CosmosClient,
DatabaseProxy
 ContainerProxy,
CosmosClient,
DatabaseProxy

Ausnahmen und Rückgabecodes

Bindung Verweis
Azure Cosmos DB (ein Microsoft-Datenbankdienst) HTTP-Statuscodes für Azure Cosmos DB

Einstellungen für „host.json“

In diesem Abschnitt werden die Konfigurationseinstellungen beschrieben, die für diese Bindung in Version 2.x und höher verfügbar sind. Einstellungen in der Datei „host.json“ gelten für alle Funktionen in einer Funktions-App-Instanz. Weitere Informationen zu Konfigurationseinstellungen für Funktionen-Apps finden Sie unter host.json Referenz für Azure Functions.

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}
Eigenschaft Standard BESCHREIBUNG
connectionMode Gateway Der von der Funktion zum Herstellen von Verbindungen mit dem Azure Cosmos DB-Dienst verwendete Verbindungsmodus. Optionen: Direct Stellt eine direkte Verbindung mit Back-End-Replikaten über TCP und kann eine geringere Latenz bereitstellen und Gateway Anforderungen über ein Front-End-Gateway über HTTPS weiterleiten. Weitere Informationen finden Sie unter Azure Cosmos DB SDK-Verbindungsmodi.
userAgentSuffix – Fügt allen Anforderungen, die vom Trigger oder der Bindung an den Dienst gestellt werden, den angegebenen Zeichenfolgenwert hinzu. Dies erleichtert Ihnen das Nachverfolgen der Aktivität in Azure Monitor basierend auf einer bestimmten Funktions-App und gefiltert nach User Agent.

Nächste Schritte

  • Last updated on