Übersicht über Azure Cosmos DB-Trigger und -Bindungen für Azure Functions 2.x oder höher

• Version 1
• Version 2 oder höher

In dieser Gruppe von Artikeln wird die Verwendung von Azure Cosmos DB-Bindungen in Azure Functions 2.x oder höher erläutert. 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	Trigger
Lesen eines Azure Cosmos DB-Dokuments	Eingabebindung
Speichern der Änderungen an einem Azure Cosmos DB-Dokument	Ausgabebindung

Hinweis

Dieser Verweis gilt für Azure Functions Version 2.x oder höher. Informationen zur Verwendung dieser Bindungen in Functions 1.x finden Sie unter Azure Cosmos DB-Bindungen für Azure Functions.

Diese Bindung hatte ursprünglich die Bezeichnung „DocumentDB“. In der Azure Functions-Version 2.x oder höher wurden der Trigger, die Bindungen und das Paket jeweils mit dem Namen „Azure Cosmos DB“ versehen.

Unterstützte APIs

Azure Cosmos DB-Bindungen werden nur in Kombination mit Azure Cosmos DB for NoSQL unterstützt. Unterstützung für Azure Cosmos DB for Table wird durch das Verwenden der Tabellenspeicherbindungen ab Erweiterung 5.x bereitgestellt. Für alle anderen Azure Cosmos DB-APIs sollten Sie von Ihrer Funktion aus auf die Datenbank zugreifen, indem Sie den statischen Client für Ihre API verwenden, einschließlich Azure Cosmos DB for MongoDB, Azure Cosmos DB for Cassandra und Azure Cosmos DB for Apache Gremlin.

Installieren der Erweiterung

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

Isoliertes Workermodell

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.

In-Process-Modell

Wichtig

Die Unterstützung für das In-Process-Modell endet am 10. November 2026. Es wird dringend empfohlen, Ihre Apps zum isolierten Workermodell zu migrieren, um den vollständigen Support zu ermöglichen.

Funktionen werden im gleichen Prozess wie der Functions-Host ausgeführt. Weitere Informationen finden Sie unter Entwickeln von C#-Klassenbibliotheksfunktionen mithilfe von Azure Functions.

In einer Variante dieses Modells kann Functions mithilfe von C#-Skripts ausgeführt werden. Dies wird hauptsächlich für die Bearbeitung im C#-Portal unterstützt. Um vorhandene Bindungserweiterungen für C#-Skriptanwendungen zu aktualisieren, die im Portal ausgeführt werden, ohne Ihre Funktions-App erneut veröffentlichen zu müssen, lesen Sie Aktualisieren von Erweiterungen.

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

Erweiterung 4.x oder höher

In diesem Abschnitt wird die Verwendung einer Klassenbibliothek beschrieben. Für C#-Skripterstellung müssen Sie stattdessen das Erweiterungspaket (Version 4.x) installieren.

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.

Mit dieser Version werden auch die Typen geändert, mit denen eine Bindung erfolgen kann. Dabei werden die Typen aus dem v2-SDK Microsoft.Azure.DocumentDB durch neuere Typen aus dem v3-SDK Microsoft.Azure.Cosmos ersetzt. Weitere Informationen zu den Unterschieden zwischen diesen neuen Typen und zur Migration zu ihnen finden Sie im SDK-Migrationsleitfaden sowie in den Beispielen zu Triggern, Eingabebindungen und Ausgabebindungen.

Diese Erweiterungsversion ist als NuGet-Paket, Version 4.x, verfügbar.

Functions 2.x oder höher

In diesem Abschnitt wird die Verwendung einer Klassenbibliothek beschrieben. Für C#-Skripterstellung müssen Sie stattdessen das Erweiterungspaket (Version 2.x oder 3.x) installieren.

: Das Arbeiten mit Triggern und Bindungen erfordert, dass Sie auf das entsprechende NuGet-Paket verweisen. Installieren Sie Version 3.x des NuGet-Pakets.

Erweiterung 4.x oder höher

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

Functions 2.x oder höher

Fügen Sie Ihrem Projekt die Erweiterung hinzu, indem Sie Version 3.x des NuGet-Pakets installieren.

Installieren des Pakets

Die Erweiterung für Azure Cosmos DB-Bindungen gehört zu einem Erweiterungspaket für die Vorschau, das in Ihrer Projektdatei host.json angegeben ist. Möglicherweise müssen Sie dieses Paket ändern, um die Version der Bindung zu ändern, oder wenn Pakete noch nicht installiert sind. Weitere Informationen finden Sie unter 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.

Paket v4.x

Diese Version des Pakets enthält Version 4.x der Azure Cosmos DB-Bindungserweiterung, mit der die Möglichkeit eingeführt wird, 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.

Sie können diese Version der Erweiterung aus dem Vorschauerweiterungspaket v4 hinzufügen, indem Sie den folgenden Code in der Datei host.json hinzufügen oder ersetzen:

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

Weitere Informationen finden Sie unter Aktualisierung Ihrer Erweiterungen.

Bundle v2.x und v3.x

Sie können diese Version der Erweiterung in Ihrer Funktions-App installieren, indem Sie das Erweiterungspaket (Version 2.x oder 3.x) registrieren.

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

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:

Isoliertes Workermodell

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

In-Process-Modell

Eine In-Process-Klassenbibliothek ist eine kompilierte C#-Funktion, die im gleichen Prozess wie die Functions-Runtime ausgeführt wird.

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

Erweiterung 4.x oder höher

Die Azure Cosmos DB-Erweiterung unterstützt Parametertypen gemäß der folgenden Tabelle.

Bindungsszenario	Parametertypen
Cosmos DB-Trigger (einzelnes Dokument)	JSON-serialisierbare Typen1
Cosmos DB-Trigger (Dokumentbatch)	IEnumerable<T>, wobei T ein serialisierbarer JSON-Typ ist1.
Cosmos DB-Eingabe (einzelnes Dokument)	JSON-serialisierbare Typen1
Cosmos DB-Eingabe (Abfrage, die mehrere Dokumente zurückgibt)	CosmosClient IEnumerable<T>, wobei T ein serialisierbarer JSON-Typ ist1.
Cosmos DB-Ausgabe (einzelnes Dokument)	JSON-serialisierbare Typen1
Cosmos DB-Ausgabe (mehrere Dokumente)	ICollector<T> oder IAsyncCollector<T>, wobei T ein serialisierbarer JSON-Typ ist1.

¹ Dokumente, die JSON-Daten enthalten, können in bekannte POCO-Typen (Plain-Old CLR Object) deserialisiert werden.

Functions 2.x oder höher

Frühere Versionen der Erweiterung haben Typen aus dem jetzt veralteten Microsoft.Azure.Documents-Namespace verfügbar gemacht. Neuere Typen aus Microsoft.Azure.Cosmos sind exklusiv für die Erweiterung 4.x und höher.

Erweiterung 4.x oder höher

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.

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

Für andere Ausgabeszenarien erstellen und verwenden Sie Typen direkt aus Microsoft.Azure.Cosmos.

Functions 2.x oder höher

Frühere Versionen von Erweiterungen im isolierten Workerprozess unterstützen nur die Bindung serialisierbare JSON-Typen. Weitere Optionen sind für die Erweiterung 4.x und höher verfügbar.

Ausnahmen und Rückgabecodes

Bindung	Verweis
Azure Cosmos DB	HTTP-Statuscodes für Azure Cosmos DB

Einstellungen für „host.json“

In diesem Abschnitt werden die für diese Bindung verfügbaren Konfigurationseinstellungen in Version 2.x und höher beschrieben. Einstellungen in der Datei „host.json“ gelten für alle Funktionen in einer Funktions-App-Instanz. Die nachfolgende Beispieldatei „host.json“ enthält nur die Einstellungen für Version 2.x und höhere Versionen für diese Bindung. Weitere Informationen zu den Konfigurationseinstellungen für Funktions-Apps in Version 2.x und höher finden Sie unter host.json-Referenz für Azure Functions.

Erweiterung 4.x oder höher

{
    "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. Die Optionen sind Direct und Gateway.
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.

Functions 2.x oder höher

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

Eigenschaft	Standard	Beschreibung
connectionMode	Gateway	Der von der Funktion zum Herstellen von Verbindungen mit dem Azure Cosmos DB-Dienst verwendete Verbindungsmodus. Die Optionen sind Direct und Gateway.
protocol	Https	Das von der Funktion zum Herstellen von Verbindungen mit dem Azure Cosmos DB-Dienst verwendete Verbindungsprotokoll. Hier finden Sie eine Erläuterung der beiden Modi.
leasePrefix	–	Lease-Präfix, das durchgängig für alle Funktionen in einer App verwendet wird.

Nächste Schritte

• Ausführen einer Funktion, wenn ein Azure Cosmos DB-Dokument erstellt oder geändert wird (Trigger)
• Lesen eines Azure Cosmos DB-Dokuments (Eingabebindung)
• Speichern der Änderungen an einem Azure Cosmos DB-Dokument (Ausgabebindung)