Partilhar via

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

O Azure Functions permite-te ligar serviços Azure e outros recursos a funções sem teres de escrever o teu próprio código de integração. Essas ligações, que representam entrada e saída, são declaradas dentro da definição de função. Os dados de enlaces são fornecidos à função como parâmetros. Um gatilho é um tipo especial de associação de entrada. Embora uma função tenha apenas um gatilho, ela pode ter várias ligações de entrada e saída. Para saber mais, consulte Azure Functions gatilhos e conceitos de ligações.

Este artigo mostra-lhe como usar o Visual Studio Code para ligar Azure Cosmos DB à função que criou no artigo de quickstart anterior. A ligação de saída que adicionas a esta função escreve dados do pedido HTTP para um documento JSON armazenado num contentor do Azure Cosmos DB.

Antes de começar, deve completar o quickstart: Criar uma função C# em Azure usando Visual Studio Code. Se já limpaste os recursos no final desse artigo, repete os passos para recriar a aplicação de funções e os recursos relacionados no Azure.

Antes de começar, deve completar o quickstart: Criar uma função JavaScript em Azure usando Visual Studio Code. Se já limpaste os recursos no final desse artigo, repete os passos para recriar a aplicação de funções e os recursos relacionados no Azure.

Nota

Este artigo suporta Node.js v4 para Funções.

Antes de começar, deve completar o quickstart: Criar uma função Python em Azure usando Visual Studio Code. Se já limpaste os recursos no final desse artigo, repete os passos para recriar a aplicação de funções e os recursos relacionados no Azure.

Configurar o seu ambiente

Antes de get started, certifica-te de instalar a extensão Azure Databases para Visual Studio Code.

Crie a sua conta de base de dados Azure Cosmos

Agora, cria uma conta no Azure Cosmos DB como um tipo de conta serverless. Este modo baseado em consumo torna o Azure Cosmos DB uma opção forte para cargas de trabalho serverless.

  1. No Visual Studio Code, selecione View>Command Palette... depois na paleta de comandos, procure por Azure Databases: Create Server...

  2. Forneça as seguintes informações nas indicações:

    Sugestão Seleção
    seleciona um servidor de base de dados Azure Escolha Core (NoSQL) para criar uma base de dados de documentos que possa consultar usando uma sintaxe SQL ou um Query Copilot (Prévia) convertendo prompts de linguagem natural em consultas. Saiba mais sobre o Azure Cosmos DB.
    Nome da conta Introduza um nome único para identificar a sua conta de base de dados Azure Cosmos. O nome da conta pode usar apenas letras minúsculas, números e hífenes (-), e deve ter entre 3 e 31 caracteres.
    Selecione um modelo de capacidade Selecione Serverless para criar uma conta em modo serverless.
    Selecionar um grupo de recursos para novos recursos Escolha o grupo de recursos onde você criou seu aplicativo de função no artigo anterior.
    Selecione um local para novos recursos Selecione uma localização geográfica para alojar a sua conta de base de dados Azure Cosmos. Use o local mais próximo de si ou dos seus utilizadores para obter o acesso mais rápido aos seus dados.

    Depois que sua nova conta for provisionada, uma mensagem será exibida na área de notificação.

Criar uma base de dados e um contentor no Azure Cosmos DB

  1. Selecione o ícone Azure na barra de Atividade, expanda Resources>Azure Cosmos DB, clique com o botão direito (Ctrl+select no macOS) a sua conta e selecione Criar base de dados... .

  2. Forneça as seguintes informações nas indicações:

    Sugestão Seleção
    Nome da base de dados Escreva my-database.
    Insira um ID para a sua coleção Escreva my-container.
    Insira a chave de partição para a coleção Digite /id como a chave de partição.

  3. Selecione OK para criar o contêiner e o banco de dados.

Atualize as configurações do aplicativo de função

No artigo anterior quickstart, criaste uma aplicação de funções em Azure. Neste artigo, atualiza a sua aplicação para escrever documentos JSON no contentor Azure Cosmos DB que criou. Para se ligar à sua conta do Azure Cosmos DB, deve adicionar a sua connection string às definições da sua aplicação. Depois descarregas a nova definição para o teu ficheiro de local.settings.json para poderes ligar à tua conta Azure Cosmos DB quando estás a correr localmente.

  1. Em Visual Studio Code, clique com o botão direito (Ctrl+clique no macOS) na sua nova conta Azure Cosmos DB e selecione Copiar Connection String.

    Copiar a cadeia de ligação do Azure Cosmos DB

  2. Pressione F1 para abrir a paleta de comandos, depois procure e execute o comando Azure Functions: Add New Setting....

  3. Escolha o aplicativo de função que você criou no artigo anterior. Forneça as seguintes informações nas indicações:

    Sugestão Seleção
    Insira o nome da nova configuração do aplicativo Escreva CosmosDbConnectionString.
    Insira o valor para "CosmosDbConnectionString" Cola a connection string da tua conta de base de dados Azure Cosmos que copiaste. Você também pode configurar a identidade Microsoft Entra como uma alternativa.

    Isto cria uma configuração de aplicação chamada conexão CosmosDbConnectionString na tua aplicação de funções no Azure. Agora, você pode baixar essa configuração para seu arquivo local.settings.json.

  4. Prima novamente F1 para abrir a paleta de comandos, depois procura e executa o comando Azure Functions: Download Remote Settings....

  5. Escolha o aplicativo de função que você criou no artigo anterior. Selecione Sim para todos para substituir as configurações locais existentes.

Este processo descarrega todas as definições do Azure para seu projeto local, incluindo a nova definição de cadeia de ligação. A maioria das configurações baixadas não é usada quando executada localmente.

Registar extensões de ligação

Como estás a usar um binding de saída do Azure Cosmos DB, tens de ter a extensão correspondente de binding instalada antes de executares o projeto.

Exceto para gatilhos HTTP e timer, as ligações são implementadas como pacotes de extensão. Execute o seguinte comando dotnet add package na janela do Terminal para adicionar o pacote de extensão Azure Cosmos DB ao seu project.

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

O seu projeto foi configurado para usar conjuntos de extensões, que instalam automaticamente um conjunto predefinido de pacotes de extensão.

A utilização dos pacotes de extensão está ativada no ficheiro host.json na raiz do project, que aparece da seguinte forma:

{
  "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"
    }
  }
}

O seu projeto foi configurado para usar conjuntos de extensões, que instalam automaticamente um conjunto predefinido de pacotes de extensão.

A utilização dos pacotes de extensão está ativada no ficheiro host.json na raiz do project, que aparece da seguinte forma:

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

Agora, pode adicionar a ligação de saída do Azure Cosmos DB ao seu projeto.

Adicionar um enlace de saída

Num projeto de biblioteca de classes C#, as ligações são definidas como atributos de ligação no método da função.

Abra o ficheiro HttpExample.cs project e adicione as seguintes classes:

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

A MyDocument classe define um objeto que é gravado no banco de dados. O connection string para a conta Storage é definido pela propriedade Connection. Neste caso, podes omitir Connection porque já estás a usar a conta storage padrão.

A classe MultiResponse permite-lhe tanto escrever na coleção especificada na Azure Cosmos DB como devolver uma mensagem de sucesso HTTP. Como você precisa retornar um MultiResponse objeto, você também precisa atualizar a assinatura do método.

Atributos específicos especificam o nome do contêiner e o nome de seu banco de dados pai. A connection string para a sua conta Azure Cosmos DB é definida pelo CosmosDbConnectionString.

Os atributos de vinculaçã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 uma vinculação de saída do Azure Cosmos DB.

Para este MultiResponse cenário, é necessário adicionar uma ligaçã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 ligação:

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

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

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

Neste código, arg_name identifica o parâmetro de ligação referenciado no seu código, database_name e container_name são os nomes da base de dados e coleções onde a ligação escreve, e connection é o nome de uma configuração de aplicação que contém a connection string para a conta Azure Cosmos DB, que está na definição CosmosDbConnectionString no ficheiro local.settings.json.

Adicione código que utiliza a vinculação de saída

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

[Function("HttpExample")]
public MultiResponse Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequest req)
{
    _logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = "Welcome to Azure Functions!";

    // 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 = new OkObjectResult(message)
    };
}

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

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 ter a seguinte aparência:

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

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

Atualize function_app.py para corresponder ao código seguinte. Adicione o outputDocument parâmetro à definição da função e outputDocument.set() na if name: declaração:

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.FUNCTION)
@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="CosmosDbConnectionString")
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

Visual Studio Code integra com Azure Functions Core ferramentas para que possa executar este projeto no seu computador local de desenvolvimento antes de publicar no Azure. Se ainda não tiver o Core Tools instalado localmente, é solicitado a instalá-lo na primeira vez que executa o seu projecto.

  1. Para chamar a sua função, pressione F5 para iniciar o projeto da aplicação da função. O painel Terminal exibe a saída das Ferramentas Principais. Seu aplicativo é iniciado no painel Terminal . Você pode ver o endpoint da URL da sua função acionada por HTTP a ser executada localmente.

    Captura de ecrã da saída da função Local no Visual Studio Code.

    Se ainda não tiver o Core Tools instalado, selecione Install para instalar o Core Tools quando solicitado to do isso.
    Se tiveres dificuldades a correr no Windows, certifica-te de que o terminal predefinido para Visual Studio Code não está definido para WSL Bash.

  2. Com as Ferramentas Principais a funcionar, vai à área Azure: Funções. Em Funções, expanda Local Project>Funções. Clique com o botão direito do mouse (Windows) ou Ctrl - clique em (macOS) na HttpExample função e escolha Executar função agora....

    Captura de ecrã da função de execução agora a partir de Visual Studio Code.

  3. Na secção Introduza o corpo da solicitação, pressione Enter para enviar uma mensagem de solicitação para a sua função.

  4. Quando a função é executada localmente e devolve 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 as ferramentas principais e desconectar o depurador.

Executar a função localmente

  1. Como no artigo anterior, pressione F5 para iniciar o projeto da aplicação de funções e as Ferramentas Principais.

  2. Com o Core Tools a funcionar, vai à área Azure: Functions. Em Funções, expanda Local Project>Funções. Clique com o botão direito do rato (Ctrl-clique no Mac) na HttpExample função e escolha Executar Função Agora....

    Executar a função agora a partir de Visual Studio Code

  3. No Enter request body, é possível ver o valor do corpo da mensagem de pedido { "name": "Azure" }. Prima Enter para enviar esta mensagem de pedido para a sua função.

  4. Depois que uma resposta for retornada, pressione Ctrl + C para parar as Ferramentas Principais.

Verificar se um documento JSON foi criado

  1. No portal do Azure, volte à sua conta do Azure Cosmos DB e selecione Data Explorer.

  2. Expanda o banco de dados e o contêiner e selecione Itens para listar os documentos criados no contêiner.

  3. Verifique se um novo documento JSON foi criado pela associação de saída.

    Verificando que um novo documento foi criado no contentor Azure Cosmos DB

Reimplantar e verificar o aplicativo atualizado

  1. No Visual Studio Code, pressione F1 para abrir a paleta de comandos. Na paleta de comandos, procure e selecione Azure Functions: Deploy to function app....

  2. Escolha o aplicativo de função que você criou no primeiro artigo. Como estás a redistribuir o teu project na mesma aplicação, seleciona Deploy para ignorar o aviso sobre sobrescrever ficheiros.

  3. Depois de concluída a implementação, pode novamente usar a função Executar Agora... para ativar a função em Azure. Este comando recupera automaticamente a chave de acesso à função e utiliza-a ao chamar o endpoint HTTP trigger.

  4. Mais uma vez, verifica os documentos criados no teu contentor Azure Cosmos DB para verificar se a ligação de saída gera novamente um novo documento JSON.

Limpar recursos

Em Azure, recursos referem-se a aplicações de funções, funções, contas de armazenamento, e assim por diante. Eles são agrupados em grupos de recursos e você pode excluir tudo em um grupo excluindo o grupo.

Criou recursos para concluir estas iniciações rápidas. Pode ser cobrado por estes recursos, dependendo do estado da sua conta e dos preços dos serviços. Se já não precisar dos recursos, pode eliminá-los da seguinte forma:

  1. Em Visual Studio Código, pressione F1 para abrir a paleta de comandos. Na paleta de comandos, procure e selecione Azure: Open in portal.

  2. Escolha seu aplicativo de função e pressione Enter. A página da aplicação de funções abre no portal do Azure.

  3. Na guia Visão geral, selecione o link nomeado ao lado de Grupo de recursos.

    Captura de ecrã a mostrar a seleção do grupo de recursos a eliminar da página da aplicação de funções.

  4. Na página Grupo de recursos, revise a lista de recursos incluídos e verifique se eles são aqueles que você deseja excluir.

  5. Selecione Eliminar grupo de recursos e siga as instruções.

    O processo de eliminação pode demorar alguns minutos. Quando terminar, é apresentada uma notificação durante alguns segundos. Também pode selecionar o ícone de sino na parte superior da página para ver a notificação.

Próximos passos

Atualizou a sua função ativada por HTTP para escrever documentos JSON num contentor do Azure Cosmos DB. Agora pode aprender mais sobre o desenvolvimento de Funções usando o Visual Studio Code:

  • Last updated on