Dela via

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

  • Artikel

Azure Cosmos DB-indatabindningen använder SQL API för att hämta en eller flera Azure Cosmos DB-dokument och skickar dem till indataparametern för funktionen. Dokument-ID:t och frågeparametrarna kan fastställas baserat på den utlösare som anropar funktionen.

Information om konfiguration och konfigurationsinformation finns i översikten.

Kommentar

När samlingen partitioneras måste uppslagsåtgärder också ange värdet för partitionsnyckeln.

Viktigt!

Den här artikeln använder flikar för att stödja flera versioner av Node.js programmeringsmodellen. V4-modellen är allmänt tillgänglig och är utformad för att ha en mer flexibel och intuitiv upplevelse för JavaScript- och TypeScript-utvecklare. Mer information om hur v4-modellen fungerar finns i utvecklarguiden för Azure Functions Node.js. Mer information om skillnaderna mellan v3 och v4 finns i migreringsguiden.

Azure Functions stöder två programmeringsmodeller för Python. Hur du definierar dina bindningar beror på din valda programmeringsmodell.

Med programmeringsmodellen Python v2 kan du definiera bindningar med hjälp av dekoratörer direkt i python-funktionskoden. Mer information finns i utvecklarguiden för Python.

Den här artikeln stöder båda programmeringsmodellerna.

Exempel

Om inget annat anges är exempel i den här artikeln målversion 3.x av Azure Cosmos DB-tillägget. För användning med tilläggsversion 4.x måste du ersätta strängen collection i egenskaps- och attributnamn med container.

En C#-funktion kan skapas med något av följande C#-lägen:

  • Isolerad arbetsmodell: Kompilerad C#-funktion som körs i en arbetsprocess som är isolerad från körningen. Isolerad arbetsprocess krävs för att stödja C#-funktioner som körs på LTS- och icke-LTS-versioner .NET och .NET Framework. Tillägg för isolerade arbetsprocessfunktioner använder Microsoft.Azure.Functions.Worker.Extensions.* namnområden.
  • Processmodell: Kompilerad C#-funktion som körs i samma process som Functions-körningen. I en variant av den här modellen kan Functions köras med C#-skript, vilket främst stöds för redigering av C#-portalen. Tillägg för in-process-funktioner använder Microsoft.Azure.WebJobs.Extensions.* namnområden.

Viktigt!

Supporten upphör för den pågående modellen den 10 november 2026. Vi rekommenderar starkt att du migrerar dina appar till den isolerade arbetsmodellen för fullt stöd.

Det här avsnittet innehåller exempel som kräver version 3.x av Azure Cosmos DB-tillägget och 5.x av Azure Storage-tillägget. Om det inte redan finns i funktionsappen lägger du till referensen till följande NuGet-paket:

Exemplen refererar till en enkel ToDoItem typ:

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

Köutlösare, leta upp ID från JSON

I följande exempel visas en funktion som hämtar ett enda dokument. Funktionen utlöses av ett JSON-meddelande i lagringskön. Köutlösaren parsar JSON till ett objekt av typen ToDoItemLookup, som innehåller det ID och partitionsnyckelvärde som ska hämtas. Det ID- och partitionsnyckelvärdet används för att returnera ett ToDoItem dokument från den angivna databasen och samlingen.

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

Det här avsnittet innehåller följande exempel:

Exemplen refererar till en enkel ToDoItem typ:

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-utlösare, leta upp ID från frågesträng – Strängparameter

I följande exempel visas en Java-funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder en frågesträng för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärdet används för att hämta ett dokument från den angivna databasen och samlingen i strängform.

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

I Körningsbiblioteket för Java-funktioner använder du anteckningen @CosmosDBInput för funktionsparametrar vars värde skulle komma från Azure 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>.

HTTP-utlösare, leta upp ID från frågesträng – POJO-parameter

I följande exempel visas en Java-funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder en frågesträng för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärde som används för att hämta ett dokument från den angivna databasen och samlingen. Dokumentet konverteras sedan till en instans av POJO ToDoItem som skapades tidigare och skickas som ett argument till funktionen.

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-utlösare, leta upp ID från routningsdata

I följande exempel visas en Java-funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder en routningsparameter för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärdet används för att hämta ett dokument från den angivna databasen och samlingen och returnera det som en 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-utlösare, leta upp ID från routningsdata med hjälp av SqlQuery

I följande exempel visas en Java-funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder en routningsparameter för att ange det ID som ska sökas upp. Det ID:t används för att hämta ett dokument från den angivna databasen och samlingen och konvertera resultatuppsättningen till en ToDoItem[], eftersom många dokument kan returneras, beroende på frågevillkoren.

Kommentar

Om du bara behöver fråga efter ID:t rekommenderar vi att du använder en sökning, som i föregående exempel, eftersom den förbrukar färre enheter för begäranden. Punktläsningsåtgärder (GET) är effektivare än frågor efter 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-utlösare, hämta flera dokument från routningsdata med hjälp av SqlQuery

I följande exempel visas en Java-funktion som hämtar flera dokument. Funktionen utlöses av en HTTP-begäran som använder en routningsparameter desc för att ange strängen som ska sökas efter i fältet description . Sökordet används för att hämta en samling dokument från den angivna databasen och samlingen, konvertera resultatuppsättningen till en ToDoItem[] och skicka den som ett argument till funktionen.

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

Det här avsnittet innehåller följande exempel som läser ett enskilt dokument genom att ange ett ID-värde från olika källor:

Köutlösare, leta upp ID från JSON

I följande exempel visas en TypeScript-funktion som läser ett enda dokument och uppdaterar dokumentets textvärde.

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-utlösare, leta upp ID från frågesträng

I följande exempel visas en TypeScript-funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder en frågesträng för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärdet används för att hämta ett ToDoItem dokument från den angivna databasen och samlingen.

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-utlösare, leta upp ID från routningsdata

I följande exempel visas en TypeScript-funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder routningsdata för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärdet används för att hämta ett ToDoItem dokument från den angivna databasen och samlingen.

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

Köutlösare, hämta flera dokument med hjälp av SqlQuery

I följande exempel visas en TypeScript-funktion som hämtar flera dokument som anges av en SQL-fråga med hjälp av en köutlösare för att anpassa frågeparametrarna.

Köutlösaren innehåller en parameter departmentId. Ett kömeddelande för { "departmentId" : "Finance" } returnerar alla poster för ekonomiavdelningen.

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

Det här avsnittet innehåller följande exempel som läser ett enskilt dokument genom att ange ett ID-värde från olika källor:

Köutlösare, leta upp ID från JSON

I följande exempel visas en JavaScript-funktion som läser ett enda dokument och uppdaterar dokumentets textvärde.

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-utlösare, leta upp ID från frågesträng

I följande exempel visas en JavaScript-funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder en frågesträng för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärdet används för att hämta ett ToDoItem dokument från den angivna databasen och samlingen.

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-utlösare, leta upp ID från routningsdata

I följande exempel visas en JavaScript-funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder routningsdata för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärdet används för att hämta ett ToDoItem dokument från den angivna databasen och samlingen.

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}`,
            };
        }
    },
});

Köutlösare, hämta flera dokument med hjälp av SqlQuery

I följande exempel visas en JavaScript-funktion som hämtar flera dokument som anges av en SQL-fråga med hjälp av en köutlösare för att anpassa frågeparametrarna.

Köutlösaren innehåller en parameter departmentId. Ett kömeddelande för { "departmentId" : "Finance" } returnerar alla poster för ekonomiavdelningen.

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

Köutlösare, leta upp ID från JSON

I följande exempel visas hur du läser och uppdaterar ett enda Azure Cosmos DB-dokument. Dokumentets unika identifierare tillhandahålls via JSON-värdet i ett kömeddelande.

Azure Cosmos DB-indatabindningen visas först i listan över bindningar som finns i funktionens konfigurationsfil (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"
}

Filen run.ps1 har PowerShell-koden som läser det inkommande dokumentet och matar ut ändringar.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document

HTTP-utlösare, leta upp ID från frågesträng

I följande exempel visas hur du läser och uppdaterar ett enda Azure Cosmos DB-dokument från ett webb-API. Dokumentets unika identifierare tillhandahålls via en frågesträngsparameter från HTTP-begäran, enligt definitionen i bindningens "Id": "{Query.Id}" egenskap.

Azure Cosmos DB-indatabindningen visas först i listan över bindningar som finns i funktionens konfigurationsfil (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 
}

Filen run.ps1 har PowerShell-koden som läser det inkommande dokumentet och matar ut ändringar.

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-utlösare, leta upp ID från routningsdata

I följande exempel visas hur du läser och uppdaterar ett enda Azure Cosmos DB-dokument från ett webb-API. Dokumentets unika identifierare tillhandahålls via en vägparameter. Routningsparametern definieras i http-begärandebindningens route egenskap och refereras till i azure Cosmos DB-bindningsegenskapen "Id": "{Id}" .

Azure Cosmos DB-indatabindningen visas först i listan över bindningar som finns i funktionens konfigurationsfil (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 
}

Filen run.ps1 har PowerShell-koden som läser det inkommande dokumentet och matar ut ändringar.

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

Köutlösare, hämta flera dokument med hjälp av SqlQuery

I följande exempel visas hur du läser flera Azure Cosmos DB-dokument. Funktionens konfigurationsfil (function.json) definierar bindningsegenskaperna, som innehåller sqlQuery. SQL-instruktionen som tillhandahålls egenskapen sqlQuery väljer den uppsättning dokument som tillhandahålls till funktionen.

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

Filen run1.ps1 har PowerShell-koden som läser de inkommande dokumenten.

param($QueueItem, $Documents, $TriggerMetadata)

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

Det här avsnittet innehåller följande exempel som läser ett enskilt dokument genom att ange ett ID-värde från olika källor:

Exemplen beror på om du använder python-programmeringsmodellen v1 eller v2.

Köutlösare, leta upp ID från JSON

I följande exempel visas en Azure Cosmos DB-indatabindning. Funktionen läser ett enda dokument och uppdaterar dokumentets textvärde.

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-utlösare, leta upp ID från frågesträng

I följande exempel visas en funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder en frågesträng för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärdet används för att hämta ett ToDoItem dokument från den angivna databasen och samlingen.

Inget motsvarande exempel för v2 just nu.

HTTP-utlösare, leta upp ID från routningsdata

I följande exempel visas en funktion som hämtar ett enda dokument. Funktionen utlöses av en HTTP-begäran som använder routningsdata för att ange det ID och partitionsnyckelvärde som ska sökas upp. Det ID- och partitionsnyckelvärdet används för att hämta ett ToDoItem dokument från den angivna databasen och samlingen.

Inget motsvarande exempel för v2 just nu.

Köutlösare, hämta flera dokument med hjälp av SqlQuery

I följande exempel visas en Azure Cosmos DB-indatabindningsfunktion för Python som använder bindningen. Funktionen hämtar flera dokument som anges av en SQL-fråga med hjälp av en köutlösare för att anpassa frågeparametrarna.

Köutlösaren innehåller en parameter departmentId. Ett kömeddelande för { "departmentId" : "Finance" } returnerar alla poster för ekonomiavdelningen.

Inget motsvarande exempel för v2 just nu.

Attribut

C#-bibliotek i både processprocess och isolerad arbetsprocess använder attribut för att definiera funktionen. C#-skriptet använder i stället en function.json konfigurationsfil enligt beskrivningen i C#-skriptguiden.

Attributegenskap beskrivning
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till det Azure Cosmos DB-konto som efterfrågas. Mer information finns i Anslutningar.
DatabaseName Namnet på Azure Cosmos DB-databasen med containern som övervakas.
ContainerName Namnet på containern som övervakas.
PartitionKey Anger partitionsnyckelvärdet för sökningen. Kan innehålla bindningsparametrar. Det krävs för sökningar i partitionerade containrar.
ID ID:t för dokumentet som ska hämtas. Den här egenskapen stöder bindningsuttryck. Ange inte både Id egenskaperna och SqlQuery . Om du inte anger någon av dem hämtas hela containern.
SqlQuery En Azure Cosmos DB SQL-fråga som används för att hämta flera dokument. Egenskapen stöder runtime-bindningar, som i det här exemplet: SELECT * FROM c where c.departmentId = {departmentId}. Ange inte både Id egenskaperna och SqlQuery . Om du inte anger någon av dem hämtas hela containern.
PreferredLocations (Valfritt) Definierar önskade platser (regioner) för geo-replikerade databaskonton i Azure Cosmos DB-tjänsten. Värden bör kommaavgränsas. Exempel: East US,South Central US,North Europe

Dekoratörer

Gäller endast för python v2-programmeringsmodellen.

Python v2-funktioner definieras med hjälp av dekoratören cosmos_db_input , som stöder dessa egenskaper, beroende på tilläggsversionen:

Property beskrivning
arg_name Variabelnamnet som används i funktionskoden som representerar listan över dokument med ändringar.
database_name Namnet på Azure Cosmos DB-databasen med samlingen som övervakas.
container_name Namnet på Den Azure Cosmos DB-samling som övervakas.
connection Den anslutningssträng av Azure Cosmos DB som övervakas.
partition_key Partitionsnyckeln för Azure Cosmos DB som övervakas.
id ID:t för dokumentet som ska hämtas.

Information om Python-funktioner som definierats med hjälp av function.json finns i avsnittet Konfiguration .

Kommentarer

Från Java Functions-körningsbiblioteket använder du anteckningen @CosmosDBInput på parametrar som läser från Azure Cosmos DB. Kommentaren stöder följande egenskaper:

Konfiguration

Gäller endast programmeringsmodellen Python v1.

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas input.cosmosDB() till metoden. Egenskaperna type, directionoch name gäller inte för v4-modellen.

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

function.json egenskap beskrivning
typ Måste anges till cosmosDB.
riktning Måste anges till in.
Namn Variabelnamnet som används i funktionskoden som representerar listan över dokument med ändringar.
samband Namnet på en appinställning eller inställningscontainer 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 containern som övervakas.
containerName Namnet på containern som övervakas.
partitionKey Anger partitionsnyckelvärdet för sökningen. Kan innehålla bindningsparametrar. Det krävs för sökningar i partitionerade containrar.
id ID:t för dokumentet som ska hämtas. Den här egenskapen stöder bindningsuttryck. Ange inte både id egenskaperna och sqlQuery . Om du inte anger någon av dem hämtas hela containern.
sqlQuery En Azure Cosmos DB SQL-fråga som används för att hämta flera dokument. Egenskapen stöder runtime-bindningar, som i det här exemplet: SELECT * FROM c where c.departmentId = {departmentId}. Ange inte både id egenskaperna och sqlQuery . Om du inte anger någon av dem hämtas hela containern.
preferredLocations (Valfritt) Definierar önskade platser (regioner) för geo-replikerade databaskonton i Azure Cosmos DB-tjänsten. Värden bör kommaavgränsas. Exempel: East US,South Central US,North Europe

Se avsnittet Exempel för fullständiga exempel.

Förbrukning

När funktionen avslutas sparas alla ändringar som görs i indatadokumentet automatiskt.

Vilken parametertyp som stöds av Cosmos DB-indatabindningen beror på functions-körningsversionen, tilläggspaketversionen och den C#-modalitet som används.

När du vill att funktionen ska bearbeta ett enda dokument kan Cosmos DB-indatabindningen binda till följande typer:

Typ Beskrivning
JSON-serialiserbara typer Functions försöker deserialisera JSON-data i dokumentet till en oformaterad TYP av CLR-objekt (POCO).

När du vill att funktionen ska bearbeta flera dokument från en fråga kan Cosmos DB-indatabindningen binda till följande typer:

Typ Beskrivning
IEnumerable<T>där T är en JSON-serialiserbar typ En uppräkning av entiteter som returneras av frågan. Varje post representerar ett dokument.
CosmosClient1 En klient som är ansluten till Cosmos DB-kontot.
Databas1 En klient som är ansluten till Cosmos DB-databasen.
Container1 En klient som är ansluten till Cosmos DB-containern.

1 Om du vill använda dessa typer måste du referera till Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 eller senare och de vanliga beroendena för SDK-typbindningar.

Från Java Functions-körningsbiblioteket exponerar @CosmosDBInput-anteckningen Azure Cosmos DB-data för funktionen. Den här anteckningen kan användas med interna Java-typer, POJO:er eller null-värden med hjälp av Optional<T>.

Få åtkomst till dokumentet med hjälp context.extraInputs.get()av .

Uppdateringar av dokument görs inte automatiskt när funktionen avslutas. Om du vill uppdatera dokument i en funktion använder du en utdatabindning. Mer information finns i PowerShell-exemplet .

Data görs tillgängliga för funktionen via en DocumentList parameter. Ändringar som görs i dokumentet sparas inte automatiskt.

anslutningar

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

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

Connection string

Anslutningssträng 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 Microsoft Entra-identitet. Gör detta genom att definiera inställningarna under ett vanligt prefix som mappas till anslutningsegenskapen i utlösaren och bindningskonfigurationen.

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

Property Miljövariabelmall beskrivning 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 används som standard, även om en användartilldelad identitet kan anges med credential egenskaperna och clientID . Observera att det inte går att konfigurera en användartilldelad identitet med ett resurs-ID. När den körs i andra sammanhang, till exempel lokal utveckling, används utvecklaridentiteten i stället, även om den 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. För de flesta Azure-tjänster innebär det att 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 minsta 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 detta skulle vara överdriven 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.

Cosmos DB använder inte Azure RBAC för dataåtgärder. I stället använder den ett inbyggt RBAC-system i Cosmos DB som bygger på liknande begrepp. Du måste skapa en rolltilldelning som ger åtkomst till ditt databaskonto vid körning. Azure RBAC Management-roller som Ägare räcker inte. I följande tabell visas inbyggda roller som rekommenderas när du använder Azure Cosmos DB-tillägget i normal drift. Programmet kan kräva ytterligare behörigheter baserat på den kod du skriver.

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

1 Dessa roller kan inte användas i en Azure RBAC-rolltilldelning. Mer information om hur du tilldelar dessa roller finns i den inbyggda RBAC-systemdokumentationen för Cosmos DB.

2 När du använder identitet behandlar Cosmos DB skapandet av containrar som en hanteringsåtgärd. Den är inte tillgänglig som en dataplansåtgärd för utlösaren. Du måste se till att du skapar de containrar som behövs av utlösaren (inklusive lånecontainern) innan du konfigurerar funktionen.

Nästa steg