Azure Cosmos DB-Trigger für Azure Functions 2.x und höher

Informationen zum partitionsübergreifenden Lauschen auf Einfügungen und Aktualisierungen durch den Azure Cosmos DB-Trigger finden Sie unter Verwenden der Unterstützung von Änderungsfeeds in Azure Cosmos DB. Der Änderungsfeed veröffentlicht Einfügungen und Updates, keine Löschungen.

Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

Beispiel

Die Verwendung des Triggers hängt von der Version des Erweiterungspakets und der C#-Modalität ab, die in Ihrer Funktions-App verwendet wird. Dies kann eine der folgenden Modalitäten sein:

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

Die folgenden Beispiele hängen von der Erweiterungsversion für den jeweiligen C#-Modus ab:

Das folgende Beispiel zeigt eine C#-Funktion, die aufgerufen wird, wenn etwas in der angegebenen Datenbank und Sammlung eingefügt oder aktualisiert wird.

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            ILogger log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.LogInformation($"Documents modified: {documents.Count}");
                log.LogInformation($"First document Id: {documents[0].Id}");
            }
        }
    }
}

Diese Funktion wird aufgerufen, wenn etwas in der angegebenen Datenbank und Sammlung eingefügt oder aktualisiert wird.

    @FunctionName("cosmosDBMonitor")
    public void cosmosDbProcessor(
        @CosmosDBTrigger(name = "items",
            databaseName = "ToDoList",
            collectionName = "Items",
            leaseCollectionName = "leases",
            createLeaseCollectionIfNotExists = true,
            connectionStringSetting = "AzureCosmosDBConnection") String[] items,
            final ExecutionContext context ) {
                context.getLogger().info(items.length + "item(s) is/are changed.");
            }

Verwenden Sie die -Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Parameter, deren Wert von Cosmos DB empfangen wird. Diese Anmerkung kann mit nativen Java-Typen, POJOs oder Werten mit Optional<T>, die NULL-Werte annehmen können, verwendet werden.

Das folgende Beispiel zeigt eine Cosmos DB-Triggerbindung in einer Datei function.json sowie eine JavaScript-Funktion, die die Bindung verwendet. Die Funktion schreibt Protokollmeldungen, wenn Cosmos DB-Datensätze geändert oder hinzugefügt werden.

Bindungsdaten in der Datei function.json:

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Beachten Sie, dass sich einige der Bindungsattributnamen in Version 4.x der Azure Cosmos DB-Erweiterung geändert haben.

Der JavaScript-Code sieht wie folgt aus:

    module.exports = async function (context, documents) {
      context.log('First document Id modified : ', documents[0].id);
    }

Das folgende Beispiel zeigt, wie eine Funktion bei Datenänderungen in Cosmos DB ausgeführt wird.

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Beachten Sie, dass sich einige der Bindungsattributnamen in Version 4.x der Azure Cosmos DB-Erweiterung geändert haben.

In der Datei run.ps1 können Sie über den Parameter auf das Dokument zugreifen, das die Funktion auslöst.

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)" 

Das folgende Beispiel zeigt eine Cosmos DB-Triggerbindung in einer Datei namens function.json sowie eine Python-Funktion, die die Bindung verwendet. Die Funktion schreibt Protokollmeldungen, wenn Cosmos DB-Datensätze geändert werden.

Bindungsdaten in der Datei function.json:

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Beachten Sie, dass sich einige der Bindungsattributnamen in Version 4.x der Azure Cosmos DB-Erweiterung geändert haben.

Dies ist der Python-Code:

    import logging
    import azure.functions as func


    def main(documents: func.DocumentList) -> str:
        if documents:
            logging.info('First document Id modified: %s', documents[0]['id'])

Attributes

Sowohl von C#-Bibliotheken vom Typ In-Process als auch von C#-Bibliotheken vom Typ Isolierter Prozess wird CosmosDBTriggerAttribute verwendet, um die Funktion zu definieren. Das C#-Skript verwendet stattdessen eine Konfigurationsdatei „function.json“.

Attributeigenschaft BESCHREIBUNG
ConnectionStringSetting Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit dem zu überwachenden Azure Cosmos DB-Konto hergestellt werden soll. Weitere Informationen finden Sie unter Verbindungen.
DatabaseName Der Name der Azure Cosmos DB-Datenbank mit der überwachten Sammlung.
CollectionName Der Name der überwachten Sammlung.
LeaseConnectionStringSetting (Optional) Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit dem Azure Cosmos DB-Konto hergestellt werden soll, das die Leasesammlung enthält.

Wenn nicht festgelegt, wird der Wert ConnectionStringSetting verwendet. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird. Die Verbindungszeichenfolge für die Leasesammlung muss über Schreibberechtigungen verfügen.
LeaseDatabaseName (Optional) Der Name der Datenbank, in der die Sammlung zum Speichern von Leases enthalten ist. Wenn nicht festgelegt, wird der Wert der databaseName-Einstellung verwendet.
LeaseCollectionName (Optional) Der Name der Sammlung, die zum Speichern von Leases verwendet wird. Wenn nicht festgelegt, wird der Wert leases verwendet.
CreateLeaseCollectionIfNotExists (Optional) Bei Festlegung auf true wird die Sammlung von Leases automatisch erstellt, wenn sie nicht bereits vorhanden ist. Standardwert: false.
LeasesCollectionThroughput (Optional:) Definiert die Anzahl von Anforderungseinheiten, die zugewiesen werden, wenn die Leasesammlung erstellt wird. Diese Einstellung wird nur verwendet, wenn CreateLeaseCollectionIfNotExists auf true festgelegt ist. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird.
LeaseCollectionPrefix (Optional) Wird diese Option festgelegt, wird der Wert den in der Leasesammlung für diese Funktion erstellten Leases als Präfix hinzugefügt. Die Verwendung eines Präfix ermöglicht die Nutzung derselben Leasesammlung durch zwei separate Azure-Funktionen über unterschiedliche Präfixe.
FeedPollDelay (Optional:) die Verzögerung (in Millisekunden) zwischen den Abfragen an eine Partition nach neuen Änderungen im Feed, nachdem alle aktuellen Änderungen beseitigt wurden. Der Standardwert beträgt 5.000 Millisekunden (oder fünf Sekunden).
LeaseAcquireInterval (Optional) Wenn gesetzt, wird das Intervall in Millisekunden definiert, das eine Aufgabe anstößt, die berechnet, ob Partitionen unter den bekannten Hostinstanzen gleichmäßig verteilt sind. Der Standardwert ist 13000 (13 Sekunden).
LeaseExpirationInterval (Optional) Wenn gesetzt, wird das Intervall in Millisekunden definiert, für das die Lease für eine Lease, die eine Partition darstellt, ausgeführt wird. Wenn die Lease innerhalb dieses Intervalls nicht erneuert wird, läuft sie ab, und der Besitz der Partition wechselt zu einer anderen Instanz. Der Standardwert ist 60000 (60 Sekunden).
LeaseRenewInterval (Optional) Wenn gesetzt, wird das Erneuerungsintervall in Millisekunden für alle Leases für Partitionen definiert, die aktuell in einer Instanz vorhanden sind. Der Standardwert ist 17000 (17 Sekunden).
CheckpointInterval (Optional) Wenn gesetzt, wird das Intervall in Millisekunden zwischen Leaseprüfpunkten definiert. Dies ist standardmäßig immer nach einem erfolgreichen Funktionsaufruf der Fall.
CheckpointDocumentCount (Optional) Passt die Menge der Dokumente zwischen Leaseprüfpunkten an. Wird standardmäßig nach jedem Funktionsaufruf ausgeführt.
MaxItemsPerInvocation (Optional:) Diese Eigenschaft legt die Höchstzahl von Elementen fest, die pro Funktionsaufruf empfangen werden können. Wenn Vorgänge in der überwachten Sammlung über gespeicherte Prozeduren ausgeführt werden, wird der Transaktionsbereich beim Lesen von Elementen aus dem Änderungsfeed beibehalten. Dadurch kann die Anzahl der empfangenen Elemente höher als der angegebene Wert sein, sodass die von derselben Transaktion geänderten Elemente als Teil eines atomischen Batches zurückgegeben werden.
StartFromBeginning (Optional:) Diese Option weist den Trigger an, Änderungen beginnend vom Anfang des Änderungsverlaufs der Sammlung anstatt ab der aktuellen Zeit zu lesen. Das Lesen von Anfang an funktioniert nur beim ersten Start des Triggers. Bei nachfolgenden Ausführungen sind die Prüfpunkte bereits gespeichert. Wenn die Leases bereits erstellt wurden, hat das Festlegen dieser Option auf true keine Auswirkungen.
PreferredLocations (Optional) Definiert bevorzugte Standorte (Regionen) für georeplizierte Datenbankkonten im Azure Cosmos DB-Dienst. Werte sollten durch Trennzeichen getrennt sein. Beispiel: „USA, Osten,USA, Süden-Mitte,Europa, Norden“.
UseMultipleWriteLocations (Optional) Aktiviert Konten in mehreren Regionen für Schreibvorgänge in die Leasesammlung.
UseDefaultJsonSerialization (Optional) Ermöglicht die Verwendung von JsonConvert.DefaultSettings in der überwachten Sammlung. Diese Einstellung gilt nur für die überwachte Sammlung und den Consumer, um die in der überwachten Sammlung verwendete Serialisierung einzurichten. JsonConvert.DefaultSettings muss in einer von CosmosDBWebJobsStartup abgeleiteten Klasse festgelegt werden.

Anmerkungen

Verwenden Sie die -Anmerkung in der Runtimebibliothek für Java-Funktionen für Parameter, die Daten aus Cosmos DB lesen. Für die Anmerkung werden folgende Eigenschaften unterstützt:

Konfiguration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die in der Datei function.json festgelegt werden, sowie über Eigenschaftsunterschiede nach Erweiterungsversion:

Eigenschaft von „function.json“ BESCHREIBUNG
type Muss auf cosmosDBTrigger festgelegt sein.
direction Muss auf in festgelegt sein. Dieser Parameter wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
name Der im Code der Funktion verwendete Variablenname, der die Liste der Dokumente mit Änderungen darstellt.
connectionStringSetting Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit dem zu überwachenden Azure Cosmos DB-Konto hergestellt werden soll. Weitere Informationen finden Sie unter Verbindungen.
databaseName Der Name der Azure Cosmos DB-Datenbank mit der überwachten Sammlung.
collectionName Der Name der überwachten Sammlung.
leaseConnectionStringSetting (Optional) Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit dem Azure Cosmos DB-Konto hergestellt werden soll, das die Leasesammlung enthält.

Wenn nicht festgelegt, wird der Wert connectionStringSetting verwendet. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird. Die Verbindungszeichenfolge für die Leasesammlung muss über Schreibberechtigungen verfügen.
leaseDatabaseName (Optional) Der Name der Datenbank, in der die Sammlung zum Speichern von Leases enthalten ist. Wenn nicht festgelegt, wird der Wert der databaseName-Einstellung verwendet.
leaseCollectionName (Optional) Der Name der Sammlung, die zum Speichern von Leases verwendet wird. Wenn nicht festgelegt, wird der Wert leases verwendet.
createLeaseCollectionIfNotExists (Optional) Bei Festlegung auf true wird die Sammlung von Leases automatisch erstellt, wenn sie nicht bereits vorhanden ist. Standardwert: false.
leasesCollectionThroughput (Optional:) Definiert die Anzahl von Anforderungseinheiten, die zugewiesen werden, wenn die Leasesammlung erstellt wird. Diese Einstellung wird nur verwendet, wenn createLeaseCollectionIfNotExists auf true festgelegt ist. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird.
leaseCollectionPrefix (Optional) Wird diese Option festgelegt, wird der Wert den in der Leasesammlung für diese Funktion erstellten Leases als Präfix hinzugefügt. Die Verwendung eines Präfix ermöglicht die Nutzung derselben Leasesammlung durch zwei separate Azure-Funktionen über unterschiedliche Präfixe.
feedPollDelay (Optional:) die Verzögerung (in Millisekunden) zwischen den Abfragen an eine Partition nach neuen Änderungen im Feed, nachdem alle aktuellen Änderungen beseitigt wurden. Der Standardwert beträgt 5.000 Millisekunden (oder fünf Sekunden).
leaseAcquireInterval (Optional) Wenn gesetzt, wird das Intervall in Millisekunden definiert, das eine Aufgabe anstößt, die berechnet, ob Partitionen unter den bekannten Hostinstanzen gleichmäßig verteilt sind. Der Standardwert ist 13000 (13 Sekunden).
leaseExpirationInterval (Optional) Wenn gesetzt, wird das Intervall in Millisekunden definiert, für das die Lease für eine Lease, die eine Partition darstellt, ausgeführt wird. Wenn die Lease innerhalb dieses Intervalls nicht erneuert wird, läuft sie ab, und der Besitz der Partition wechselt zu einer anderen Instanz. Der Standardwert ist 60000 (60 Sekunden).
leaseRenewInterval (Optional) Wenn gesetzt, wird das Erneuerungsintervall in Millisekunden für alle Leases für Partitionen definiert, die aktuell in einer Instanz vorhanden sind. Der Standardwert ist 17000 (17 Sekunden).
checkpointInterval (Optional) Wenn gesetzt, wird das Intervall in Millisekunden zwischen Leaseprüfpunkten definiert. Dies ist standardmäßig immer nach einem erfolgreichen Funktionsaufruf der Fall.
checkpointDocumentCount (Optional) Passt die Menge der Dokumente zwischen Leaseprüfpunkten an. Wird standardmäßig nach jedem Funktionsaufruf ausgeführt.
maxItemsPerInvocation (Optional:) Diese Eigenschaft legt die Höchstzahl von Elementen fest, die pro Funktionsaufruf empfangen werden können. Wenn Vorgänge in der überwachten Sammlung über gespeicherte Prozeduren ausgeführt werden, wird der Transaktionsbereich beim Lesen von Elementen aus dem Änderungsfeed beibehalten. Dadurch kann die Anzahl der empfangenen Elemente höher als der angegebene Wert sein, sodass die von derselben Transaktion geänderten Elemente als Teil eines atomischen Batches zurückgegeben werden.
startFromBeginning (Optional:) Diese Option weist den Trigger an, Änderungen beginnend vom Anfang des Änderungsverlaufs der Sammlung anstatt ab der aktuellen Zeit zu lesen. Das Lesen von Anfang an funktioniert nur beim ersten Start des Triggers. Bei nachfolgenden Ausführungen sind die Prüfpunkte bereits gespeichert. Wenn die Leases bereits erstellt wurden, hat das Festlegen dieser Option auf true keine Auswirkungen.
preferredLocations (Optional) Definiert bevorzugte Standorte (Regionen) für georeplizierte Datenbankkonten im Azure Cosmos DB-Dienst. Werte sollten durch Trennzeichen getrennt sein. Beispiel: „USA, Osten,USA, Süden-Mitte,Europa, Norden“.
useMultipleWriteLocations (Optional) Aktiviert Konten in mehreren Regionen für Schreibvorgänge in die Leasesammlung.

Vollständige Beispiele finden Sie im Abschnitt „Beispiele“.

Verwendung

Der vom Azure Cosmos DB-Trigger unterstützte Parametertyp hängt von der Version der Functions-Runtime, von der Version des Erweiterungspakets sowie von der verwendeten C#-Modalität ab.

Der Trigger erfordert eine zweite Sammlung, die er zum Speichern von Leases auf den Partitionen verwendet. Sowohl die überwachte Sammlung als auch die, die die Leases enthält, muss verfügbar sein, damit der Trigger funktioniert.

Wichtig

Falls mehrere Funktionen für die Verwendung eines Cosmos DB-Triggers für die gleiche Sammlung konfiguriert sind, muss jede dieser Funktionen eine dedizierte Leasesammlung verwenden oder für jede Funktion ein anderes LeaseCollectionPrefix angeben. Andernfalls wird nur eine der Funktionen ausgelöst. Weitere Informationen zum Präfix finden Sie im Abschnitt zu Attributen.

Wichtig

Falls mehrere Funktionen für die Verwendung eines Cosmos DB-Triggers für die gleiche Sammlung konfiguriert sind, muss jede dieser Funktionen eine dedizierte Leasesammlung verwenden oder für jede Funktion ein anderes leaseCollectionPrefix angeben. Andernfalls wird nur eine der Funktionen ausgelöst. Weitere Informationen zum Präfix finden Sie im Abschnitt zu Anmerkungen.

Wichtig

Falls mehrere Funktionen für die Verwendung eines Cosmos DB-Triggers für die gleiche Sammlung konfiguriert sind, muss jede dieser Funktionen eine dedizierte Leasesammlung verwenden oder für jede Funktion ein anderes leaseCollectionPrefix angeben. Andernfalls wird nur eine der Funktionen ausgelöst. Weitere Informationen zu diesem Präfix finden Sie im Konfigurationsabschnitt.

Der Trigger gibt nicht an, ob ein Dokument aktualisiert oder eingefügt wurde, er stellt das Dokument lediglich bereit. Wenn Sie Aktualisierungen und Einfügungen unterschiedlich verarbeiten müssen, können Sie dazu Zeitstempelfelder für Einfügung oder Aktualisierung implementieren.

Verbindungen

Die Eigenschaften connectionStringSetting/connection und leaseConnectionStringSetting/leaseConnection sind Verweise auf eine Umgebungskonfiguration, die angibt, wie sich die App mit Azure Cosmos DB verbinden soll. Damit kann Folgendes festgelegt werden:

  • Der Name einer Anwendungseinstellung, die eine Verbindungszeichenfolge enthält
  • Der Name eines gemeinsam genutzten Präfixes für mehrere Anwendungseinstellungen, die zusammen eine identitätsbasierte Verbindung definieren. Diese Option ist nur für die connection- und leaseConnection-Versionen ab connection verfügbar.

Wenn der konfigurierte Wert sowohl eine genaue Übereinstimmung für eine einzelne Einstellung als auch eine Präfix-Übereinstimmung für andere Einstellungen ist, wird die genaue Übereinstimmung verwendet.

Verbindungszeichenfolge

Die Verbindungszeichenfolge für Ihr Datenbankkonto sollte in einer Anwendungseinstellung mit einem Namen gespeichert werden, der dem in der Verbindungseigenschaft der Bindungskonfiguration angegebenen Wert entspricht.

Identitätsbasierte Verbindungen

Wenn Sie Version 4.x oder eine höhere Version der Erweiterung verwenden, können Sie die App anstelle einer Verbindungszeichenfolge mit einem Geheimnis eine Azure Active Directory-Identität verwenden lassen. Dazu definieren Sie Einstellungen unter einem gemeinsamen Präfix, das der Verbindungseigenschaft in der Trigger- und Bindungskonfiguration zugeordnet ist.

In diesem Modus benötigt die Erweiterung die folgenden Eigenschaften:

Eigenschaft Vorlage für Umgebungsvariable BESCHREIBUNG Beispielwert
Kontoendpunkt <CONNECTION_NAME_PREFIX>__accountEndpoint Der URI des Azure Cosmos DB-Kontoendpunkts. https://<Name_des_Datenbankkontos>.documents.azure.com:443/

Zusätzliche Eigenschaften können festgelegt werden, um die Verbindung anzupassen. Weitere Informationen finden Sie unter Allgemeine Eigenschaften für identitätsbasierte Verbindungen.

Identitätsbasierte Verbindungen verwenden eine verwaltete Identität, wenn sie im Azure Functions-Dienst gehostet werden. Standardmäßig wird eine vom System zugewiesene Identität verwendet, auch wenn mit den Eigenschaften credential und clientID eine vom Benutzer zugewiesene Identität angegeben werden kann. Beachten Sie, dass das Konfigurieren einer benutzerseitig zugewiesenen Identität mit einer Ressourcen-ID nicht unterstützt wird. Bei Ausführung in anderen Kontexten (z. B. bei der lokalen Entwicklung) wird stattdessen Ihre Entwickleridentität verwendet, Dieses Verhalten kann angepasst werden. Weitere Informationen finden Sie unter Lokale Entwicklung mit identitätsbasierten Verbindungen.

Erteilen der Berechtigung für die Identität

Unabhängig davon, welche Identität verwendet wird, muss diese über Berechtigungen zum Ausführen der vorgesehenen Aktionen verfügen. Sie müssen eine Rolle in Azure RBAC zuweisen, indem Sie entweder integrierte oder benutzerdefinierte Rollen verwenden, die diese Berechtigungen bereitstellen.

Wichtig

Vom Zieldienst werden möglicherweise einige nicht für alle Kontexte erforderliche Berechtigungen verfügbar gemacht. Befolgen Sie nach Möglichkeit das Prinzip der geringsten Berechtigung, und gewähren Sie der Identität nur die erforderlichen Berechtigungen. Wenn die App beispielsweise nur Daten aus einer Datenquelle lesen muss, verwenden Sie eine Rolle, die nur über Leseberechtigungen verfügt. Es wäre nicht angemessen, eine Rolle zu zuweisen, die auch das Schreiben in diesen Dienst zulässt, da dies eine übermäßige Berechtigung für einen Lesevorgang wäre. Ebenso sollten Sie sicherstellen, dass die Rollenzuweisung auf die Ressourcen begrenzt ist, die gelesen werden müssen.

Sie müssen eine Rollenzuweisung erstellen, die zur Laufzeit Zugriff auf Ihr Datenbankkonto ermöglicht. Verwaltungsrollen wie Besitzer sind nicht ausreichend. Die folgende Tabelle zeigt integrierte Rollen, die für den normalen Betrieb mit der Cosmos DB-Erweiterung empfohlen werden. Ihre Anwendung erfordert möglicherweise zusätzliche Berechtigungen basierend auf dem von Ihnen geschriebenen Code.

Bindungstyp Integrierte Beispielrollen
Trigger Integrierter Mitwirkender an Cosmos DB-Daten
Eingabebindung Integrierter Cosmos DB-Datenleser
Ausgabebindung Integrierter Mitwirkender an Cosmos DB-Daten

Nächste Schritte