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

O Azure Functions lhe permite conectar os serviços do Azure e outros recursos às funções sem precisar escrever seu próprio código de integração. Essas associações, que representam a entrada e a saída, são declaradas na definição de função. Dados de associações 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 associações de entrada e de saída. Para saber mais, confira Conceitos de gatilhos e de associações do Azure Functions.

Este artigo mostrará de que modo usar o Visual Studio Code para conectar o Azure Cosmos DB à função criada no artigo anterior do guia de início rápido. A associação de saída adicionada a essa função gravará dados da solicitação HTTP em um documento JSON armazenado em um contêiner do Azure Cosmos DB.

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.

Configurar seu ambiente

Antes de começar, lembre-se de instalar a extensão de Bancos de Dados do Azure no Visual Studio Code.

Criar uma conta do Azure Cosmos DB

Importante

O Azure Cosmos DB sem servidor já está em disponibilidade geral. Esse modo baseado em consumo torna o Azure Cosmos DB uma opção forte para cargas de trabalho sem servidor. Para usar o Azure Cosmos DB no modo sem servidor, escolha a opção Sem Servidor como o Modo de capacidade durante a criação de sua conta.

  1. No Visual Studio Code, escolha o ícone do Azure na barra de atividade.

  2. Na área Azure: Bancos de Dados, clique com o botão direito do mouse (Ctrl+clique no macOS) na assinatura do Azure em que você criou seu aplicativo de funções no artigo anterior e selecione Criar Servidor…

    Creating a new Azure Cosmos DB account from Visual Studio code

  3. Forneça as seguintes informações nos prompts:

    Prompt Seleção
    Selecionar um servidor de banco de dados do Azure Escolha Core (SQL) para criar um banco de dados de documentos em que você poderá executar uma consulta usando uma sintaxe SQL. Saiba mais sobre a API do SQL do Azure Cosmos DB.
    Nome da Conta Insira um nome exclusivo para identificar a conta do Azure Cosmos DB. O nome da conta pode usar apenas letras minúsculas, números e hifens (-) e deve ter de 3 a 31 caracteres.
    Selecione um modelo de capacidade Selecione Sem servidor para criar uma conta no modo sem servidor.
    Selecione um grupo de recursos para novos recursos Escolha o grupo de recursos em que o aplicativo de funções foi criado no artigo anterior.
    Selecione uma localização para novos recursos Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima de você ou de seus usuários para obter um acesso mais rápido aos dados.

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

Criar um banco de dados e um contêiner do Azure Cosmos DB

  1. Clique com o botão direito do mouse na sua conta e selecione Criar banco de dados….

  2. Forneça as seguintes informações nos prompts:

    Prompt Seleção
    Nome do banco de dados Digite my-database.
    Insira uma ID para sua coleção Digite 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.

Atualizar as configurações do aplicativo de funções

No artigo anterior do guia de início rápido, um aplicativo de funções foi criado no Azure. Neste artigo, você atualizará seu aplicativo para gravar documentos JSON no contêiner do Azure Cosmos DB que você acabou de criar. Para se conectar à conta do Azure Cosmos DB, será necessário adicionar a cadeia de conexão dela às configurações do aplicativo. Depois baixe a nova configuração no arquivo local.settings.json para que seja possível se conectar à conta do Azure Cosmos DB quando ela estiver em execução localmente.

  1. No Visual Studio Code, clique com o botão direito do mouse (Ctrl+clique no macOS) na sua nova conta do Azure Cosmos DB e selecione Copiar Cadeia de Conexão.

    Copying the Azure Cosmos DB connection string

  2. Pressione a tecla F1 para abrir a paleta de comandos, depois pesquise 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 nos prompts:

    Prompt Seleção
    Insira o nome da configuração do novo aplicativo Digite CosmosDbConnectionString.
    Insira o valor para "CosmosDbConnectionString" Cole a cadeia de conexão da sua conta do Azure Cosmos DB que você acabou de copiar.

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

  4. Pressione a tecla F1 novamente para abrir a paleta de comandos, depois pesquise e execute 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.

Isso baixa toda a configuração do Azure para seu projeto local, incluindo a nova configuração da cadeia de conexão. A maioria das configurações baixadas não é usada durante a execução local.

Registrar as extensões de associação

Como você está usando uma associação de saída do Azure Cosmos DB, será necessário obter a extensão das associações correspondentes instalada antes de executar o projeto.

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.WebJobs.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",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[1.*, 2.0.0)"
  } 
}

Agora é possível adicionar a associação de saída do Azure Cosmos DB ao seu projeto.

Adicionar uma associação de saída

No Functions, cada tipo de associação requer que um direction, type e um name exclusivo seja definido no arquivo functions.json. A maneira como você define esses atributos depende do idioma do seu aplicativo de funções.

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. O arquivo function.json exigido por Functions é gerado automaticamente com base nesses atributos.

Abra o arquivo de projeto HttpExample.cs e adicione o seguinte parâmetro à definição do método :

[CosmosDB(databaseName: "my-database", collectionName: "my-container",
    ConnectionStringSetting = "CosmosDbConnectionString"
    )]IAsyncCollector<dynamic> documentsOut,

O parâmetro documentsOut é do tipo IAsyncCollector<T>. Ele representa uma coleção de documentos JSON que serão gravados no contêiner do Azure Cosmos DB após a conclusão da função. Os atributos específicos indicam os nomes do contêiner e do banco de dados pai. A cadeia de conexão de sua conta do Azure Cosmos DB será definida pelo ConnectionStringSettingAttribute.

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 CosmosDbConnectionString.

Atributos de associação são definidos diretamente no arquivo function.json. Dependendo do tipo de associação, outras propriedades podem ser necessárias. 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. A extensão facilita a inclusão de associações no arquivo function.json.

Para criar uma associação, clique com o botão direito do mouse (Ctrl+clique no macOS) no arquivo function.json na pasta HttpTrigger e escolha Adicionar associação... . Siga os prompts para definir as seguintes propriedades de associação para a nova associação:

Prompt Valor Descrição
Selecionar direção de associação out A associação é uma associação de saída.
Selecionar associação com direção de saída Azure Cosmos DB A associação é uma associação do Azure Cosmos DB.
O nome usado para identificar essa associação em seu código outputDocument Nome que identifica o parâmetro de associação referenciado em seu código.
O banco de dados do Cosmos DB em que os dados serão gravados my-database O nome do banco de dados do Azure Cosmos DB em que o contêiner de destino está localizado.
A coleção de bancos de dados em que os dados serão gravados my-container O nome do contêiner do Azure Cosmos DB em que os documentos JSON serão gravados.
Se for true, cria o banco de dados e a coleção do Cosmos DB false O banco de dados e o contêiner de destino já existem.
Selecione a configuração de "local.setting.json" CosmosDbConnectionString O nome de uma configuração de aplicativo que contém a cadeia de conexão da conta do Azure Cosmos DB.
Chave de partição (opcional) deixar em branco Será necessário somente quando a associação de saída criar o contêiner.
Produtividade da coleção (opcional) deixar em branco Será necessário somente quando a associação de saída criar o contêiner.

Uma associação é incluída na matriz bindings no seu function.json, que deve ter a seguinte aparência após a remoção dos valores undefined presentes

{
    "type": "cosmosDB",
    "direction": "out",
    "name": "outputDocument",
    "databaseName": "my-database",
    "collectionName": "my-container",
    "createIfNotExists": "false",
    "connectionStringSetting": "CosmosDbConnectionString"
}

Adicionar o código que usa a associação de saída

Adicione o código que usa o objeto de associação de saída documentsOut para criar um documento JSON. Adicione esse código antes do método retornar.

if (!string.IsNullOrEmpty(name))
{
    // Add a JSON document to the output container.
    await documentsOut.AddAsync(new
    {
        // create a random ID
        id = System.Guid.NewGuid().ToString(),
        name = name
    });
}

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

[FunctionName("HttpExample")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
    [CosmosDB(
        databaseName: "my-database",
        collectionName: "my-container",
        ConnectionStringSetting = "CosmosDbConnectionString")]IAsyncCollector<dynamic> documentsOut,
    ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;

    if (!string.IsNullOrEmpty(name))
    {
        // Add a JSON document to the output container.
        await documentsOut.AddAsync(new
        {
            // create a random ID
            id = System.Guid.NewGuid().ToString(),
            name = name
        });
    }

    string responseMessage = string.IsNullOrEmpty(name)
        ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
        : $"Hello, {name}. This HTTP triggered function executed successfully.";

    return new OkObjectResult(responseMessage);
}

Adicione o código que usa o objeto de associação de saída outputDocument em context.bindings para criar um documento JSON. Adicione esse código antes da instrução context.res.

if (name) {
    context.bindings.outputDocument = JSON.stringify({
        // 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:

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    const name = (req.query.name || (req.body && req.body.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.";

    if (name) {
        context.bindings.outputDocument = JSON.stringify({
            // create a random ID
            id: new Date().toISOString() + Math.random().toString().substring(2, 10),
            name: name
        });
    }

    context.res = {
        // status: 200, /* Defaults to 200 */
        body: responseMessage
    };
}

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

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.

  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.

    Screenshot of the Local function Visual Studio Code output.

    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... .

    Screenshot of execute function now from Visual Studio Code.

  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... .

    Execute function now from Visual Studio Code

  3. Em Insira o corpo da solicitação, você verá o valor do corpo da mensagem de solicitação igual a . 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.

Verificar se o documento JSON foi criado

  1. No portal do Azure, navegue de volta para sua conta do Azure Cosmos DB e selecione Data Explorer.

  2. Expanda o banco de dados e o contêiner, depois selecione Itens para listar os documentos criados em seu contêiner.

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

    Verifying that a new document has been created in the Azure Cosmos DB container

Reimplementar e verificar o aplicativo atualizado

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

  2. Escolha o aplicativo de funções que você criou no primeiro artigo. Como você está reimplantando seu projeto no mesmo aplicativo, selecione Implantar para descartar o aviso de substituição de arquivos.

  3. Após a conclusão da implantação, use novamente o recurso Executar Função Agora... para disparar a função no Azure.

  4. Clique mais uma vez em Verificar os documentos criados no contêiner do Azure Cosmos DB para verificar se a associação de saída vai gerar um documento JSON novamente.

Limpar os recursos

No Azure, os Recursos se referem a aplicativos 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 junto ao excluir o grupo.

Você criou recursos para concluir esses guias de início rápido. Você pode ser cobrado por esses recursos, dependendo do status de conta e preços do serviço. Caso não precise mais dos recursos, é possível excluí-los desta maneira:

  1. No Visual Studio Code, pressione F1 para abrir a paleta de comandos. Na paleta de comandos, pesquise e selecione Azure: Open in portal.

  2. Escolha seu aplicativo de funções e pressione ENTER. A página do aplicativo de funções é aberta no portal do Azure.

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

    Screenshot of select the resource group to delete from the function app page.

  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. Na página Grupo de recursos, examine a lista de recursos incluídos e verifique se eles são aqueles que deseja excluir.

  6. Selecione Excluir grupo de recursos e siga as instruções.

    A exclusão poderá levar alguns minutos. Ao ser concluída, uma notificação será exibida por alguns segundos. Também é possível selecionar o ícone de sino na parte superior da página para exibir a notificação.

Próximas etapas

Você atualizou uma função disparada por HTTP para gravar documentos JSON em um contêiner do Azure Cosmos DB. Agora você pode saber mais sobre o desenvolvimento no Functions usando o Visual Studio Code: