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

  • Artikel

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:

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

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.

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.

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.

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

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.

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

Nächste Schritte