Freigeben über


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. Im Änderungsfeed werden neue und aktualisierte Elemente veröffentlicht. Aktualisierungen aufgrund von Löschungen sind nicht enthalten.

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

Skalierungsentscheidungen von Cosmos DB für Verbrauchs- und Premium-Pläne werden über zielbasierte Skalierung getroffen. Weitere Informationen finden Sie unter Zielbasierte Skalierung.

Wichtig

In diesem Artikel werden Registerkarten verwendet, um mehrere Versionen des Node.js-Programmiermodells zu unterstützen. Das v4-Modell ist allgemein verfügbar und bietet JavaScript- und TypeScript-Entwicklern eine flexiblere und intuitivere Erfahrung. Weitere Informationen zur Funktionsweise des v4-Modells finden Sie im Azure Functions Node.js-Entwicklerhandbuch. Weitere Informationen zu den Unterschieden zwischen v3 und v4 finden Sie im Migrationshandbuch.

Azure Functions unterstützt zwei Programmiermodelle für Python. Wie Sie Ihre Bindung definieren, hängt vom gewählten Python-Programmiermodell ab.

Mit dem Python v2-Programmiermodell können Sie Bindungen mithilfe von Decorators direkt im Python-Funktionscode definieren. Weitere Informationen finden Sie im Python Developer-Leitfaden.

In diesem Artikel werden beide Programmiermodelle unterstützt.

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 Klassenbibliothek in einem isolierten Workerprozess ist eine kompilierte C#-Funktion, die in einem von der Runtime isolierten Prozess ausgeführt wird.

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

Dieses Beispiel bezieht sich auf einen einfachen ToDoItem-Typ:

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

Die folgende Funktion wird aufgerufen, wenn es Einfügungen oder Aktualisierungen in der angegebenen Datenbank und Sammlung gibt.

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "ToDoItems",
    containerName:"TriggerItems",
    Connection = "CosmosDBConnection",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> todoItems,
    FunctionContext context)
{
    if (todoItems is not null && todoItems.Any())
    {
        foreach (var doc in todoItems)
        {
            _logger.LogInformation("ToDoItem: {desc}", doc.Description);
        }
    }
}

Diese Funktion wird aufgerufen, wenn in der angegebenen Datenbank und im angegebenen Container Einfügungen oder Aktualisierungen vorhanden sind.

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.

    @FunctionName("CosmosDBTriggerFunction")
    public void run(
        @CosmosDBTrigger(
            name = "items",
            databaseName = "ToDoList",
            containerName = "Items",
            leaseContainerName="leases",
            connection = "AzureCosmosDBConnection",
            createLeaseContainerIfNotExists = true
        )
        Object inputItem,
        final ExecutionContext context
    ) {
        context.getLogger().info("Items modified: " + inputItems.size());
    }

Verwenden Sie die @CosmosDBTrigger-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Parameter, deren Wert von Azure 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 TypeScript-Funktion für einen Azure Cosmos DB-Trigger. Die Funktion schreibt Protokollmeldungen, wenn Azure Cosmos DB-Datensätze geändert oder hinzugefügt werden.

import { app, InvocationContext } from '@azure/functions';

export async function cosmosDBTrigger1(documents: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Cosmos DB function processed ${documents.length} documents`);
}

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: cosmosDBTrigger1,
});

Das folgende Beispiel zeigt eine JavaScript-Funktion für einen Azure Cosmos DB-Trigger. Die Funktion schreibt Protokollmeldungen, wenn Azure Cosmos DB-Datensätze geändert oder hinzugefügt werden.

const { app } = require('@azure/functions');

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: (documents, context) => {
        context.log(`Cosmos DB function processed ${documents.length} documents`);
    },
});

Das folgende Beispiel zeigt, wie eine Funktion bei Datenänderungen in Azure 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 $Documents 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 Azure Cosmos DB-Triggerbindung. Das Beispiel hängt davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(name="documents", 
                       connection="CONNECTION_SETTING",
                       database_name="DB_NAME", 
                       container_name="CONTAINER_NAME", 
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def test_function(documents: func.DocumentList) -> str:
    if documents:
        logging.info('Document id: %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, wie im C#-Skript-Handbuch beschrieben.

Attributeigenschaft BESCHREIBUNG
Connection 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 dem überwachten Container.
ContainerName Der Name des überwachten Containers.
LeaseConnection (Optional) Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit dem Azure Cosmos DB-Konto hergestellt werden soll, das den Leasecontainer enthält.

Wenn nicht festgelegt, wird der Wert Connection verwendet. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird. Die Verbindungszeichenfolge für den Leasecontainer muss über Schreibberechtigungen verfügen.
LeaseDatabaseName (Optional) Der Name der Datenbank, in der der Container zum Speichern von Leases enthalten ist. Wenn nicht festgelegt, wird der Wert der databaseName-Einstellung verwendet.
LeaseContainerName (Optional) Der Name des Containers, der zum Speichern von Leases verwendet wird. Wenn nicht festgelegt, wird der Wert leases verwendet.
CreateLeaseContainerIfNotExists (Optional) Bei Festlegung auf true wird der Leasecontainer automatisch erstellt, falls er noch nicht vorhanden ist. Der Standardwert ist false. Wenn Sie Microsoft Entra-Identitäten verwenden und den Wert true festlegen, ist das Erstellen von Containern kein zulässiger Vorgang, und Ihre Funktion kann nicht gestartet werden.
LeasesContainerThroughput (Optional) Definiert die Anzahl von Anforderungseinheiten, die zugewiesen werden, wenn der Leasecontainer erstellt wird. Diese Einstellung wird nur verwendet, wenn CreateLeaseContainerIfNotExists auf true festgelegt ist. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird.
LeaseContainerPrefix (Optional) Wird diese Option festgelegt, wird der Wert den im Leasecontainer für diese Funktion erstellten Leases als Präfix hinzugefügt. Die Verwendung eines Präfixes ermöglicht die Nutzung des gleichen Leasecontainers 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).
MaxItemsPerInvocation (Optional:) Diese Eigenschaft legt die Höchstzahl von Elementen fest, die pro Funktionsaufruf empfangen werden können. Wenn Vorgänge im überwachten Container ü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) Durch diese Option wird der Trigger angewiesen, Änderungen beginnend vom Anfang des Änderungsverlaufs des Containers 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.
StartFromTime (Optional) Dient zum Abrufen oder Festlegen des Zeitpunkts (Datum und Uhrzeit), ab dem der Lesevorgang für den Änderungsfeed initialisiert werden soll. Als Format wird ISO 8601 mit UTC-Kennzeichner empfohlen (also beispielsweise 2021-02-16T14:19:29Z). Diese Option wird nur zum Festlegen des anfänglichen Triggerzustands verwendet. Sobald der Trigger über einen Leasezustand verfügt, hat das Ändern dieses Werts keine Auswirkungen mehr.
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“.

Decorator-Elemente

Gilt nur für das Python v2-Programmiermodell.

Für Python v2-Funktionen, die mithilfe eines Decorators definiert wurden, gelten die folgenden Eigenschaften für cosmos_db_trigger:

Eigenschaft BESCHREIBUNG
arg_name Der im Code der Funktion verwendete Variablenname, der die Liste der Dokumente mit Änderungen darstellt.
database_name Der Name der Azure Cosmos DB-Datenbank mit der überwachten Sammlung.
collection_name Der Name der Azure Cosmos DB-Sammlung, die überwacht wird.
connection Die Verbindungszeichenfolge der zu überwachenden Azure Cosmos DB.

Informationen zu Python-Funktionen, die mithilfe von function.json definiert wurden, finden Sie im Abschnitt Konfiguration.

Anmerkungen

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.

Verwenden Sie die @CosmosDBTrigger Anmerkung für Parameter, die Daten aus Azure Cosmos DB lesen. Für die Anmerkung werden folgende Eigenschaften unterstützt:

Attributeigenschaft BESCHREIBUNG
connection 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.
name Der Name der Funktion.
databaseName Der Name der Azure Cosmos DB-Datenbank mit dem überwachten Container.
containerName Der Name des überwachten Containers.
leaseConnectionStringSetting (Optional) Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit dem Azure Cosmos DB-Konto hergestellt werden soll, das den Leasecontainer enthält.

Wenn nicht festgelegt, wird der Wert Connection verwendet. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird. Die Verbindungszeichenfolge für den Leasecontainer muss über Schreibberechtigungen verfügen.
leaseDatabaseName (Optional) Der Name der Datenbank, in der der Container zum Speichern von Leases enthalten ist. Wenn nicht festgelegt, wird der Wert der databaseName-Einstellung verwendet.
leaseContainerName (Optional) Der Name des Containers, der zum Speichern von Leases verwendet wird. Wenn nicht festgelegt, wird der Wert leases verwendet.
createLeaseContainerIfNotExists (Optional) Bei Festlegung auf true wird der Leasecontainer automatisch erstellt, falls er noch nicht vorhanden ist. Der Standardwert ist false. Wenn Sie Microsoft Entra-Identitäten verwenden, wenn Sie den Wert truefestlegen, ist das Erstellen von Containern kein zulässiger Vorgang , und Ihre Funktion wird nicht gestartet.
leasesContainerThroughput (Optional) Definiert die Anzahl von Anforderungseinheiten, die zugewiesen werden, wenn der Leasecontainer erstellt wird. Diese Einstellung wird nur verwendet, wenn CreateLeaseContainerIfNotExists auf true festgelegt ist. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird.
leaseContainerPrefix (Optional) Wird diese Option festgelegt, wird der Wert den im Leasecontainer für diese Funktion erstellten Leases als Präfix hinzugefügt. Die Verwendung eines Präfixes ermöglicht die Nutzung des gleichen Leasecontainers 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 verlängert wird, läuft sie ab und der Besitz der Partition wird zu einer anderen Instanz verschoben. 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).
maxItemsPerInvocation (Optional:) Diese Eigenschaft legt die Höchstzahl von Elementen fest, die pro Funktionsaufruf empfangen werden können. Wenn Vorgänge im überwachten Container ü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) Durch diese Option wird der Trigger angewiesen, Änderungen beginnend vom Anfang des Änderungsverlaufs des Containers 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“.

Konfiguration

Gilt nur für das Python v1-Programmiermodell.

In der folgenden Tabelle werden die Eigenschaften erläutert, die Sie für das options-Objekt festlegen können, das an die app.cosmosDB()-Methode übergeben wird. Die Eigenschaften type, direction und name gelten nicht für das Modell v4.

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.
connection 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 dem überwachten Container.
containerName Der Name des überwachten Containers.
leaseConnection (Optional) Der Name einer App-Einstellung oder eines Einstellungscontainers, die bzw. der angibt, wie eine Verbindung mit dem Azure Cosmos DB-Konto hergestellt werden soll, das den Leasecontainer enthält.

Wenn nicht festgelegt, wird der Wert connection verwendet. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird. Die Verbindungszeichenfolge für den Leasecontainer muss über Schreibberechtigungen verfügen.
leaseDatabaseName (Optional) Der Name der Datenbank, in der der Container zum Speichern von Leases enthalten ist. Wenn nicht festgelegt, wird der Wert der databaseName-Einstellung verwendet.
leaseContainerName (Optional) Der Name des Containers, der zum Speichern von Leases verwendet wird. Wenn nicht festgelegt, wird der Wert leases verwendet.
createLeaseContainerIfNotExists (Optional) Bei Festlegung auf true wird der Leasecontainer automatisch erstellt, falls er noch nicht vorhanden ist. Der Standardwert ist false. Wenn Sie Microsoft Entra-Identitäten verwenden und den Wert true festlegen, ist das Erstellen von Containern kein zulässiger Vorgang, und Ihre Funktion kann nicht gestartet werden.
leasesContainerThroughput (Optional) Definiert die Anzahl von Anforderungseinheiten, die zugewiesen werden, wenn der Leasecontainer erstellt wird. Diese Einstellung wird nur verwendet, wenn createLeaseContainerIfNotExists auf true festgelegt ist. Dieser Parameter wird automatisch festgelegt, wenn die Bindung im Portal erstellt wird.
leaseContainerPrefix (Optional) Wird diese Option festgelegt, wird der Wert den im Leasecontainer für diese Funktion erstellten Leases als Präfix hinzugefügt. Die Verwendung eines Präfixes ermöglicht die Nutzung des gleichen Leasecontainers 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).
maxItemsPerInvocation (Optional:) Diese Eigenschaft legt die Höchstzahl von Elementen fest, die pro Funktionsaufruf empfangen werden können. Wenn Vorgänge im überwachten Container ü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) Durch diese Option wird der Trigger angewiesen, Änderungen beginnend vom Anfang des Änderungsverlaufs des Containers 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.
startFromTime (Optional) Dient zum Abrufen oder Festlegen des Zeitpunkts (Datum und Uhrzeit), ab dem der Lesevorgang für den Änderungsfeed initialisiert werden soll. Als Format wird ISO 8601 mit UTC-Kennzeichner empfohlen (also beispielsweise 2021-02-16T14:19:29Z). Diese Option wird nur zum Festlegen des anfänglichen Triggerzustands verwendet. Sobald der Trigger über einen Leasezustand verfügt, hat das Ändern dieses Werts keine Auswirkungen mehr.
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“.

Vollständige Beispiele finden Sie im Abschnitt Beispiele.

Verwendung

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

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.

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.

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, kann die App anstelle einer Verbindungszeichenfolge mit einem Geheimnis eine Microsoft Entra-Identität verwenden. 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. Daher müssen Sie für die meisten Azure-Dienste eine Rolle in Azure RBAC zuweisen, indem Sie entweder integrierte oder benutzerdefinierte Rollen verwenden, die diese Berechtigungen bieten.

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.

Azure RBAC wird von Cosmos DB nicht für Datenvorgänge verwendet. Stattdessen wird ein in Cosmos DB integriertes RBAC-System verwendet, das auf ähnlichen Konzepten basiert. Sie müssen eine Rollenzuweisung erstellen, die zur Laufzeit Zugriff auf Ihr Datenbankkonto ermöglicht. Azure RBAC-Verwaltungsrollen wie Besitzer sind nicht ausreichend. Die folgende Tabelle zeigt integrierte Rollen, die für den normalen Betrieb mit der Azure Cosmos DB-Erweiterung empfohlen werden. Ihre Anwendung erfordert möglicherweise zusätzliche Berechtigungen basierend auf dem von Ihnen geschriebenen Code.

Bindungstyp Beispiele für integrierte Rollen1
Trigger2 Integrierter Mitwirkender an Cosmos DB-Daten
Eingabebindung Integrierter Cosmos DB-Datenleser
Ausgabebindung Integrierter Mitwirkender an Cosmos DB-Daten

1 Diese Rollen können nicht in einer Azure RBAC-Rollenzuweisung verwendet werden. Ausführliche Informationen zum Zuweisen dieser Rollen finden Sie in der Dokumentation zum in Cosmos DB integrierten RBAC-System.

2 Bei Verwendung von Identitäten behandelt Cosmos DB die Containererstellung als Verwaltungsvorgang. Es ist nicht als Datenebenenvorgang für den Trigger verfügbar. Sie müssen sicherstellen, dass Sie die vom Trigger benötigten Container (einschließlich des Leasecontainers) erstellen, bevor Sie Ihre Funktion einrichten.

Nächste Schritte