Delen via

Azure Cosmos DB-invoerbinding voor Azure Functions 2.x en hoger

  • Artikel

Bij een Azure Cosmos DB-invoerbinding wordt de SQL-API gebruikt voor het ophalen van een of meer Azure Cosmos DB-documenten en het doorgeven daarvan aan de invoerparameter van de functie. De document-ID of queryparameters kunnen worden bepaald op basis van de trigger die de functie activeert.

Zie het overzicht voor informatie over het instellen en configureren van details.

Notitie

Wanneer de verzameling is gepartitioneerd, moeten opzoekbewerkingen ook de partitiesleutelwaarde opgeven.

Belangrijk

In dit artikel worden tabbladen gebruikt ter ondersteuning van meerdere versies van het Node.js programmeermodel. Het v4-model is algemeen beschikbaar en is ontworpen voor een flexibelere en intuïtievere ervaring voor JavaScript- en TypeScript-ontwikkelaars. Raadpleeg de ontwikkelaarshandleiding voor Azure Functions Node.js voor meer informatie over hoe het v4-model werkt. Raadpleeg de migratiehandleiding voor meer informatie over de verschillen tussen v3 en v4.

Azure Functions ondersteunt twee programmeermodellen voor Python. De manier waarop u uw bindingen definieert, is afhankelijk van het gekozen programmeermodel.

Met het Python v2-programmeermodel kunt u bindingen definiëren met behulp van decorators rechtstreeks in uw Python-functiecode. Zie de Ontwikkelaarshandleiding voor Python voor meer informatie.

Dit artikel ondersteunt beide programmeermodellen.

Opmerking

Tenzij anders vermeld, zijn voorbeelden in dit artikel gericht op versie 3.x van de Azure Cosmos DB-extensie. Voor gebruik met extensieversie 4.x moet u de tekenreeks collection in eigenschaps- en kenmerknamen vervangen door container.

U kunt een C#-functie maken met behulp van een van de volgende C#-modi:

  • Geïsoleerd werkrolmodel: gecompileerde C#-functie die wordt uitgevoerd in een werkproces dat is geïsoleerd van de runtime. Geïsoleerd werkproces is vereist voor de ondersteuning van C#-functies die worden uitgevoerd op LTS- en niet-LTS-versies .NET en .NET Framework. Extensies voor geïsoleerde werkprocesfuncties maken gebruik van Microsoft.Azure.Functions.Worker.Extensions.* naamruimten.
  • In-process model: gecompileerde C#-functie die wordt uitgevoerd in hetzelfde proces als de Functions-runtime. In een variatie van dit model kunnen functies worden uitgevoerd met behulp van C#-scripting. Dit wordt voornamelijk ondersteund voor het bewerken van de C#-portal. Extensies voor in-process-functies maken gebruik van Microsoft.Azure.WebJobs.Extensions.* naamruimten.

Belangrijk

De ondersteuning wordt beëindigd voor het in-process model op 10 november 2026. We raden u ten zeerste aan uw apps te migreren naar het geïsoleerde werkrolmodel voor volledige ondersteuning.

Deze sectie bevat voorbeelden waarvoor versie 3.x van de Azure Cosmos DB-extensie en 5.x van de Azure Storage-extensie is vereist. Als deze nog niet aanwezig is in uw functie-app, voegt u een verwijzing toe naar de volgende NuGet-pakketten:

De voorbeelden verwijzen naar een eenvoudig ToDoItem type:

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

Wachtrijtrigger, id opzoeken vanuit JSON

In het volgende voorbeeld ziet u een functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een JSON-bericht in de opslagwachtrij. De wachtrijtrigger parseert de JSON in een object van het type ToDoItemLookup, dat de id- en partitiesleutelwaarde bevat die moet worden opgehaald. Deze id- en partitiesleutelwaarde worden gebruikt om een ToDoItem document te retourneren uit de opgegeven database en verzameling.

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

Deze sectie bevat de volgende voorbeelden:

De voorbeelden verwijzen naar een eenvoudig ToDoItem type:

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

HTTP-trigger, id opzoeken uit querytekenreeks - tekenreeksparameter

In het volgende voorbeeld ziet u een Java-functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die gebruikmaakt van een querytekenreeks om de id en partitiesleutelwaarde op te geven die moeten worden opgezoekd. Deze id- en partitiesleutelwaarde worden gebruikt om een document op te halen uit de opgegeven database en verzameling, in tekenreeksvorm.

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

Gebruik in de Java Functions Runtime-bibliotheek de @CosmosDBInput aantekening voor functieparameters waarvan de waarde afkomstig is van Azure Cosmos DB. Deze aantekening kan worden gebruikt met systeemeigen Java-typen, POJO's of nullbare waarden met Optional<T>.

HTTP-trigger, id opzoeken uit querytekenreeks - POJO-parameter

In het volgende voorbeeld ziet u een Java-functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die gebruikmaakt van een querytekenreeks om de id en partitiesleutelwaarde op te geven die moeten worden opgezoekd. Deze id- en partitiesleutelwaarde die wordt gebruikt om een document op te halen uit de opgegeven database en verzameling. Het document wordt vervolgens geconverteerd naar een exemplaar van de ToDoItem POJO die eerder is gemaakt en doorgegeven als argument aan de functie.

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP-trigger, id opzoeken uit routegegevens

In het volgende voorbeeld ziet u een Java-functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die gebruikmaakt van een routeparameter om de id en partitiesleutelwaarde op te geven die moeten worden opgezoekd. Deze id- en partitiesleutelwaarde worden gebruikt om een document op te halen uit de opgegeven database en verzameling, waardoor het wordt geretourneerd als een Optional<String>.

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

HTTP-trigger, id opzoeken uit routegegevens, met behulp van SqlQuery

In het volgende voorbeeld ziet u een Java-functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die gebruikmaakt van een routeparameter om de id op te geven die moet worden opgezoekd. Deze id wordt gebruikt om een document op te halen uit de opgegeven database en verzameling, waarbij de resultatenset wordt geconverteerd naar een ToDoItem[], omdat veel documenten kunnen worden geretourneerd, afhankelijk van de querycriteria.

Notitie

Als u alleen een query wilt uitvoeren op de id, is het raadzaam om een opzoekactie te gebruiken, zoals in de vorige voorbeelden, omdat er minder aanvraageenheden worden verbruikt. Puntleesbewerkingen (GET) zijn efficiënter dan query's per id.

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP-trigger, meerdere documenten ophalen uit routegegevens met behulp van SqlQuery

In het volgende voorbeeld ziet u een Java-functie waarmee meerdere documenten worden opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die gebruikmaakt van een routeparameter desc om de tekenreeks op te geven waarnaar in het description veld moet worden gezocht. De zoekterm wordt gebruikt om een verzameling documenten op te halen uit de opgegeven database en verzameling, waarbij de resultatenset wordt geconverteerd naar een ToDoItem[] en deze als argument wordt doorgegeven aan de functie.

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

Deze sectie bevat de volgende voorbeelden die één document lezen door een id-waarde op te geven uit verschillende bronnen:

Wachtrijtrigger, id opzoeken vanuit JSON

In het volgende voorbeeld ziet u een TypeScript-functie die één document leest en de tekstwaarde van het document bijwerkt.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: false,
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

interface MyDocument {
    text: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const doc = <MyDocument>context.extraInputs.get(cosmosInput);
    doc.text = 'This was updated!';
    context.extraOutputs.set(cosmosOutput, doc);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: storageQueueTrigger1,
});

HTTP-trigger, id opzoeken uit querytekenreeks

In het volgende voorbeeld ziet u een TypeScript-functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die gebruikmaakt van een querytekenreeks om de id en partitiesleutelwaarde op te geven die moeten worden opgezoekd. Deze id- en partitiesleutelwaarde worden gebruikt om een ToDoItem document op te halen uit de opgegeven database en verzameling.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

HTTP-trigger, id opzoeken uit routegegevens

In het volgende voorbeeld ziet u een TypeScript-functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die routegegevens gebruikt om de id- en partitiesleutelwaarde op te geven om op te zoeken. Deze id- en partitiesleutelwaarde worden gebruikt om een ToDoItem document op te halen uit de opgegeven database en verzameling.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

Wachtrijtrigger, meerdere documenten ophalen met behulp van SqlQuery

In het volgende voorbeeld ziet u een TypeScript-functie waarmee meerdere documenten worden opgehaald die zijn opgegeven door een SQL-query, met behulp van een wachtrijtrigger om de queryparameters aan te passen.

De wachtrijtrigger biedt een parameter departmentId. Een wachtrijbericht van { "departmentId" : "Finance" } de afdeling Financiën retourneert alle records.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface MyDocument {}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
    for (const document of documents) {
        // operate on each document
    }
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: storageQueueTrigger1,
});

Deze sectie bevat de volgende voorbeelden die één document lezen door een id-waarde op te geven uit verschillende bronnen:

Wachtrijtrigger, id opzoeken vanuit JSON

In het volgende voorbeeld ziet u een JavaScript-functie die één document leest en de tekstwaarde van het document bijwerkt.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: false,
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: (queueItem, context) => {
        const doc = context.extraInputs.get(cosmosInput);
        doc.text = 'This was updated!';
        context.extraOutputs.set(cosmosOutput, doc);
    },
});

HTTP-trigger, id opzoeken uit querytekenreeks

In het volgende voorbeeld ziet u een JavaScript-functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die gebruikmaakt van een querytekenreeks om de id en partitiesleutelwaarde op te geven die moeten worden opgezoekd. Deze id- en partitiesleutelwaarde worden gebruikt om een ToDoItem document op te halen uit de opgegeven database en verzameling.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

HTTP-trigger, id opzoeken uit routegegevens

In het volgende voorbeeld ziet u een JavaScript-functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die routegegevens gebruikt om de id- en partitiesleutelwaarde op te geven om op te zoeken. Deze id- en partitiesleutelwaarde worden gebruikt om een ToDoItem document op te halen uit de opgegeven database en verzameling.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

Wachtrijtrigger, meerdere documenten ophalen met behulp van SqlQuery

In het volgende voorbeeld ziet u een JavaScript-functie waarmee meerdere documenten worden opgehaald die zijn opgegeven door een SQL-query, met behulp van een wachtrijtrigger om de queryparameters aan te passen.

De wachtrijtrigger biedt een parameter departmentId. Een wachtrijbericht van { "departmentId" : "Finance" } de afdeling Financiën retourneert alle records.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: (queueItem, context) => {
        const documents = context.extraInputs.get(cosmosInput);
        for (const document of documents) {
            // operate on each document
        }
    },
});

Wachtrijtrigger, id opzoeken vanuit JSON

In het volgende voorbeeld ziet u hoe u één Azure Cosmos DB-document kunt lezen en bijwerken. De unieke id van het document wordt verstrekt via JSON-waarde in een wachtrijbericht.

De Azure Cosmos DB-invoerbinding wordt eerst vermeld in de lijst met bindingen die zijn gevonden in het configuratiebestand van de functie (function.json).

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

Het bestand run.ps1 bevat de PowerShell-code waarmee het binnenkomende document wordt gelezen en wijzigingen worden uitgevoerd.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document

HTTP-trigger, id opzoeken uit querytekenreeks

In het volgende voorbeeld ziet u hoe u één Azure Cosmos DB-document kunt lezen en bijwerken vanuit een web-API. De unieke id van het document wordt verstrekt via een querytekenreeksparameter uit de HTTP-aanvraag, zoals gedefinieerd in de eigenschap van "Id": "{Query.Id}" de binding.

De Azure Cosmos DB-invoerbinding wordt eerst vermeld in de lijst met bindingen die zijn gevonden in het configuratiebestand van de functie (function.json).

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
}

Het bestand run.ps1 bevat de PowerShell-code waarmee het binnenkomende document wordt gelezen en wijzigingen worden uitgevoerd.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

HTTP-trigger, id opzoeken uit routegegevens

In het volgende voorbeeld ziet u hoe u één Azure Cosmos DB-document kunt lezen en bijwerken vanuit een web-API. De unieke id van het document wordt opgegeven via een routeparameter. De routeparameter wordt gedefinieerd in de eigenschap van route de HTTP-aanvraagbinding en waarnaar wordt verwezen in de azure Cosmos DB-bindingseigenschap "Id": "{Id}" .

De Azure Cosmos DB-invoerbinding wordt eerst vermeld in de lijst met bindingen die zijn gevonden in het configuratiebestand van de functie (function.json).

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
}

Het bestand run.ps1 bevat de PowerShell-code waarmee het binnenkomende document wordt gelezen en wijzigingen worden uitgevoerd.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

Wachtrijtrigger, meerdere documenten ophalen met behulp van SqlQuery

In het volgende voorbeeld ziet u hoe u meerdere Azure Cosmos DB-documenten kunt lezen. Het configuratiebestand van de functie (function.json) definieert de bindingseigenschappen, waaronder de sqlQuery. De SQL-instructie die aan de sqlQuery eigenschap is verstrekt, selecteert de set documenten die aan de functie zijn verstrekt.

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
}

Het bestand run1.ps1 bevat de PowerShell-code waarmee de inkomende documenten worden gelezen.

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
}

Deze sectie bevat de volgende voorbeelden die één document lezen door een id-waarde op te geven uit verschillende bronnen:

De voorbeelden zijn afhankelijk van het gebruik van het v1- of v2 Python-programmeermodel.

Wachtrijtrigger, id opzoeken vanuit JSON

In het volgende voorbeeld ziet u een Azure Cosmos DB-invoerbinding. De functie leest één document en werkt de tekstwaarde van het document bij.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.queue_trigger(arg_name="msg", 
                   queue_name="outqueue", 
                   connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents", 
                     database_name="MyDatabase",
                     collection_name="MyCollection",
                     id="{msg.payload_property}",
                     partition_key="{msg.payload_property}",
                     connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument", 
                      database_name="MyDatabase",
                      collection_name="MyCollection",
                      connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
                  inputDocument: func.DocumentList, 
                  outputDocument: func.Out[func.Document]):
     document = documents[id]
     document["text"] = "This was updated!"
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

HTTP-trigger, id opzoeken uit querytekenreeks

In het volgende voorbeeld ziet u een functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die gebruikmaakt van een querytekenreeks om de id en partitiesleutelwaarde op te geven die moeten worden opgezoekd. Deze id- en partitiesleutelwaarde worden gebruikt om een ToDoItem document op te halen uit de opgegeven database en verzameling.

Op dit moment is er geen equivalent voorbeeld voor v2.

HTTP-trigger, id opzoeken uit routegegevens

In het volgende voorbeeld ziet u een functie waarmee één document wordt opgehaald. De functie wordt geactiveerd door een HTTP-aanvraag die routegegevens gebruikt om de id- en partitiesleutelwaarde op te geven om op te zoeken. Deze id- en partitiesleutelwaarde worden gebruikt om een ToDoItem document op te halen uit de opgegeven database en verzameling.

Op dit moment is er geen equivalent voorbeeld voor v2.

Wachtrijtrigger, meerdere documenten ophalen met behulp van SqlQuery

In het volgende voorbeeld ziet u een Python-functie voor invoerbinding van Azure Cosmos DB die gebruikmaakt van de binding. De functie haalt meerdere documenten op die zijn opgegeven door een SQL-query, met behulp van een wachtrijtrigger om de queryparameters aan te passen.

De wachtrijtrigger biedt een parameter departmentId. Een wachtrijbericht van { "departmentId" : "Finance" } de afdeling Financiën retourneert alle records.

Op dit moment is er geen equivalent voorbeeld voor v2.

Kenmerken

Zowel in-process als geïsoleerde werkproces C#-bibliotheken gebruiken kenmerken om de functie te definiëren. C#-script maakt in plaats daarvan gebruik van een function.json configuratiebestand, zoals beschreven in de handleiding voor C#-scripts.

Kenmerkeigenschap Beschrijving
Verbinding De naam van een app-instelling of verzameling die aangeeft hoe verbinding moet worden gemaakt met het Azure Cosmos DB-account waarop een query wordt uitgevoerd. Zie Verbindingen voor meer informatie.
DatabaseName De naam van de Azure Cosmos DB-database met de container die wordt bewaakt.
ContainerName De naam van de container die wordt bewaakt.
PartitionKey Hiermee geeft u de partitiesleutelwaarde voor de zoekactie. Kan bindingsparameters bevatten. Het is vereist voor zoekacties in gepartitioneerde containers.
Id De id van het document dat moet worden opgehaald. Deze eigenschap ondersteunt bindingexpressies. Stel de eigenschappen SqlQuery niet inId. Als u geen van beide hebt ingesteld, wordt de hele container opgehaald.
SqlQuery Een Azure Cosmos DB SQL-query die wordt gebruikt voor het ophalen van meerdere documenten. De eigenschap ondersteunt runtimebindingen, zoals in dit voorbeeld: SELECT * FROM c where c.departmentId = {departmentId}. Stel de eigenschappen SqlQuery niet inId. Als u geen van beide hebt ingesteld, wordt de hele container opgehaald.
PreferredLocations (Optioneel) Definieert voorkeurslocaties (regio's) voor geo-gerepliceerde databaseaccounts in de Azure Cosmos DB-service. Waarden moeten door komma's worden gescheiden. Bijvoorbeeld: East US,South Central US,North Europe.

Decorators

Is alleen van toepassing op het Python v2-programmeermodel.

Python v2-functies worden gedefinieerd met behulp van de cosmos_db_input decorator, die deze eigenschappen ondersteunt, afhankelijk van de extensieversie:

Eigenschappen Beschrijving
arg_name De naam van de variabele die wordt gebruikt in functiecode die de lijst met documenten met wijzigingen vertegenwoordigt.
database_name De naam van de Azure Cosmos DB-database met de verzameling die wordt bewaakt.
container_name De naam van de Azure Cosmos DB-verzameling die wordt bewaakt.
connection De verbindingsreeks van de Azure Cosmos DB die wordt bewaakt.
partition_key De partitiesleutel van de Azure Cosmos DB die wordt bewaakt.
id De id van het document dat moet worden opgehaald.

Zie de sectie Configuratie voor Python-functies die zijn gedefinieerd met behulp van function.json.

Aantekeningen

Gebruik in de Java Functions Runtime-bibliotheek de @CosmosDBInput aantekening voor parameters die worden gelezen uit Azure Cosmos DB. De aantekening ondersteunt de volgende eigenschappen:

Configuratie

Is alleen van toepassing op het Python v1-programmeermodel.

In de volgende tabel worden de eigenschappen uitgelegd die u kunt instellen voor het options object dat aan de input.cosmosDB() methode is doorgegeven. De typeeigenschappen en directionname eigenschappen zijn niet van toepassing op het v4-model.

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u in het function.json-bestand hebt ingesteld, waarbij de eigenschappen verschillen per extensieversie:

function.json-eigenschap Beschrijving
type Moet worden ingesteld op cosmosDB.
direction Moet worden ingesteld op in.
name De naam van de variabele die wordt gebruikt in functiecode die de lijst met documenten met wijzigingen vertegenwoordigt.
verbinding De naam van een app-instelling of instellingscontainer die aangeeft hoe verbinding moet worden gemaakt met het Azure Cosmos DB-account dat wordt bewaakt. Zie Verbindingen voor meer informatie.
databaseName De naam van de Azure Cosmos DB-database met de container die wordt bewaakt.
containerName De naam van de container die wordt bewaakt.
partitionKey Hiermee geeft u de partitiesleutelwaarde voor de zoekactie. Kan bindingsparameters bevatten. Het is vereist voor zoekacties in gepartitioneerde containers.
id De id van het document dat moet worden opgehaald. Deze eigenschap ondersteunt bindingexpressies. Stel de eigenschappen sqlQuery niet inid. Als u geen van beide hebt ingesteld, wordt de hele container opgehaald.
sqlQuery Een Azure Cosmos DB SQL-query die wordt gebruikt voor het ophalen van meerdere documenten. De eigenschap ondersteunt runtimebindingen, zoals in dit voorbeeld: SELECT * FROM c where c.departmentId = {departmentId}. Stel de eigenschappen sqlQuery niet inid. Als u geen van beide hebt ingesteld, wordt de hele container opgehaald.
preferredLocations (Optioneel) Definieert voorkeurslocaties (regio's) voor geo-gerepliceerde databaseaccounts in de Azure Cosmos DB-service. Waarden moeten door komma's worden gescheiden. Bijvoorbeeld: East US,South Central US,North Europe.

Zie de sectie Voorbeeld voor volledige voorbeelden.

Gebruik

Wanneer de functie wordt afgesloten, worden alle wijzigingen die in het invoerdocument zijn aangebracht, automatisch behouden.

Het parametertype dat wordt ondersteund door de Cosmos DB-invoerbinding, is afhankelijk van de runtimeversie van Functions, de versie van het extensiepakket en de gebruikte C#-modaliteit.

Wanneer u wilt dat de functie één document verwerkt, kan de Cosmos DB-invoerbinding worden gekoppeld aan de volgende typen:

Type Description
JSON serialiseerbare typen Functions probeert de JSON-gegevens van het document te deserialiseren in een niet-oud CLR-objecttype (POCO).

Wanneer u wilt dat de functie meerdere documenten uit een query verwerkt, kan de Cosmos DB-invoerbinding worden gekoppeld aan de volgende typen:

Type Description
IEnumerable<T>waarbij T een type JSON serialiseerbaar is Een opsomming van entiteiten die door de query worden geretourneerd. Elke vermelding vertegenwoordigt één document.
CosmosClient1 Een client die is verbonden met het Cosmos DB-account.
Database1 Een client die is verbonden met de Cosmos DB-database.
Container1 Een client die is verbonden met de Cosmos DB-container.

1 Als u deze typen wilt gebruiken, moet u verwijzen naar Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 of hoger en de algemene afhankelijkheden voor SDK-typebindingen.

Vanuit de Runtime-bibliotheek van Java-functies maakt de @CosmosDBInput aantekening Azure Cosmos DB-gegevens beschikbaar voor de functie. Deze aantekening kan worden gebruikt met systeemeigen Java-typen, POJO's of nullbare waarden met Optional<T>.

Open het document met behulp van context.extraInputs.get().

Updates voor documenten worden niet automatisch uitgevoerd bij het afsluiten van de functie. Als u documenten in een functie wilt bijwerken, gebruikt u een uitvoerbinding. Zie het PowerShell-voorbeeld voor meer informatie.

Gegevens worden via een DocumentList parameter beschikbaar gesteld aan de functie. Wijzigingen die in het document zijn aangebracht, worden niet automatisch behouden.

Connecties

De connectionStringSetting/connection en leaseConnectionStringSetting/leaseConnection eigenschappen zijn verwijzingen naar de omgevingsconfiguratie die aangeeft hoe de app verbinding moet maken met Azure Cosmos DB. Ze kunnen het volgende opgeven:

Als de geconfigureerde waarde zowel een exacte overeenkomst is voor één instelling als een voorvoegselovereenkomst voor andere instellingen, wordt de exacte overeenkomst gebruikt.

Connection string

De verbindingsreeks voor uw databaseaccount moet worden opgeslagen in een toepassingsinstelling met een naam die overeenkomt met de waarde die is opgegeven door de verbindingseigenschap van de bindingsconfiguratie.

Op identiteit gebaseerde verbindingen

Als u versie 4.x of hoger van de extensie gebruikt, in plaats van een verbindingsreeks met een geheim te gebruiken, kunt u de app een Microsoft Entra-identiteit laten gebruiken. Hiervoor definieert u instellingen onder een gemeenschappelijk voorvoegsel dat is toegewezen aan de verbindingseigenschap in de trigger- en bindingsconfiguratie.

In deze modus vereist de extensie de volgende eigenschappen:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Accounteindpunt <CONNECTION_NAME_PREFIX>__accountEndpoint De eindpunt-URI van het Azure Cosmos DB-account. <https:// database_account_name.documents.azure.com:443/>

Er kunnen extra eigenschappen worden ingesteld om de verbinding aan te passen. Zie Algemene eigenschappen voor op identiteit gebaseerde verbindingen.

Wanneer deze worden gehost in de Azure Functions-service, maken identiteitsverbindingen gebruik van een beheerde identiteit. De door het systeem toegewezen identiteit wordt standaard gebruikt, hoewel een door de gebruiker toegewezen identiteit kan worden opgegeven met de credential en clientID eigenschappen. Houd er rekening mee dat het configureren van een door de gebruiker toegewezen identiteit met een resource-id niet wordt ondersteund. Wanneer uw ontwikkelaarsidentiteit wordt uitgevoerd in andere contexten, zoals lokale ontwikkeling, wordt in plaats daarvan uw ontwikkelaarsidentiteit gebruikt, hoewel dit kan worden aangepast. Zie Lokale ontwikkeling met op identiteit gebaseerde verbindingen.

Toestemming verlenen aan de identiteit

Elke identiteit die wordt gebruikt, moet machtigingen hebben om de beoogde acties uit te voeren. Voor de meeste Azure-services betekent dit dat u een rol in Azure RBAC moet toewijzen met behulp van ingebouwde of aangepaste rollen die deze machtigingen bieden.

Belangrijk

Sommige machtigingen worden mogelijk weergegeven door de doelservice die niet nodig is voor alle contexten. Waar mogelijk moet u zich houden aan het principe van minimale bevoegdheid, waarbij de identiteit alleen vereiste bevoegdheden verleent. Als de app bijvoorbeeld alleen uit een gegevensbron moet kunnen lezen, gebruikt u een rol die alleen gemachtigd is om te lezen. Het zou ongepast zijn om een rol toe te wijzen die ook schrijfbewerkingen naar die service toestaat, omdat dit overmatige machtigingen zou zijn voor een leesbewerking. Op dezelfde manier wilt u ervoor zorgen dat de roltoewijzing alleen is afgestemd op de resources die moeten worden gelezen.

Cosmos DB maakt geen gebruik van Azure RBAC voor gegevensbewerkingen. In plaats daarvan wordt een ingebouwd RBAC-systeem van Cosmos DB gebruikt dat is gebaseerd op vergelijkbare concepten. U moet een roltoewijzing maken die tijdens runtime toegang biedt tot uw databaseaccount. Azure RBAC-beheerrollen zoals Eigenaar zijn niet voldoende. De volgende tabel bevat ingebouwde rollen die worden aanbevolen bij het gebruik van de Azure Cosmos DB-extensie in normale werking. Uw toepassing vereist mogelijk extra machtigingen op basis van de code die u schrijft.

Bindingstype Voorbeeld van ingebouwde rollen1
Trigger2 Inzender voor ingebouwde Cosmos DB-gegevens
Invoerbinding Ingebouwde gegevenslezer van Cosmos DB
Uitvoerbinding Inzender voor ingebouwde Cosmos DB-gegevens

1 Deze rollen kunnen niet worden gebruikt in een Azure RBAC-roltoewijzing. Raadpleeg de ingebouwde RBAC-systeemdocumentatie van Cosmos DB voor meer informatie over het toewijzen van deze rollen.

2 Wanneer u identiteit gebruikt, behandelt Cosmos DB het maken van containers als een beheerbewerking. Het is niet beschikbaar als een gegevensvlakbewerking voor de trigger. U moet ervoor zorgen dat u de containers maakt die nodig zijn voor de trigger (inclusief de leasecontainer) voordat u uw functie instelt.

Volgende stappen