Partilhar via

Azure Cosmos DB input binding para Funções do Azure 2.x e superiores

A ligação de entrada do Azure Cosmos DB utiliza a API SQL para recuperar um ou mais documentos do Azure Cosmos DB e passá-los ao parâmetro de entrada da função. Os parâmetros de consulta ou o ID do documento podem ser determinados com base no acionador que invoca a função.

Para obter informações sobre detalhes de instalação e configuração, consulte a visão geral.

Nota

Quando a coleção é particionada, as operações de pesquisa também devem especificar o valor da chave de partição.

Importante

Este artigo usa guias para oferecer suporte a várias versões do modelo de programação Node.js. O modelo v4 está geralmente disponível e foi projetado para ter uma experiência mais flexível e intuitiva para desenvolvedores JavaScript e TypeScript. Para mais detalhes sobre como funciona o modelo v4, consulte o guia para desenvolvedores Funções do Azure Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.

O Funções do Azure suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.

O modelo de programação Python v2 permite-te definir bindings usando decoradores diretamente no teu código de função Python. Para mais informações, consulte o guia para desenvolvedores Python.

Este artigo suporta ambos os modelos de programação.

Exemplo

Salvo indicação em contrário, exemplos neste artigo visam a versão 3.x da extensão Azure Cosmos DB. Para uso com a extensão versão 4.x, você precisa substituir a cadeia de caracteres collection em nomes de propriedade e atributo por container.

Uma função C# pode ser criada usando um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. É necessário um processo trabalhador isolado para suportar funções C# a correr em versões LTS e não-LTS, como .NET e o framework .NET. Extensões para funções de processos trabalhadores isolados usam espaços de nomes Microsoft.Azure.Functions.Worker.Extensions.*.
  • Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions. Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. Extensões para funções em processo utilizam espaços de nomes Microsoft.Azure.WebJobs.Extensions.*.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte total.

Esta secção contém exemplos que requerem a versão 3.x da extensão Azure Cosmos DB e a 5.x da extensão Armazenamento do Azure. Se ainda não estiver presente no seu aplicativo de função, adicione referência aos seguintes pacotes NuGet:

Os exemplos referem-se a um tipo simples ToDoItem :

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

Gatilho de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma função que recupera um único documento. A função é acionada por uma mensagem JSON na fila de armazenamento. O gatilho de fila analisa o JSON em um objeto do tipo ToDoItemLookup, que contém o ID e o valor da chave de partição a serem recuperados. Esse ID e o valor da chave de partição são usados para retornar um ToDoItem documento do banco de dados e da coleção especificados.

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

Esta seção contém os seguintes exemplos:

Os exemplos referem-se a um tipo simples ToDoItem :

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

Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta - Parâmetro String

O exemplo seguinte mostra uma função Java que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um documento do banco de dados e da coleção especificados, no formato 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();
        }
    }
}

Na biblioteca de runtime de funções Java, use a anotação @CosmosDBInput nos parâmetros da função cujo valor provém de Azure Cosmos DB. Esta anotação pode ser usada com tipos nativos de Java, POJOs ou valores anuláveis usando Optional<T>.

Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta - parâmetro POJO

O exemplo seguinte mostra uma função Java que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse valor de ID e chave de partição usado para recuperar um documento do banco de dados e da coleção especificados. O documento é então convertido em uma instância do ToDoItem POJO criado anteriormente e passado como um argumento para a função.

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

Gatilho HTTP, procure ID a partir de dados de rota

O exemplo seguinte mostra uma função Java que recupera um único documento. A função é acionada por uma solicitação HTTP que usa um parâmetro route para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um documento do banco de dados e da coleção especificados, retornando-o como um Optional<String>arquivo .

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

Gatilho HTTP, procure ID de dados de rota, usando SqlQuery

O exemplo seguinte mostra uma função Java que recupera um único documento. A função é acionada por uma solicitação HTTP que usa um parâmetro route para especificar o ID a ser pesquisado. Esse ID é usado para recuperar um documento do banco de dados e da coleção especificados, convertendo o conjunto de resultados em um ToDoItem[], já que muitos documentos podem ser retornados, dependendo dos critérios de consulta.

Nota

Se você precisar consultar apenas pelo ID, é recomendável usar uma pesquisa, como os exemplos anteriores, pois consome menos unidades de solicitação. As operações de leitura pontual (GET) são mais eficientes do que as consultas por 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, obter vários documentos de dados de rota, usando SqlQuery

O exemplo seguinte mostra uma função Java que recupera múltiplos documentos. A função é acionada por uma solicitação HTTP que usa um parâmetro desc route para especificar a cadeia de caracteres a ser pesquisada description no campo. O termo de pesquisa é usado para recuperar uma coleção de documentos do banco de dados e da coleção especificados, convertendo o conjunto de resultados em um ToDoItem[] e passando-o como um argumento para a função.

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

Esta seção contém os seguintes exemplos que leem um único documento especificando um valor de ID de várias fontes:

Gatilho de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma função TypeScript que lê um único documento e atualiza o valor de texto do documento.

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

Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função TypeScript que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

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

Gatilho HTTP, procure ID a partir de dados de rota

O exemplo a seguir mostra uma função TypeScript que recupera um único documento. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

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

Gatilho de fila, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma função TypeScript que recupera vários documentos especificados por uma consulta SQL, usando um gatilho de fila para personalizar os parâmetros de consulta.

O gatilho de fila fornece um parâmetro departmentId. Uma mensagem de fila de { "departmentId" : "Finance" } retornaria todos os registros para o departamento financeiro.

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

Esta seção contém os seguintes exemplos que leem um único documento especificando um valor de ID de várias fontes:

Gatilho de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma função JavaScript que lê um único documento e atualiza o valor de texto do documento.

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

Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função JavaScript que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

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

Gatilho HTTP, procure ID a partir de dados de rota

O exemplo a seguir mostra uma função JavaScript que recupera um único documento. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

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

Gatilho de fila, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma função JavaScript que recupera vários documentos especificados por uma consulta SQL, usando um gatilho de fila para personalizar os parâmetros de consulta.

O gatilho de fila fornece um parâmetro departmentId. Uma mensagem de fila de { "departmentId" : "Finance" } retornaria todos os registros para o departamento financeiro.

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

Gatilho de fila, ID de pesquisa de JSON

O exemplo seguinte demonstra como ler e atualizar um único documento do Azure Cosmos DB. O identificador exclusivo do documento é fornecido por meio do valor JSON em uma mensagem de fila.

A Azure Cosmos DB ligação de entrada está listada em primeiro lugar na lista de ligações encontradas no ficheiro de configuração da função (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"
}

O arquivo run.ps1 tem o código do PowerShell que lê o documento de entrada e gera alterações.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document

Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta

O exemplo seguinte demonstra como ler e atualizar um único documento do Azure Cosmos DB a partir de uma API web. O identificador exclusivo do documento é fornecido por meio de um parâmetro querystring da solicitação HTTP, conforme definido na propriedade da "Id": "{Query.Id}" ligação.

A Azure Cosmos DB ligação de entrada está listada em primeiro lugar na lista de ligações encontradas no ficheiro de configuração da função (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 
}

O arquivo run.ps1 tem o código do PowerShell que lê o documento de entrada e gera alterações.

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

Gatilho HTTP, procure ID a partir de dados de rota

O exemplo seguinte demonstra como ler e atualizar um único documento do Azure Cosmos DB a partir de uma API web. O identificador exclusivo do documento é fornecido por meio de um parâmetro route. O parâmetro de rota está definido na propriedade route da ligação HTTP e referenciado na propriedade de ligação Azure Cosmos DB "Id": "{Id}".

A Azure Cosmos DB ligação de entrada está listada em primeiro lugar na lista de ligações encontradas no ficheiro de configuração da função (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 
}

O arquivo run.ps1 tem o código do PowerShell que lê o documento de entrada e gera alterações.

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

Gatilho de fila, obter vários documentos, usando SqlQuery

O exemplo seguinte demonstra como ler múltiplos documentos do Azure Cosmos DB. O arquivo de configuração da função (function.json) define as propriedades de ligação, que incluem o sqlQueryarquivo . A instrução SQL fornecida à sqlQuery propriedade seleciona o conjunto de documentos fornecidos para a função.

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

O arquivo run1.ps1 tem o código do PowerShell que lê os documentos de entrada.

param($QueueItem, $Documents, $TriggerMetadata)

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

Esta seção contém os seguintes exemplos que leem um único documento especificando um valor de ID de várias fontes:

Os exemplos dependem se usas o modelo de programação Python v1 ou v2.

Usando ligações de SDK-Type para o Cosmos DB (visualização)

Este exemplo utiliza tipos SDK para aceder diretamente ao objeto subjacente CosmosClient fornecido pela ligação de entrada do Cosmos DB:

A função percorre todos os bancos de dados e registra seus IDs.

import logging
import azure.functions as func
import azurefunctions.extensions.bindings.cosmosdb as cosmos

app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)

@app.route(route="cosmos")
@app.cosmos_db_input(arg_name="client",
                     connection="CosmosDBConnection",
                     database_name=None,
                     container_name=None)
def get_docs(req: func.HttpRequest, client: cosmos.CosmosClient):
    databases = client.list_databases()
    for db in databases:
        logging.info(f"Found database with ID: {db.get('id')}")

    return "ok"

Para exemplos de utilização de outros tipos de SDK, veja as amostras ContainerProxy e DatabaseProxy. Para um tutorial passo a passo sobre como incluir bindings do tipo SDK na sua aplicação de funções, siga as Bindings do SDK Python para CosmosDB Sample.

Para saber mais, incluindo quais outras associações de tipo SDK são suportadas, consulte Associações de tipo SDK.

Gatilho de fila, ID de pesquisa de JSON

O exemplo seguinte mostra uma ligação de entrada do Azure Cosmos DB. A função lê um único documento e atualiza o valor de texto do documento.

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]):
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

Nenhuma amostra equivalente para v2 no momento.

Gatilho HTTP, procure ID a partir de dados de rota

O exemplo a seguir mostra uma função que recupera um único documento. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

Nenhuma amostra equivalente para v2 no momento.

Gatilho de fila, obter vários documentos, usando SqlQuery

O exemplo seguinte mostra uma função Azure Cosmos DB que liga input Python e utiliza a ligação. A função recupera vários documentos especificados por uma consulta SQL, usando um gatilho de fila para personalizar os parâmetros de consulta.

O gatilho de fila fornece um parâmetro departmentId. Uma mensagem de fila de { "departmentId" : "Finance" } retornaria todos os registros para o departamento financeiro.

Nenhuma amostra equivalente para v2 no momento.

Atributos

As bibliotecas C# do processo de trabalho em processo e isoladas usam atributos para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Propriedade Attribute Descrição
Ligação O nome de uma configuração de aplicação ou coleção de definições que especifica como se ligar à conta do Azure Cosmos DB que está a ser consultada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados O nome da base de dados Azure Cosmos DB com o contentor a ser monitorizado.
Nome do contêiner O nome do contêiner que está sendo monitorado.
PartitionKey Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de vinculação. É necessário para pesquisas em contêineres particionados .
ID A ID do documento a ser recuperado. Esta propriedade suporta expressões de ligação. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
SqlQuery Uma consulta SQL do Azure Cosmos DB usada para recuperar múltiplos documentos. A propriedade suporta associações de tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
Locais preferidos (Opcional) Define localizações preferenciais (regiões) para contas de base de dados geo-replicadas no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, East US,South Central US,North Europe.

Decoradores

Aplica-se apenas ao modelo de programação Python v2.

Python funções v2 são definidas usando o decorador cosmos_db_input, que suporta estas propriedades, dependendo da versão de extensão:

Propriedade Descrição
arg_name O nome da variável usada no código da função que representa a lista de documentos com alterações.
database_name O nome da base de dados Azure Cosmos DB com a coleção monitorizada.
container_name O nome da coleção Azure Cosmos DB está a ser monitorizado.
connection A cadeia de ligação do Azure Cosmos DB a ser monitorizada.
partition_key A chave de partição do Azure Cosmos DB está a ser monitorizada.
id A ID do documento a ser recuperado.

Para Python funções definidas usando function.json, veja a secção Configuration.

Anotações

A partir da biblioteca de runtime de funções Java, use a anotação @CosmosDBInput nos parâmetros que leem de Azure Cosmos DB. A anotação suporta as seguintes propriedades:

Configuração

Aplica-se apenas ao modelo de programação Python v1.

A tabela a seguir explica as propriedades que você pode definir no options objeto passado para o input.cosmosDB() método. As typepropriedades , direction, e name não se aplicam ao modelo v4.

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json, onde as propriedades diferem de acordo com a versão da extensão:

function.json propriedade Descrição
tipo Deve ser definido como cosmosDB.
direção Deve ser definido como in.
Designação O nome da variável usada no código da função que representa a lista de documentos com alterações.
conexão O nome de uma configuração de aplicação ou contentor que especifica como se ligar à conta do Azure Cosmos DB monitorizada. Para obter mais informações, consulte Conexões.
Nome do banco de dados O nome da base de dados Azure Cosmos DB com o contentor a ser monitorizado.
containerName O nome do contêiner que está sendo monitorado.
partitionKey Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de vinculação. É necessário para pesquisas em contêineres particionados .
ID A ID do documento a ser recuperado. Esta propriedade suporta expressões de ligação. Não defina as id propriedades e sqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
sqlQuery Uma consulta SQL do Azure Cosmos DB usada para recuperar múltiplos documentos. A propriedade suporta associações de tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina as id propriedades e sqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
preferredLocations (Opcional) Define localizações preferenciais (regiões) para contas de base de dados geo-replicadas no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, East US,South Central US,North Europe.

Consulte a seção Exemplo para obter exemplos completos.

Utilização

Quando a função é encerrada com êxito, todas as alterações feitas no documento de entrada são automaticamente persistidas.

O tipo de parâmetro suportado pela ligação de entrada do Cosmos DB depende da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

Quando você deseja que a função processe um único documento, a associação de entrada do Cosmos DB pode se vincular aos seguintes tipos:

Tipo Descrição
Tipos serializáveis JSON As funções tentam desserializar os dados JSON do documento em um tipo de objeto CLR antigo (POCO).

Quando você deseja que a função processe vários documentos de uma consulta, a associação de entrada do Cosmos DB pode se vincular aos seguintes tipos:

Tipo Descrição
IEnumerable<T>onde T é um tipo serializável JSON Uma enumeração de entidades retornadas pela consulta. Cada entrada representa um documento.
CosmosClient1 Um cliente conectado à conta do Cosmos DB.
Base de dados1 Um cliente conectado ao banco de dados do Cosmos DB.
Contentor1 Um cliente conectado ao contêiner do Cosmos DB.

1 Para usar estes tipos, precisa de consultar Microsoft.Azure. Functions.Worker.Extensions.CosmosDB 4.4.0 ou posterior e as dependências common para ligações de tipos SDK.

A partir da biblioteca de runtime de funções Java, a anotação @CosmosDBInput expõe os dados Azure Cosmos DB à função. Esta anotação pode ser usada com tipos nativos de Java, POJOs ou valores anuláveis usando Optional<T>.

Acesse o documento usando context.extraInputs.get().

As atualizações de documentos não são feitas automaticamente após a saída da função. Para atualizar documentos em uma função, use uma associação de saída. Consulte o exemplo do PowerShell para obter mais detalhes.

Os dados são disponibilizados para a função através de um DocumentList parâmetro. As alterações feitas no documento não são persistidas automaticamente. As funções também suportam bindings de tipos de SDK em Python para o Azure Cosmos, o que permite trabalhar com dados usando estes tipos de SDK subjacentes:

Importante

O suporte para tipos de SDK CosmosDB para Python está em Pré-visualização e é suportado apenas para o modelo de programação Python v2. Para mais informações, veja SDK tipos em Python.

Ligações

As propriedades e referenciam a configuração do ambiente que especifica como a aplicação se liga à Azure Cosmos DB. Podem especificar:

  • O nome de uma configuração de aplicação que contém uma cadeia de ligação.
  • O nome de um prefixo partilhado para múltiplas definições de aplicação, que em conjunto definem uma ligação de identidade gerida. Esta opção só está disponível para as connection versões e leaseConnection da versão 4.x ou superior da extensão.

Se o valor configurado for uma correspondência exata para uma única configuração e uma correspondência de prefixo para outras configurações, a correspondência exata será usada.

Sugestão

As ligações de identidade gerida são recomendadas em detrimento das cadeias de ligação para melhorar a segurança. As cadeias de ligação incluem credenciais que podem ser expostas, enquanto as identidades geridas eliminam a necessidade de gerir segredos.

Se estiveres a usar versão 4.x ou superior da extensão, em vez de usar um cadeia de ligação com um segredo, podes fazer com que a aplicação use uma identidade Microsoft Entra. Para isso, defina definições sob um prefixo comum que corresponda à propriedade de ligação na configuração de trigger e binding.

Neste modo, a extensão requer as seguintes definições de aplicação:

Cenário baseado em modelos Descrição Tipo de identidade
<CONNECTION_NAME_PREFIX>__accountEndpoint O endpoint endpoint da conta Azure Cosmos DB URI. Atribuído pelo sistema ou pelo utilizador
<CONNECTION_NAME_PREFIX>__credential Deve ser definido como managedidentity. Atribuída pelo utilizador
<CONNECTION_NAME_PREFIX>__clientId A ID do cliente da identidade gerenciada atribuída pelo usuário. Atribuída pelo utilizador

O valor por que substituires <CONNECTION_NAME_PREFIX> é tratado pela extensão de ligação como o nome da definição de ligação.

Por exemplo, se a sua configuração de binding especificar connection = "CosmosDBConnection" uma identidade gerida atribuída pelo utilizador, configure as seguintes definições de aplicação:

{
    "CosmosDBConnection__accountEndpoint": "https://mycosmosdb.documents.azure.com:443/",
    "CosmosDBConnection__credential": "managedidentity",
    "CosmosDBConnection__clientId": "00000000-0000-0000-0000-000000000000"
}

Sugestão

Use identidades geridas atribuídas pelo utilizador para cenários de produção onde precisa de controlo detalhado sobre permissões de identidade em múltiplos recursos.

Pode usar definições adicionais no modelo para personalizar ainda mais a ligação. Consulte Propriedades comuns para conexões baseadas em identidade.

Quando alojadas no serviço Funções do Azure, as ligações baseadas em identidade utilizam uma identidade gerida. A identidade atribuída ao sistema é usada por padrão, embora uma identidade atribuída ao usuário possa ser especificada com as credential propriedades e clientID . Observe que não há suporte para a configuração de uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, sua identidade de desenvolvedor é usada, embora isso possa ser personalizado. Consulte Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão à identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços Azure, isto significa que precisa de atribuir um papel no Azure RBAC, usando papéis incorporados ou personalizados que forneçam essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço de destino que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo só precisa ser capaz de ler de uma fonte de dados, use uma função que só tenha permissão para ler. Seria inadequado atribuir uma função que também permita escrever a esse serviço, pois isso seria uma permissão excessiva para uma operação de leitura. Da mesma forma, convém garantir que a atribuição de função tenha escopo apenas sobre os recursos que precisam ser lidos.

O Cosmos DB não utiliza o Azure RBAC para operações de dados. Em vez disso, ele usa um sistema RBAC integrado do Cosmos DB que é construído em conceitos semelhantes. Você precisará criar uma atribuição de função que forneça acesso à sua conta de banco de dados em tempo de execução. Azure cargos de gestão RBAC como Proprietário não são suficientes. A tabela seguinte mostra os papéis incorporados recomendados ao utilizar a extensão Azure Cosmos DB em funcionamento normal. Seu aplicativo pode exigir permissões adicionais com base no código que você escreve.

Tipo de vinculação Exemplo de funçõesinternas 1
Gatilho2 Colaborador de dados integrado do Cosmos DB
Vinculação de entrada Leitor de dados integrado do Cosmos DB
Vinculação de saída Colaborador de dados integrado do Cosmos DB

1 Estas funções não podem ser usadas numa atribuição de função Azure RBAC. Consulte a documentação do sistema RBAC integrado do Cosmos DB para obter detalhes sobre como atribuir essas funções.

2 Ao usar a identidade, o Cosmos DB trata a criação de contêineres como uma operação de gerenciamento. Ele não está disponível como uma operação de plano de dados para o gatilho. Você precisará garantir que você crie os contêineres necessários para o gatilho (incluindo o contêiner de concessão) antes de configurar sua função.

Próximos passos

  • Last updated on