Azure Cosmos DB associação de saída para Azure Functions 2.x e superior

Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

Este artigo dá suporte a ambos os modelos de programação.

A função C# pode ser criada por meio de um dos seguintes modos C#:

• Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. O processo de trabalho isolado é necessário para dar suporte a funções C# em execução em versões LTS e não LTS .NET e no .NET Framework. As extensões para funções de processo de trabalho isoladas usam namespaces Microsoft.Azure.Functions.Worker.Extensions.*.
• Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions. Em uma variação desse modelo, o Functions pode ser executado usando scripts C#, que é compatível principalmente com a edição do portal C#. As extensões para funções em processo usam namespaces Microsoft.Azure.WebJobs.Extensions.*.

O suporte do Go não está disponível para essa ligação no momento.

• Gatilho de fila, salva a mensagem ao banco de dados por meio do valor de retorno
• Gatilho HTTP, salva um documento ao banco de dados por meio do valor de retorno
• Gatilho HTTP, salva um documento ao banco de dados por meio do valor de OutputBinding
• Gatilho HTTP, salva vários documentos ao banco de dados por meio do valor de OutputBinding

Gatilho de fila, salva a mensagem ao banco de dados por meio do valor de retorno

O exemplo a seguir mostra uma função Java que adiciona um documento a um banco de dados com dados de uma mensagem no Armazenamento de Filas.

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

Gatilho HTTP, salva um documento ao banco de dados por meio do valor de retorno

O exemplo a seguir mostra uma função Java cuja assinatura é anotada com @CosmosDBOutput e tem o valor retornado do tipo String. O documento JSON retornado pela função é gravado automaticamente na coleção de Azure Cosmos DB correspondente.

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

Gatilho HTTP, salva um documento ao banco de dados por meio do valor de OutputBinding

O exemplo a seguir mostra uma função Java que grava um documento para Azure Cosmos DB por meio de um parâmetro de saída OutputBinding<T>. Neste exemplo, o parâmetro outputItem precisa ser anotado com @CosmosDBOutput, não a assinatura de função. Usar OutputBinding<T> permite que sua função aproveite a associação para gravar o documento em Azure Cosmos DB ao mesmo tempo em que permite retornar um valor diferente para o chamador de função, como um documento JSON ou XML.

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

Gatilho HTTP, salva vários documentos ao banco de dados por meio do valor de OutputBinding

O exemplo a seguir mostra uma função Java que grava vários documentos para Azure Cosmos DB por meio de um parâmetro de saída OutputBinding<T>. Neste exemplo, o parâmetro outputItem precisa ser anotado com @CosmosDBOutput, não a assinatura de função. O parâmetro de saída outputItem tem uma lista de objetos ToDoItem como seu tipo de parâmetro de modelo. Usar OutputBinding<T> permite que sua função aproveite a associação para gravar os documentos em Azure Cosmos DB, permitindo também retornar um valor diferente para o chamador de função, como um documento JSON ou XML.

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

Na biblioteca Java functions runtime, use a anotação @CosmosDBOutput em parâmetros gravados em Azure Cosmos DB. O tipo de parâmetro de anotação deve ser OutputBinding<T>, em que T é um tipo de Java nativo ou um POJO.

O exemplo a seguir mostra como gravar dados em Azure Cosmos DB usando uma associação de saída. A associação é declarada no arquivo de configuração da função (functions.json) e usa dados de uma mensagem de fila e grava em um documento Azure Cosmos DB.

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
} 

No arquivo run.ps1, o objeto retornado da função é mapeado para um objeto EmployeeDocument, que é persistido no banco de dados.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
} 

O exemplo a seguir demonstra como gravar um documento em um banco de dados Azure Cosmos DB como a saída de uma função. O exemplo depende se você usa o v1 ou v2 Python modelo de programação.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

Atributos

As bibliotecas C# em processo e de processo de trabalho isolado 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#.

Decoradores

Aplica somente para o modelo de programação Python v2.

Para Python funções v2 definidas usando um decorador, as seguintes propriedades no cosmos_db_output:

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

Anotações

Na biblioteca Java functions runtime, use a anotação @CosmosDBOutput em parâmetros que gravam em Azure Cosmos DB. Essa anotação dá suporte às seguintes propriedades:

• nome
• connectionStringSetting
• databaseName
• collectionName
• createIfNotExists
• Datatype
• partitionKey
• preferredLocations
• useMultipleWriteLocations

Configuração

Aplica somente para o modelo de programação Python v1.

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json. Essas propriedades se diferenciam pela versão da extensão:

O parâmetro de função de saída deve ser definido como func.Out[func.Document]. Consulte o exemplo de saída para obter detalhes.

Os tipos específicos com suporte pela associação de saída do Cosmos DB dependem da versão de runtime do Functions, da versão do pacote de extensão e da modalidade de C# usada.