Vstupní vazba Azure Cosmos DB pro Azure Functions 2.x a vyšší

  • Článek

Vstupní vazba služby Azure Cosmos DB načítá pomocí rozhraní SQL API jeden nebo více dokumentů Azure Cosmos DB a předává je do vstupního parametru funkce. Parametry ID dokumentu nebo dotaz se dají určit podle aktivační události, která funkci volá.

Informace o nastavení a konfiguraci najdete v přehledu.

Poznámka:

Při dělení kolekce musí vyhledávací operace také zadat hodnotu klíče oddílu.

Důležité

Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Azure Functions podporuje dva programovací modely pro Python. Způsob, jakým definujete vazby, závisí na zvoleném programovacím modelu.

Programovací model Pythonu v2 umožňuje definovat vazby pomocí dekorátorů přímo v kódu funkce Pythonu. Další informace najdete v příručce pro vývojáře Pythonu.

Tento článek podporuje oba programovací modely.

Příklad

Pokud není uvedeno jinak, příklady v tomto článku cílí na verzi 3.x rozšíření Azure Cosmos DB. Pro použití s rozšířením verze 4.x je nutné nahradit řetězec collection v názvech vlastností a atributů .container

Funkci jazyka C# je možné vytvořit pomocí jednoho z následujících režimů jazyka C#:

  • Izolovaný model pracovního procesu: Kompilovaná funkce jazyka C#, která běží v pracovním procesu, který je izolovaný od modulu runtime. Izolovaný pracovní proces je nutný pro podporu funkcí C# spuštěných na LTS a jiných verzích než LTS .NET a rozhraní .NET Framework. Rozšíření pro izolované funkce pracovních procesů používají Microsoft.Azure.Functions.Worker.Extensions.* obory názvů.
  • Model v procesu: Zkompilovaná funkce jazyka C#, která běží ve stejném procesu jako modul runtime služby Functions. Ve variantě tohoto modelu je možné spouštět funkce pomocí skriptování jazyka C#, což je podporováno především pro úpravy portálu C#. Rozšíření pro procesní funkce používají Microsoft.Azure.WebJobs.Extensions.* obory názvů.

Důležité

Podpora modelu v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovního procesu pro plnou podporu.

Tato část obsahuje příklady, které vyžadují rozšíření Azure Cosmos DB verze 3.x a rozšíření Azure Storage verze 5.x. Pokud ještě v aplikaci funkcí není, přidejte odkaz na následující balíčky NuGet:

Příklady odkazují na jednoduchý 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}");
    }
}

Trigger fronty, vyhledání ID z JSON

Následující příklad ukazuje funkci, která načte jeden dokument. Funkce se aktivuje zprávou JSON ve frontě úložiště. Trigger fronty parsuje JSON do objektu typu ToDoItemLookup, který obsahuje ID a hodnotu klíče oddílu, které se mají načíst. Toto ID a hodnota klíče oddílu ToDoItem slouží k vrácení dokumentu ze zadané databáze a kolekce.

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

Tato část obsahuje následující příklady:

Příklady odkazují na jednoduchý 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 + "}";
  }
}

Trigger HTTP, vyhledání ID z řetězce dotazu – parametr String

Následující příklad ukazuje funkci Java, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který pomocí řetězce dotazu určí ID a hodnotu klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu se používají k načtení dokumentu ze zadané databáze a kolekce ve formuláři String.

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

V knihovně modulu runtime funkcí Java použijte poznámku @CosmosDBInput k parametrům funkce, jejichž hodnota pochází ze služby Azure Cosmos DB. Tuto poznámku lze použít s nativními typy Javy, POJOs nebo hodnotami null s použitím Optional<T>.

Trigger HTTP, vyhledání ID z řetězce dotazu – parametr POJO

Následující příklad ukazuje funkci Java, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který pomocí řetězce dotazu určí ID a hodnotu klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu sloužící k načtení dokumentu ze zadané databáze a kolekce. Dokument se pak převede na instanci dříve vytvořené úlohy ToDoItem POJO a předá se funkci jako argument.

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

Trigger HTTP, vyhledání ID ze směrovacích dat

Následující příklad ukazuje funkci Java, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který používá parametr trasy k zadání ID a hodnoty klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu se používají k načtení dokumentu ze zadané databáze a kolekce, která ho vrací jako 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();
        }
    }
}

Trigger HTTP, vyhledání ID ze směrovacích dat pomocí SqlQuery

Následující příklad ukazuje funkci Java, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který pomocí parametru trasy určí ID, které se má vyhledat. Toto ID se používá k načtení dokumentu ze zadané databáze a kolekce, převod sady výsledků na hodnotu ToDoItem[], protože mnoho dokumentů může být vráceno v závislosti na kritériích dotazu.

Poznámka:

Pokud potřebujete dotazovat pouze podle ID, doporučujeme použít vyhledávání, jako jsou předchozí příklady, protože spotřebuje méně jednotek žádostí. Operace čtení bodů (GET) jsou efektivnější než dotazy podle 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();
        }
    }
}

Trigger HTTP, získání více dokumentů ze směrovacích dat pomocí SqlQuery

Následující příklad ukazuje funkci Java, která načítá více dokumentů. Funkce se aktivuje požadavkem HTTP, který pomocí parametru desc trasy určí řetězec, který se má v description poli vyhledat. Hledaný termín se používá k načtení kolekce dokumentů ze zadané databáze a kolekce, převod sady výsledků na ToDoItem[] hodnotu a jeho předání jako argument funkci.

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

Tato část obsahuje následující příklady, které čtou jeden dokument zadáním hodnoty ID z různých zdrojů:

Trigger fronty, vyhledání ID z JSON

Následující příklad ukazuje funkci TypeScript, která čte jeden dokument a aktualizuje textovou hodnotu dokumentu.

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

Trigger HTTP, vyhledání ID z řetězce dotazu

Následující příklad ukazuje funkci TypeScript, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který pomocí řetězce dotazu určí ID a hodnotu klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu ToDoItem slouží k načtení dokumentu ze zadané databáze a kolekce.

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

Trigger HTTP, vyhledání ID ze směrovacích dat

Následující příklad ukazuje funkci TypeScript, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který používá směrovací data k určení ID a hodnoty klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu ToDoItem slouží k načtení dokumentu ze zadané databáze a kolekce.

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

Trigger fronty, získání více dokumentů pomocí SqlQuery

Následující příklad ukazuje funkci TypeScript, která načítá více dokumentů určených dotazem SQL pomocí triggeru fronty k přizpůsobení parametrů dotazu.

Trigger fronty poskytuje parametr departmentId. Zpráva fronty { "departmentId" : "Finance" } by vrátila všechny záznamy pro finanční oddělení.

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

Tato část obsahuje následující příklady, které čtou jeden dokument zadáním hodnoty ID z různých zdrojů:

Trigger fronty, vyhledání ID z JSON

Následující příklad ukazuje funkci JavaScriptu, která čte jeden dokument a aktualizuje textovou hodnotu dokumentu.

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

Trigger HTTP, vyhledání ID z řetězce dotazu

Následující příklad ukazuje funkci JavaScriptu, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který pomocí řetězce dotazu určí ID a hodnotu klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu ToDoItem slouží k načtení dokumentu ze zadané databáze a kolekce.

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

Trigger HTTP, vyhledání ID ze směrovacích dat

Následující příklad ukazuje funkci JavaScriptu, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který používá směrovací data k určení ID a hodnoty klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu ToDoItem slouží k načtení dokumentu ze zadané databáze a kolekce.

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

Trigger fronty, získání více dokumentů pomocí SqlQuery

Následující příklad ukazuje funkci JavaScriptu, která načítá více dokumentů určených dotazem SQL pomocí triggeru fronty k přizpůsobení parametrů dotazu.

Trigger fronty poskytuje parametr departmentId. Zpráva fronty { "departmentId" : "Finance" } by vrátila všechny záznamy pro finanční oddělení.

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

Trigger fronty, vyhledání ID z JSON

Následující příklad ukazuje, jak číst a aktualizovat jeden dokument služby Azure Cosmos DB. Jedinečný identifikátor dokumentu se poskytuje prostřednictvím hodnoty JSON ve zprávě fronty.

Vstupní vazba Azure Cosmos DB je uvedená jako první v seznamu vazeb nalezených v konfiguračním souboru funkce (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"
}

Soubor run.ps1 obsahuje kód PowerShellu, který čte příchozí dokument a výstupy se změní.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document

Trigger HTTP, vyhledání ID z řetězce dotazu

Následující příklad ukazuje, jak číst a aktualizovat jeden dokument služby Azure Cosmos DB z webového rozhraní API. Jedinečný identifikátor dokumentu je poskytován prostřednictvím parametru řetězce dotazu z požadavku HTTP, jak je definováno ve vlastnosti vazby "Id": "{Query.Id}" .

Vstupní vazba Azure Cosmos DB je uvedená jako první v seznamu vazeb nalezených v konfiguračním souboru funkce (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 
}

Soubor run.ps1 obsahuje kód PowerShellu, který čte příchozí dokument a výstupy se změní.

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

Trigger HTTP, vyhledání ID ze směrovacích dat

Následující příklad ukazuje, jak číst a aktualizovat jeden dokument služby Azure Cosmos DB z webového rozhraní API. Jedinečný identifikátor dokumentu je poskytován prostřednictvím parametru trasy. Parametr trasy je definován ve vlastnosti vazby route požadavku HTTP a odkazuje se na ji ve vlastnosti vazby Azure Cosmos DB "Id": "{Id}" .

Vstupní vazba Azure Cosmos DB je uvedená jako první v seznamu vazeb nalezených v konfiguračním souboru funkce (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 
}

Soubor run.ps1 obsahuje kód PowerShellu, který čte příchozí dokument a výstupy se změní.

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

Trigger fronty, získání více dokumentů pomocí SqlQuery

Následující příklad ukazuje, jak číst více dokumentů Azure Cosmos DB. Konfigurační soubor funkce (function.json) definuje vlastnosti vazby, které zahrnují .sqlQuery Příkaz SQL zadaný pro sqlQuery vlastnost vybere sadu dokumentů poskytovaných funkci.

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

Soubor run1.ps1 obsahuje kód PowerShellu, který čte příchozí dokumenty.

param($QueueItem, $Documents, $TriggerMetadata)

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

Tato část obsahuje následující příklady, které čtou jeden dokument zadáním hodnoty ID z různých zdrojů:

Příklady závisí na tom, jestli používáte programovací model v1 nebo v2 Pythonu.

Trigger fronty, vyhledání ID z JSON

Následující příklad ukazuje vstupní vazbu Azure Cosmos DB. Funkce čte jeden dokument a aktualizuje textovou hodnotu dokumentu.

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.")

Trigger HTTP, vyhledání ID z řetězce dotazu

Následující příklad ukazuje funkci, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který pomocí řetězce dotazu určí ID a hodnotu klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu ToDoItem slouží k načtení dokumentu ze zadané databáze a kolekce.

V tuto chvíli neexistuje žádný ekvivalentní vzorek pro v2.

Trigger HTTP, vyhledání ID ze směrovacích dat

Následující příklad ukazuje funkci, která načte jeden dokument. Funkce se aktivuje požadavkem HTTP, který používá směrovací data k určení ID a hodnoty klíče oddílu, které se mají vyhledat. Toto ID a hodnota klíče oddílu ToDoItem slouží k načtení dokumentu ze zadané databáze a kolekce.

V tuto chvíli neexistuje žádný ekvivalentní vzorek pro v2.

Trigger fronty, získání více dokumentů pomocí SqlQuery

Následující příklad ukazuje funkci Python vstupní vazby služby Azure Cosmos DB, která používá vazbu. Funkce načte více dokumentů určených dotazem SQL pomocí triggeru fronty k přizpůsobení parametrů dotazu.

Trigger fronty poskytuje parametr departmentId. Zpráva fronty { "departmentId" : "Finance" } by vrátila všechny záznamy pro finanční oddělení.

V tuto chvíli neexistuje žádný ekvivalentní vzorek pro v2.

Atributy

Knihovny C# v procesu i izolovaného pracovního procesu používají atributy k definování funkce. Skript jazyka C# místo toho používá konfigurační soubor function.json, jak je popsáno v průvodci skriptováním jazyka C#.

Vlastnost atributu Popis
Připojení Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k dotazovanému účtu služby Azure Cosmos DB. Další informace najdete v tématu Připojení.
Název databáze Název databáze Azure Cosmos DB s monitorovaným kontejnerem.
Název kontejneru Název monitorovaného kontejneru.
PartitionKey Určuje hodnotu klíče oddílu pro vyhledávání. Může obsahovat parametry vazby. Vyžaduje se pro vyhledávání v dělených kontejnerech.
Id ID dokumentu, který se má načíst. Tato vlastnost podporuje vazbové výrazy. Nenastavujte obě vlastnosti Id i SqlQuery vlastnosti. Pokud ani jeden nenastavíte, načte se celý kontejner.
SqlQuery Dotaz SQL služby Azure Cosmos DB, který se používá k načítání více dokumentů. Vlastnost podporuje vazby modulu runtime, jako v tomto příkladu: SELECT * FROM c where c.departmentId = {departmentId}. Nenastavujte obě vlastnosti Id i SqlQuery vlastnosti. Pokud ani jeden nenastavíte, načte se celý kontejner.
PreferredLocations (Volitelné) Definuje upřednostňovaná umístění (oblasti) pro geograficky replikované databázové účty ve službě Azure Cosmos DB. Hodnoty by měly být oddělené čárkami. Například East US,South Central US,North Europe.

Dekoratéry

Platí pouze pro programovací model Pythonu v2.

Funkce Pythonu v2 se definují pomocí dekorátoru cosmos_db_input , který podporuje tyto vlastnosti v závislosti na verzi rozšíření:

Vlastnost Popis
arg_name Název proměnné použitý v kódu funkce, který představuje seznam dokumentů se změnami.
database_name Název databáze Azure Cosmos DB s monitorovanou kolekcí.
container_name Název monitorované kolekce Azure Cosmos DB.
connection Monitorovaná připojovací řetězec služby Azure Cosmos DB.
partition_key Klíč oddílu monitorované služby Azure Cosmos DB.
id ID dokumentu, který se má načíst.

Informace o funkcích Pythonu definovaných pomocí function.json najdete v části Konfigurace .

Poznámky

V knihovně modulu runtime funkcí Java použijte poznámku @CosmosDBInput k parametrům, které čtou ze služby Azure Cosmos DB. Poznámka podporuje následující vlastnosti:

Konfigurace

Platí pouze pro programovací model Pythonu v1.

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě input.cosmosDB() . Funkce type, directiona name vlastnosti se nevztahují na model v4.

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json , kde se vlastnosti liší podle verze rozšíření:

vlastnost function.json Popis
type Musí být nastavena na cosmosDBhodnotu .
direction Musí být nastavena na inhodnotu .
Jméno Název proměnné použitý v kódu funkce, který představuje seznam dokumentů se změnami.
připojení Název nastavení aplikace nebo kontejneru nastavení, který určuje, jak se připojit k monitorovanému účtu služby Azure Cosmos DB. Další informace najdete v tématu Připojení.
databaseName Název databáze Azure Cosmos DB s monitorovaným kontejnerem.
containerName Název monitorovaného kontejneru.
partitionKey Určuje hodnotu klíče oddílu pro vyhledávání. Může obsahovat parametry vazby. Vyžaduje se pro vyhledávání v dělených kontejnerech.
id ID dokumentu, který se má načíst. Tato vlastnost podporuje vazbové výrazy. Nenastavujte obě vlastnosti id i sqlQuery vlastnosti. Pokud ani jeden nenastavíte, načte se celý kontejner.
sqlQuery Dotaz SQL služby Azure Cosmos DB, který se používá k načítání více dokumentů. Vlastnost podporuje vazby modulu runtime, jako v tomto příkladu: SELECT * FROM c where c.departmentId = {departmentId}. Nenastavujte obě vlastnosti id i sqlQuery vlastnosti. Pokud ani jeden nenastavíte, načte se celý kontejner.
preferredLocations (Volitelné) Definuje upřednostňovaná umístění (oblasti) pro geograficky replikované databázové účty ve službě Azure Cosmos DB. Hodnoty by měly být oddělené čárkami. Například East US,South Central US,North Europe.

Kompletní příklady najdete v části Příklad.

Využití

Po úspěšném ukončení funkce se všechny změny provedené ve vstupním dokumentu automaticky zachovají.

Typ parametru podporovaný vstupní vazbou Cosmos DB závisí na verzi modulu runtime služby Functions, verzi balíčku rozšíření a použitém režimu jazyka C#.

Pokud chcete, aby funkce zpracovávala jeden dokument, vstupní vazba Cosmos DB může svázat s následujícími typy:

Typ Popis
Serializovatelné typy JSON Funkce se pokusí deserializovat data JSON dokumentu do prostého typu objektu CLR (POCO).

Pokud chcete, aby funkce zpracovávala více dokumentů z dotazu, vstupní vazba Cosmos DB může svázat s následujícími typy:

Typ Popis
IEnumerable<T>where T je serializovatelný typ JSON Výčet entit vrácených dotazem. Každá položka představuje jeden dokument.
CosmosClient1 Klient připojený k účtu Cosmos DB.
Databáze1 Klient připojený k databázi Cosmos DB.
Kontejner1 Klient připojený ke kontejneru Cosmos DB.

1 Pokud chcete použít tyto typy, musíte odkazovat na Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 nebo novější a běžné závislosti pro vazby typu sady SDK.

V knihovně modulu runtime funkcí Java zpřístupní @CosmosDBInput poznámky data azure Cosmos DB funkci. Tuto poznámku lze použít s nativními typy Javy, POJOs nebo hodnotami null s použitím Optional<T>.

Přístup k dokumentu pomocí .context.extraInputs.get()

Aktualizace dokumentů se při ukončení funkce neprovedou automaticky. K aktualizaci dokumentů ve funkci použijte výstupní vazbu. Další podrobnosti najdete v příkladu PowerShellu.

Data jsou k dispozici funkci prostřednictvím parametru DocumentList . Změny provedené v dokumentu nejsou automaticky zachovány.

Propojení

leaseConnection leaseConnectionStringSetting/Vlastnosti connectionStringSetting/connection jsou odkazy na konfiguraci prostředí, která určuje, jak se má aplikace připojit ke službě Azure Cosmos DB. Můžou zadat:

Pokud je nakonfigurovaná hodnota přesná shoda pro jedno nastavení i shodu předpony pro jiná nastavení, použije se přesná shoda.

Connection string

Připojovací řetězec pro váš databázový účet by měl být uložen v nastavení aplikace s názvem, který odpovídá hodnotě určené vlastností připojení konfigurace vazby.

Připojení založená na identitách

Pokud používáte rozšíření verze 4.x nebo vyšší, můžete místo použití připojovací řetězec s tajným kódem použít aplikaci identitu Microsoft Entra. Uděláte to tak, že nastavení definujete pod společnou předponou, která je v konfiguraci triggeru a vazeb namapovaná na vlastnost připojení.

V tomto režimu rozšíření vyžaduje následující vlastnosti:

Vlastnost Šablona proměnné prostředí Popis Příklad hodnoty
Koncový bod účtu <CONNECTION_NAME_PREFIX>__accountEndpoint Identifikátor URI koncového bodu účtu služby Azure Cosmos DB. <https:// database_account_name.documents.azure.com:443/>

Pro přizpůsobení připojení je možné nastavit další vlastnosti. Viz Běžné vlastnosti pro připojení založená na identitě.

Při hostovaní ve službě Azure Functions používají připojení založená na identitách spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když je možné zadat identitu přiřazenou uživatelem s vlastnostmi a clientID vlastnostmicredential. Všimněte si, že konfigurace identity přiřazené uživatelem s ID prostředku se nepodporuje . Při spuštění v jiných kontextech, jako je místní vývoj, se místo toho použije vaše identita vývojáře, i když je možné ji přizpůsobit. Viz Místní vývoj s připojeními založenými na identitách.

Udělení oprávnění identitě

Jakákoli identita, kterou používáte, musí mít oprávnění k provedení zamýšlených akcí. U většiny služeb Azure to znamená, že potřebujete přiřadit roli v Azure RBAC pomocí předdefinovaných nebo vlastních rolí, které tato oprávnění poskytují.

Důležité

Cílová služba může zpřístupnit některá oprávnění, která nejsou nutná pro všechny kontexty. Pokud je to možné, dodržujte zásadu nejnižšího oprávnění a udělte identitě pouze požadovaná oprávnění. Pokud například aplikace potřebuje jen číst ze zdroje dat, použijte roli, která má oprávnění jen ke čtení. Přiřazení role, která také umožňuje zápis do této služby, by bylo nevhodné, protože by to bylo nadměrné oprávnění pro operaci čtení. Podobně byste chtěli zajistit, aby přiřazení role bylo vymezeno pouze nad prostředky, které je potřeba číst.

Cosmos DB nepoužívá Azure RBAC pro operace s daty. Místo toho používá integrovaný systém RBAC služby Cosmos DB, který je založený na podobných konceptech. Budete muset vytvořit přiřazení role, které poskytuje přístup k vašemu databázovému účtu za běhu. Role správy Azure RBAC, jako je vlastník , nestačí. Následující tabulka ukazuje předdefinované role, které se doporučují při použití rozšíření Azure Cosmos DB v normálním provozu. Vaše aplikace může vyžadovat další oprávnění na základě kódu, který napíšete.

Typ vazby Příklad předdefinovaných rolí1
Aktivační událost2 Integrovaný přispěvatel dat ve službě Cosmos DB
Vstupní vazba Integrovaná čtečka dat ve službě Cosmos DB
Výstupní vazba Integrovaný přispěvatel dat ve službě Cosmos DB

1 Tyto role nelze použít v přiřazení role Azure RBAC. Podrobnosti o přiřazování těchto rolí najdete v integrované dokumentaci k systému RBAC služby Cosmos DB.

2 Při použití identity služba Cosmos DB považuje vytvoření kontejneru za operaci správy. Není k dispozici jako operace roviny dat pro trigger. Před nastavením funkce budete muset zajistit, abyste vytvořili kontejnery potřebné triggerem (včetně kontejneru zapůjčení).

Další kroky