Azure Cosmos DB-utlösare för Azure Functions 2.x och senare

Azure Cosmos DB-utlösaren använder Azure Cosmos DB-ändringsflödet för att lyssna efter infogningar och uppdateringar mellan partitioner. Ändringsflödet publicerar infogningar och uppdateringar, inte borttagningar.

Information om installation och konfiguration finns i översikten.

Exempel

Användningen av utlösaren beror på versionen av tilläggspaketet och den C#-modalitet som används i funktionsappen, vilket kan vara något av följande:

Ett processbaserat klassbibliotek är en kompilerad C#-funktion som körs i samma process som Functions-körningen.

Följande exempel beror på tilläggsversionen för det angivna C#-läget.

I följande exempel visas en C#-funktion som anropas när det finns infogningar eller uppdateringar i den angivna databasen och samlingen.

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}");
            }
        }
    }
}

Den här funktionen anropas när det finns infogningar eller uppdateringar i den angivna databasen och samlingen.

    @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.");
            }

I Körningsbiblioteket för Java-funktioner använder du kommentaren @CosmosDBTrigger på parametrar vars värde kommer från Cosmos DB. Den här anteckningen kan användas med interna Java-typer, POJO:er eller null-värden med hjälp av Optional<T>.

I följande exempel visas en Cosmos DB-utlösarbindning i en function.json-fil och en JavaScript-funktion som använder bindningen. Funktionen skriver loggmeddelanden när Cosmos DB-poster läggs till eller ändras.

Här är bindningsdata i filen function.json :

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

Observera att några av namnen på bindningsattributen har ändrats i version 4.x av Azure Cosmos DB-tillägget.

Här är JavaScript-koden:

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

I följande exempel visas hur du kör en funktion när data ändras i Cosmos DB.

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

Observera att några av namnen på bindningsattributen har ändrats i version 4.x av Azure Cosmos DB-tillägget.

I filenrun.ps1 har du åtkomst till dokumentet som utlöser funktionen via parametern $Documents .

param($Documents, $TriggerMetadata) 

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

I följande exempel visas en Cosmos DB-utlösarbindning i en function.json-fil och en Python funktion som använder bindningen. Funktionen skriver loggmeddelanden när Cosmos DB-poster ändras.

Här är bindningsdata i filen function.json :

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

Observera att några av namnen på bindningsattributen har ändrats i version 4.x av Azure Cosmos DB-tillägget.

Här är den Python koden:

    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'])

Attribut

Både processbaserade och isolerade C#-bibliotek använder CosmosDBTriggerAttribute för att definiera funktionen. C#-skriptet använder i stället en function.json-konfigurationsfil.

Attributegenskap Description
ConnectionStringSetting Namnet på en appinställning eller inställningssamling som anger hur du ansluter till det Azure Cosmos DB-konto som övervakas. Mer information finns i Anslutningar.
DatabaseName Namnet på Azure Cosmos DB-databasen med samlingen som övervakas.
CollectionName Namnet på samlingen som övervakas.
LeaseConnectionStringSetting (Valfritt) Namnet på en appinställning eller inställningssamling som anger hur du ansluter till det Azure Cosmos DB-konto som innehåller lånesamlingen.

När värdet inte anges används det ConnectionStringSetting . Den här parametern anges automatiskt när bindningen skapas i portalen. Anslutningssträngen för lånesamlingen måste ha skrivbehörighet.
LeaseDatabaseName (Valfritt) Namnet på databasen som innehåller samlingen som används för att lagra lån. När den inte har angetts används värdet för inställningen databaseName .
LeaseCollectionName (Valfritt) Namnet på samlingen som används för att lagra lån. När värdet inte anges används det leases .
CreateLeaseCollectionIfNotExists (Valfritt) När den är inställd truepå skapas lånesamlingen automatiskt när den inte redan finns. Standardvärdet är false.
LeasesCollectionThroughput (Valfritt) Definierar antalet enheter för programbegäran som ska tilldelas när lånesamlingen skapas. Den här inställningen används bara när CreateLeaseCollectionIfNotExists är inställd på true. Den här parametern anges automatiskt när bindningen skapas med hjälp av portalen.
LeaseCollectionPrefix (Valfritt) När värdet anges läggs värdet till som ett prefix till de lån som skapats i leasesamlingen för den här funktionen. Med ett prefix kan två separata Azure Functions dela samma lånesamling med hjälp av olika prefix.
FeedPollDelay (Valfritt) Tiden (i millisekunder) för fördröjningen mellan avsökningen av en partition för nya ändringar i feeden, när alla aktuella ändringar har tömts. Standardvärdet är 5 000 millisekunder eller 5 sekunder.
LeaseAcquireInterval (Valfritt) När den ställs in definierar den i millisekunder intervallet för att starta en uppgift för att beräkna om partitioner distribueras jämnt mellan kända värdinstanser. Standardvärdet är 13 000 (13 sekunder).
LeaseExpirationInterval (Valfritt) När den anges definierar den i millisekunder det intervall för vilket lånet tas på ett lån som representerar en partition. Om lånet inte förnyas inom det här intervallet upphör det att gälla och ägarskapet för partitionen flyttas till en annan instans. Standardvärdet är 60 000 (60 sekunder).
LeaseRenewInterval (Valfritt) När den anges definierar den, i millisekunder, förnyelseintervallet för alla lån för partitioner som för närvarande innehas av en instans. Standardvärdet är 17 000 (17 sekunder).
CheckpointInterval (Valfritt) När den anges definierar den intervallet mellan lånekontrollpunkterna i millisekunder. Standardvärdet är alltid efter varje funktionsanrop.
CheckpointDocumentCount (Valfritt) Anpassar mängden dokument mellan lånekontrollpunkter. Standardvärdet är efter varje funktionsanrop.
MaxItemsPerInvocation (Valfritt) När den här egenskapen anges anger den maximala antalet objekt som tas emot per funktionsanrop. Om åtgärder i den övervakade samlingen utförs via lagrade procedurer bevaras transaktionsomfånget vid läsning av objekt från ändringsflödet. Därför kan antalet mottagna objekt vara högre än det angivna värdet så att objekten som ändras av samma transaktion returneras som en del av en atomisk batch.
StartFromBeginning (Valfritt) Det här alternativet instruerar utlösaren att läsa ändringar från början av samlingens ändringshistorik i stället för att starta vid den aktuella tidpunkten. Läsning från början fungerar bara första gången utlösaren startar, eftersom kontrollpunkterna redan lagras i efterföljande körningar. Att ange det här alternativet till true när det redan finns lån har skapats har ingen effekt.
PreferredLocations (Valfritt) Definierar önskade platser (regioner) för geo-replikerade databaskonton i Azure Cosmos DB-tjänsten. Värdena ska vara kommaavgränsade. Till exempel "USA, östra, USA, södra centrala, Europa, norra".
UseMultipleWriteLocations (Valfritt) Aktiverar konton i flera regioner för att skriva till lånesamlingen.
UseDefaultJsonSerialization (Valfritt) Låter dig använda JsonConvert.DefaultSettings i den övervakade samlingen. Den här inställningen gäller endast för den övervakade samlingen och konsumenten för att konfigurera serialiseringen som används i den övervakade samlingen. JsonConvert.DefaultSettings måste anges i en klass som härletts från CosmosDBWebJobsStartup.

Anteckningar

Konfiguration

I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i filen function.json , där egenskaperna skiljer sig åt beroende på tilläggsversion:

function.json-egenskap Description
Typ Måste anges till cosmosDBTrigger.
Riktning Måste anges till in. Den här parametern anges automatiskt när du skapar utlösaren i Azure Portal.
Namn Variabelnamnet som används i funktionskoden som representerar listan över dokument med ändringar.
connectionStringSetting Namnet på en appinställning eller inställningssamling som anger hur du ansluter till det Azure Cosmos DB-konto som övervakas. Mer information finns i Anslutningar.
Databasename Namnet på Azure Cosmos DB-databasen med samlingen som övervakas.
collectionName Namnet på samlingen som övervakas.
leaseConnectionStringSetting (Valfritt) Namnet på en appinställning eller inställningssamling som anger hur du ansluter till det Azure Cosmos DB-konto som innehåller lånesamlingen.

När värdet inte har angetts används det connectionStringSetting . Den här parametern anges automatiskt när bindningen skapas i portalen. Anslutningssträngen för lånesamlingen måste ha skrivbehörighet.
leaseDatabaseName (Valfritt) Namnet på databasen som innehåller samlingen som används för att lagra lån. När inställningen inte har angetts används värdet för inställningen databaseName .
leaseCollectionName (Valfritt) Namnet på samlingen som används för att lagra lån. När värdet inte har angetts används det leases .
createLeaseCollectionIfNotExists (Valfritt) När den är inställd på trueskapas lånesamlingen automatiskt när den inte redan finns. Standardvärdet är false.
leasesCollectionThroughput (Valfritt) Definierar antalet enheter för begäranden som ska tilldelas när lånesamlingen skapas. Den här inställningen används bara när createLeaseCollectionIfNotExists är inställd på true. Den här parametern anges automatiskt när bindningen skapas med hjälp av portalen.
leaseCollectionPrefix (Valfritt) När värdet anges läggs värdet till som ett prefix till lånen som skapats i samlingen Lån för den här funktionen. Med ett prefix kan två separata Azure Functions dela samma lånesamling med hjälp av olika prefix.
feedPollDelay (Valfritt) Tiden (i millisekunder) för fördröjningen mellan avsökningen av en partition för nya ändringar i flödet, när alla aktuella ändringar har tömts. Standardvärdet är 5 000 millisekunder eller 5 sekunder.
leaseAcquireInterval (Valfritt) När den anges definierar den i millisekunder intervallet för att starta en uppgift för att beräkna om partitioner fördelas jämnt mellan kända värdinstanser. Standardvärdet är 13 000 (13 sekunder).
leaseExpirationInterval (Valfritt) När den anges definierar den i millisekunder det intervall för vilket lånet tas på ett lån som representerar en partition. Om lånet inte förnyas inom det här intervallet upphör det att gälla och ägarskapet för partitionen flyttas till en annan instans. Standardvärdet är 6 0000 (60 sekunder).
leaseRenewInterval (Valfritt) När den anges definierar den, i millisekunder, förnyelseintervallet för alla lån för partitioner som för närvarande innehas av en instans. Standardvärdet är 17 000 (17 sekunder).
checkpointInterval (Valfritt) När den anges definierar den i millisekunder intervallet mellan lånekontrollpunkter. Standardinställningen är alltid efter varje funktionsanrop.
checkpointDocumentCount (Valfritt) Anpassar mängden dokument mellan lånekontrollpunkter. Standardinställningen är efter varje funktionsanrop.
maxItemsPerInvocation (Valfritt) När den här egenskapen anges anger den maximalt antal objekt som tas emot per funktionsanrop. Om åtgärder i den övervakade samlingen utförs via lagrade procedurer bevaras transaktionsomfånget vid läsning av objekt från ändringsflödet. Därför kan antalet mottagna objekt vara högre än det angivna värdet så att objekten som ändras av samma transaktion returneras som en del av en atomisk batch.
startFromBeginning (Valfritt) Det här alternativet uppmanar utlösaren att läsa ändringar från början av samlingens ändringshistorik i stället för att starta vid den aktuella tidpunkten. Läsning från början fungerar bara första gången utlösaren startar, eftersom kontrollpunkterna redan lagras i efterföljande körningar. Om du anger det här alternativet till true när det redan finns lån har skapats har det ingen effekt.
preferredLocations (Valfritt) Definierar prioriterade platser (regioner) för geo-replikerade databaskonton i Azure Cosmos DB-tjänsten. Värdena ska vara kommaavgränsade. Till exempel "USA, östra, USA, södra centrala, Europa, norra".
useMultipleWriteLocations (Valfritt) Aktiverar konton i flera regioner för att skriva till lånesamlingen.

Se avsnittet Exempel för fullständiga exempel.

Användning

Parametertypen som stöds av Azure Cosmos DB-utlösaren beror på functions-körningsversionen, tilläggspaketversionen och den C#-modalitet som används.

Utlösaren kräver en andra samling som används för att lagra lån över partitionerna. Både samlingen som övervakas och samlingen som innehåller lånen måste vara tillgänglig för att utlösaren ska fungera.

Viktigt

Om flera funktioner har konfigurerats för att använda en Cosmos DB-utlösare för samma samling bör var och en av funktionerna använda en dedikerad lånesamling eller ange en annan LeaseCollectionPrefix för varje funktion. Annars utlöses bara en av funktionerna. Information om prefixet finns i avsnittet Konfiguration.

Viktigt

Om flera funktioner har konfigurerats för att använda en Cosmos DB-utlösare för samma samling bör var och en av funktionerna använda en dedikerad lånesamling eller ange en annan leaseCollectionPrefix för varje funktion. Annars utlöses bara en av funktionerna. Information om prefixet finns i avsnittet Konfiguration.

Utlösaren anger inte om ett dokument har uppdaterats eller infogats, utan innehåller bara själva dokumentet. Om du behöver hantera uppdateringar och infogningar på olika sätt kan du göra det genom att implementera tidsstämpelfält för infogning eller uppdatering.

Anslutningar

connectionStringSetting/connection Egenskaperna och leaseConnectionStringSetting/leaseConnection är referenser till miljökonfigurationen som anger hur appen ska ansluta till Azure Cosmos DB. De kan ange följande:

Om det konfigurerade värdet både är en exakt matchning för en enda inställning och en prefixmatchning för andra inställningar används den exakta matchningen.

Anslutningssträng

Anslutningssträngen för ditt databaskonto ska lagras i en programinställning med ett namn som matchar värdet som anges av anslutningsegenskapen för bindningskonfigurationen.

Identitetsbaserade anslutningar

Om du använder version 4.x eller senare av tillägget kan du i stället för att använda en anslutningssträng med en hemlighet låta appen använda en Azure Active Directory identitet. För att göra detta definierar du inställningar under ett vanligt prefix som mappar till anslutningsegenskapen i utlösaren och bindningskonfigurationen.

I det här läget kräver tillägget följande egenskaper:

Egenskap Miljövariabelmall Description Exempelvärde
Kontoslutpunkt <CONNECTION_NAME_PREFIX>__accountEndpoint Azure Cosmos DB-kontots slutpunkts-URI. <https:// database_account_name.documents.azure.com:443/>

Ytterligare egenskaper kan anges för att anpassa anslutningen. Se Vanliga egenskaper för identitetsbaserade anslutningar.

När identitetsbaserade anslutningar finns i Azure Functions-tjänsten använder de en hanterad identitet. Den systemtilldelade identiteten credential används som standard, även om en användartilldelad identitet kan anges med egenskaperna och clientID . Observera att det inte går att konfigurera en användartilldelad identitet med ett resurs-ID. När du kör i andra sammanhang, till exempel lokal utveckling, används utvecklaridentiteten i stället, även om detta kan anpassas. Se Lokal utveckling med identitetsbaserade anslutningar.

Bevilja behörighet till identiteten

Den identitet som används måste ha behörighet att utföra de avsedda åtgärderna. Du måste tilldela en roll i Azure RBAC med hjälp av antingen inbyggda eller anpassade roller som ger dessa behörigheter.

Viktigt

Vissa behörigheter kan exponeras av måltjänsten som inte är nödvändiga för alla kontexter. Om möjligt följer du principen om lägsta behörighet och beviljar identiteten endast nödvändiga privilegier. Om appen till exempel bara behöver kunna läsa från en datakälla använder du en roll som bara har behörighet att läsa. Det skulle vara olämpligt att tilldela en roll som också tillåter skrivning till tjänsten, eftersom det skulle vara överdrivet med behörighet för en läsåtgärd. På samma sätt vill du se till att rolltilldelningen endast är begränsad till de resurser som behöver läsas.

Du måste skapa en rolltilldelning som ger åtkomst till ditt databaskonto vid körning. Hanteringsroller som Ägare räcker inte. I följande tabell visas inbyggda roller som rekommenderas när du använder Cosmos DB-tillägget i normal drift. Ditt program kan kräva ytterligare behörigheter baserat på den kod du skriver.

Bindningstyp Exempel på inbyggda roller
Utlösare Inbyggd Cosmos DB-datadeltagare
Indatabindning Inbyggd Cosmos DB-dataläsare
Utdatabindning Inbyggd Cosmos DB-datadeltagare

Nästa steg