Conectar o Azure Functions ao Azure Cosmos DB usando o Visual Studio Code

Antes de começar, você precisa concluir o Guia de início rápido: Criar uma função C# no Azure usando o Visual Studio Code. Se você já limpou os recursos ao final daquele artigo, percorra as etapas novamente para recriar o aplicativo de funções e recursos relacionados no Azure.

Antes de começar, você precisa concluir o Guia de início rápido: Criar uma função JavaScript no Azure usando o Visual Studio Code. Se você já limpou os recursos ao final daquele artigo, percorra as etapas novamente para recriar o aplicativo de funções e recursos relacionados no Azure.

Antes de começar, você precisa concluir o Guia de início rápido: Criar uma função do Python no Azure usando o Visual Studio Code. Se você já limpou os recursos ao final daquele artigo, percorra as etapas novamente para recriar o aplicativo de funções e recursos relacionados no Azure.

Com exceção dos gatilhos de timer e HTTP, as associações são implementadas como pacotes de extensão. Execute o comando dotnet add package a seguir na janela Terminal para adicionar o pacote de extensão do Azure Cosmos DB ao seu projeto.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

Seu projeto foi configurado para usar pacotes de extensão, que instalam automaticamente um conjunto predefinido de pacotes de extensão.

O uso de pacotes de extensão é habilitado no arquivo host.json na raiz do projeto, cuja aparência é semelhante à seguinte:

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  },
  "concurrency": {
    "dynamicConcurrencyEnabled": true,
    "snapshotPersistenceEnabled": true
  },
  "extensions": {
    "cosmosDB": {
      "connectionMode": "Gateway"
    }
  }
}

Seu projeto foi configurado para usar pacotes de extensão, que instalam automaticamente um conjunto predefinido de pacotes de extensão.

O uso de pacotes de extensão é habilitado no arquivo host.json na raiz do projeto, cuja aparência é semelhante à seguinte:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  } 
}

Em um projeto de biblioteca de classes C#, as associações são definidas como atributos de associação no método de função.

Abra o arquivo de projeto HttpExample.cs e adicione as seguintes classes:

public class MultiResponse
{
    [CosmosDBOutput("my-database", "my-container",
        Connection = "CosmosDbConnectionSetting", CreateIfNotExists = true)]
    public MyDocument Document { get; set; }
    public HttpResponseData HttpResponse { get; set; }
}
public class MyDocument {
    public string id { get; set; }
    public string message { get; set; }
}

A classe MyDocument define um objeto que é gravado no banco de dados. A cadeia de conexão para a conta de armazenamento é definida pela propriedade Connection. Nesse caso, você poderia omitir Connection porque já está usando a conta de armazenamento padrão.

A classe MultiResponse permite que você faz gravações na coleção especificada do Azure Cosmos DB e retorne uma mensagem de êxito HTTP. Como você precisa retornar um objeto MultiResponse, também precisa atualizar a assinatura do método.

Os atributos específicos indicam o nome do contêiner e do nome do banco de dados pai. A cadeia de conexão de sua conta do Azure Cosmos DB será definida pelo CosmosDbConnectionSetting.

Os atributos de associação são definidos diretamente no código da função. A configuração de saída do Azure Cosmos DB descreve os campos necessários para executar uma associação de saída do Azure Cosmos DB.

Para esse cenário MultiResponse, você precisa adicionar uma associação de saída extraOutputs à função.

app.http('HttpExample', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {

Adicione as seguintes propriedades à configuração de associação:

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

Os atributos de associação são definidos diretamente no arquivo function_app.py. Use o decorador cosmos_db_output para adicionar uma associação de saída do Azure Cosmos DB:

@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", 
    container_name="my-container", connection="CosmosDbConnectionSetting")

Nesse código, arg_name identifica o parâmetro de associação referenciado no código, database_name e container_name são os nomes do banco de dados e da coleção nos quais a associação faz a gravação e connection é o nome de uma configuração de aplicativo que contém a cadeia de conexão para a conta do Azure Cosmos DB, que está na configuração CosmosDbConnectionSetting no arquivo local.settings.json.

Substitua o método Run existente pelo seguinte código:

[Function("HttpExample")]
public static MultiResponse Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger("HttpExample");
    logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = "Welcome to Azure Functions!";

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString(message);

    // Return a response to both HTTP trigger and Azure Cosmos DB output binding.
    return new MultiResponse()
    {
         Document = new MyDocument
        {
            id = System.Guid.NewGuid().ToString(),
            message = message
        },
        HttpResponse = response
    };
}

Adicione o código que usa o objeto de associação de saída extraInputs em context para enviar um documento JSON para a função de associação de saída nomeada, sendToCosmosDb. Adicione esse código antes da instrução return.

context.extraOutputs.set(sendToCosmosDb, {
  // create a random ID
  id:
    new Date().toISOString() + Math.random().toString().substring(2, 10),
  name: name,
});

Neste ponto, sua função deve ser a seguinte:

const { app, output } = require('@azure/functions');

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

app.http('HttpExampleToCosmosDB', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {
    try {
      context.log(`Http function processed request for url "${request.url}"`);

      const name = request.query.get('name') || (await request.text());

      if (!name) {
        return { status: 404, body: 'Missing required data' };
      }

      // Output to Database
      context.extraOutputs.set(sendToCosmosDb, {
        // create a random ID
        id:
          new Date().toISOString() + Math.random().toString().substring(2, 10),
        name: name,
      });

      const responseMessage = name
        ? 'Hello, ' +
          name +
          '. This HTTP triggered function executed successfully.'
        : 'This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.';

      // Return to HTTP client
      return { body: responseMessage };
    } catch (error) {
      context.log(`Error: ${error}`);
      return { status: 500, body: 'Internal Server Error' };
    }
  },
});

Este código agora retorna um objeto MultiResponse que contém um documento e uma resposta HTTP.

Atualize HttpExample\function_app.py para correspondê-lo ao código a seguir. Atualize o parâmetro outputDocument à definição de função e outputDocument.set() abaixo da instrução if name::

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", container_name="my-container", connection="CosmosDbConnectionSetting")
def test_function(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
    outputDocument: func.Out[func.Document]) -> func.HttpResponse:
     logging.info('Python HTTP trigger function processed a request.')
     logging.info('Python Cosmos DB trigger function processed a request.')
     name = req.params.get('name')
     if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

     if name:
        outputDocument.set(func.Document.from_dict({"id": name}))
        msg.set(name)
        return func.HttpResponse(f"Hello {name}!")
     else:
        return func.HttpResponse(
                    "Please pass a name on the query string or in the request body",
                    status_code=400
                )

O documento {"id": "name"} é criado na coleção de banco de dados especificada na associação.

Executar a função localmente

O Visual Studio Code integra-se ao Azure Functions Core Tools para permitir que você execute esse projeto em seu computador de desenvolvimento local antes da publicação no Azure. Se você ainda não tiver o Core Tools instalado localmente, será solicitado que você o instale na primeira vez que executar o projeto.

1. Para chamar sua função, pressione F5 para iniciar o projeto de aplicativo de funções. O painel Terminal exibirá a saída do Core Tools. Seu aplicativo é iniciado no painel Terminal. Você pode ver o ponto de extremidade de URL de sua função disparada por HTTP localmente.

   

   Se o Core Tools ainda não estiver instalado, selecione Instalar para instalar o Core Tools quando solicitado a fazê-lo.
   Se você tiver problemas com a execução no Windows, verifique se o terminal padrão do Visual Studio Code não está definido como bash WSL.

2. Com o Core Tools em execução, acesse a área Azure: Funções. Em Funções, expanda Projeto Local>Funções. Clique com o botão direito do mouse (Windows) ou clique em CTRL - (macOS) na função HttpExample e escolha Função Executar Agora... .

   

3. Em Insira o corpo da solicitação, pressione ENTER para enviar uma mensagem à função.

4. Quando a função é executada localmente e retorna uma resposta, uma notificação é gerada no Visual Studio Code. As informações sobre a execução da função são mostradas no painel Terminal.

5. Pressione Ctrl + C para parar o Core Tools e desconectar o depurador.

Executar a função localmente

1. Como no artigo anterior, clique em F5 para iniciar o projeto do aplicativo de funções e o Core Tools.

2. Com o Core Tools em execução, acesse a área Azure: Funções. Em Funções, expanda Projeto Local>Funções. Clique com o botão direito do mouse (CTRL-clique no Mac) na função HttpExample e escolha Executar Função Agora... .

   

3. Em Insira o corpo da solicitação, você verá o valor do corpo da mensagem de solicitação igual a { "name": "Azure" }. Clique em ENTER para enviar essa mensagem de solicitação à função.

4. Depois que uma resposta for retornada, clique em CTRL + C para interromper o Core Tools.

• Exemplos de projetos de função completos em C#.

• Referência do desenvolvedor de C# do Azure Functions

• Exemplos de projetos de função completos em JavaScript.

• Guia do desenvolvedor de JavaScript do Azure Functions

• Exemplos de projetos de função completos no Python.

• Guia do desenvolvedor do Python para o Azure Functions