Vinculação de entrada do Azure Cosmos DB para o Azure Functions 2.x e superior

  • Artigo

O enlace de entrada do Azure Cosmos DB utiliza a API do SQL para obter um ou mais documentos do Azure Cosmos DB e passa-os para o 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 obter mais detalhes sobre como o modelo v4 funciona, consulte o Guia do desenvolvedor do Azure Functions Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.

O Azure Functions 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 definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.

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

Exemplo

Salvo indicação em contrário, os exemplos neste artigo destinam-se à versão 3.x da extensão do 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. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
  • 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#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

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 seção contém exemplos que exigem a versão 3.x da extensão do Azure Cosmos DB e a 5.x da extensão do 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 a seguir 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 tempo de execução de funções Java, use a @CosmosDBInput anotação em parâmetros de função cujo valor viria do Azure Cosmos DB. Essa anotação pode ser usada com tipos Java nativos, POJOs ou valores anuláveis usando Optional<T>.

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

O exemplo a seguir 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 a seguir 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 a seguir 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 consumirá 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 a seguir mostra uma função Java que recupera vários 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 a seguir 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 associação de entrada do Azure Cosmos DB é listada primeiro na lista de associações encontradas no arquivo 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 a seguir 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 associação de entrada do Azure Cosmos DB é listada primeiro na lista de associações encontradas no arquivo 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 a seguir 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 route é definido na propriedade da associação route de solicitação HTTP e referenciado na propriedade de associação do Azure Cosmos DB "Id": "{Id}" .

A associação de entrada do Azure Cosmos DB é listada primeiro na lista de associações encontradas no arquivo 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 a seguir demonstra como ler vários 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 você usa o modelo de programação Python v1 ou v2.

Gatilho de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma associaçã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]):
     document = documents[id]
     document["text"] = "This was updated!"
     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 a seguir mostra uma função Python de vinculação de entrada do Azure Cosmos DB que usa 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 Description
Ligação O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo consultada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
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 vários 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 locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente 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.

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

Property Description
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 do banco de dados do Azure Cosmos DB com a coleção sendo monitorada.
container_name O nome da coleção do Azure Cosmos DB que está sendo monitorada.
connection A cadeia de conexão do Azure Cosmos DB que está sendo monitorada.
partition_key A chave de partição do Azure Cosmos DB que está sendo monitorada.
id A ID do documento a ser recuperado.

Para funções Python definidas usando function.json, consulte a seção Configuração .

Anotações

Na biblioteca de tempo de execução de funções Java, use a @CosmosDBInput anotação em parâmetros lidos do 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 Description
type 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 aplicativo ou contêiner de configuração que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorada. Para obter mais informações, consulte Conexões.
Nome do banco de dados O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
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 vários 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 locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente 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 Description
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 Description
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 esses tipos, você precisa fazer referência a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 ou posterior e às dependências comuns para associações de tipo SDK.

Na biblioteca de tempo de execução de funções Java, a anotação @CosmosDBInput expõe os dados do Azure Cosmos DB à função. Essa anotação pode ser usada com tipos Java nativos, 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.

Ligações

As connectionStringSetting/connection propriedades e leaseConnectionStringSetting/leaseConnection são referências à configuração do ambiente que especifica como o aplicativo deve se conectar ao Azure Cosmos DB. Podem especificar:

  • O nome de uma configuração de aplicativo que contém uma cadeia de conexão
  • O nome de um prefixo compartilhado para várias configurações de aplicativo, definindo em conjunto uma conexão baseada em identidade. 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.

Connection string

A cadeia de conexão para sua conta de banco de dados deve ser armazenada em uma configuração de aplicativo com um nome correspondente ao valor especificado pela propriedade connection da configuração de ligação.

Conexões baseadas em identidade

Se você estiver usando a versão 4.x ou superior da extensão, em vez de usar uma cadeia de conexão com um segredo, você pode fazer com que o aplicativo use uma identidade do Microsoft Entra. Para tal, deverá especificar as definições num prefixo comum que mapeia para a propriedade de connection na configuração do enlace e do acionador.

Neste modo, a extensão requer as seguintes propriedades:

Property Modelo de variável de ambiente Description Valor de exemplo
Ponto de extremidade da conta <CONNECTION_NAME_PREFIX>__accountEndpoint O URI do ponto de extremidade da conta do Azure Cosmos DB. https://< database_account_name.documents.azure.com:443/>

Propriedades adicionais podem ser definidas para personalizar a conexão. Consulte Propriedades comuns para conexões baseadas em identidade.

Quando hospedadas no serviço Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. 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 do Azure, isso significa que você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem 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 usa o RBAC do Azure 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. As funções de Gerenciamento do RBAC do Azure, como Proprietário , não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão do Azure Cosmos DB em operação 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 Essas funções não podem ser usadas em uma atribuição de função RBAC do Azure. 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