Armazenar dados não estruturados usando o Azure Functions e o Azure Cosmos DB

O Azure Cosmos DB é uma ótima maneira de armazenar dados não estruturados e JSON. Combinado com o Azure Functions, o Azure Cosmos DB acelera e facilita o armazenamento de dados com muito menos código do que o necessário para armazenar dados em um banco de dados relacional.

No Azure Functions, associações de entrada e saída fornecem uma maneira declarativa para se conectar a dados de serviço externo de sua função. Neste artigo, saiba como atualizar uma função existente a fim de adicionar uma associação de saída que armazena dados não estruturados em um documento do Azure Cosmos DB.

Pré-requisitos

Para concluir este tutorial:

Este tópico usa como ponto de partida os recursos criados em Criar sua primeira função no portal do Azure. Se você ainda não fez isso, conclua estas etapas agora para criar seu aplicativo de funções.

Criar uma conta do Azure Cosmos DB

Antes de criar a associação de saída, você precisa ter uma conta do Azure Cosmos DB que use a API de SQL.

1. No menu do portal do Azure ou na Home page, selecione Criar um recurso.

2. Pesquise por Azure Cosmos DB. Selecione Criar>Azure Cosmos DB.

3. Na página Criar uma conta do Azure Cosmos DB, selecione a opção Criar na seção Azure Cosmos DB for NoSQL.

   O Azure Cosmos DB fornece várias APIs:

   • NoSQL, para dados do documento
   • PostgreSQL
   • MongoDB, para dados do documento
   • Apache Cassandra
   • Tabela
   • Apache Gremlin, para dados do grafo

   Para saber mais sobre a API para NoSQL, confira Bem-vindo(a) ao Azure Cosmos DB.

4. Na página Criar uma Conta do Azure Cosmos DB, insira as configurações básicas da nova conta do Azure Cosmos DB.

   Configuração	Valor	Descrição
   Subscription	Nome da assinatura	Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos DB.
   Grupo de recursos	Nome do grupo de recursos	Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.
   Nome da Conta	Um nome exclusivo	Insira um nome para identificar a conta do Azure Cosmos DB. Já que documents.Azure.com é acrescentado ao nome que você fornece para criar o URI, use um nome exclusivo. O nome pode conter apenas letras minúsculas, números e o caractere de hífen (-). Deve ter de 3 a 44 caracteres.
   Location	A região mais próxima dos usuários	Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.
   Modo de capacidade	Taxa de transferência provisionada ou sem servidor	Selecione Taxa de transferência provisionada para criar uma conta no modo taxa de transferência provisionada. Selecione Sem servidor para criar uma conta no modo sem servidor.
   Aplicar o desconto por nível gratuito do Azure Cosmos DB	Aplicar ou Não aplicar	Com a camada gratuita do Azure Cosmos DB, você recebe os primeiros 1000 RU/s e 25 GB de armazenamento sem custos em uma conta. Saiba mais sobre o nível gratuito.
   Limitar a taxa de transferência total da conta	Selecionado ou não	Limite a quantidade total da taxa de transferência que pode ser provisionada nessa conta. Esse limite impede encargos inesperados relacionados à taxa de transferência provisionada. Você pode atualizar ou remover esse limite depois que sua conta for criada.

   Você pode ter até uma conta gratuita do Azure Cosmos DB por assinatura do Azure e deve aceitar ao criar a conta. Se você não vê a opção de aplicar o desconto por nível gratuito, outra conta da assinatura já foi habilitada com o nível gratuito.

   

   Observação

   As seguintes opções não estarão disponíveis se você selecionar Sem servidor como Modo de capacidade:

   • Aplicar desconto por nível gratuito
   • Limitar a taxa de transferência total da conta

5. Na guia Distribuição global, configure os detalhes a seguir. Para este início rápido, é possível usar os valores padrão:

   Configuração	Valor	Descrição
   Redundância geográfica	Desabilitar	Habilite ou desabilite a distribuição global em sua conta emparelhando sua região com uma região de par. Você poderá adicionar mais regiões à sua conta posteriormente.
   Gravações de várias regiões	Desabilitar	A capacidade de gravação de várias regiões permite que você aproveite a taxa de transferência provisionada para seus bancos de dados e contêineres em todo o mundo.
   Zonas de Disponibilidades	Desabilitar	As Zonas de Disponibilidade ajudam a aprimorar a disponibilidade e a resiliência do seu aplicativo.

   Observação

   As seguintes opções não estarão disponíveis se você selecionar Sem servidor como Modo de capacidade na página anterior Noções básicas:

   • Redundância geográfica
   • Gravações de várias regiões

6. Opcionalmente, você pode configurar mais detalhes nas seguintes guias:

   • Redes. Configure o acesso a partir de uma rede virtual.
   • Política de Backup. Configure uma política de backup periódica ou contínua.
   • Criptografia. Use uma chave gerenciada pelo serviço ou uma chave gerenciada pelo cliente.
   • Marcas. Marcas são pares nome/valor que permitem categorizar recursos e exibir a cobrança consolidada por meio da aplicação da mesma marca a vários recursos e grupos de recursos.

7. Selecione Examinar + criar.

8. Examine as configurações da conta e selecione Criar. São necessários alguns minutos para criar a conta. Aguarde até que a página do portal exiba Sua implantação está concluída.

   

9. Selecione Ir para recurso para ir para a página da conta do Azure Cosmos DB.

   

Adicionar uma associação de saída

1. No portal do Azure, navegue até o aplicativo de funções que você criou anteriormente e selecione-o.

2. Selecione Funções e a função HttpTrigger.

   

3. Selecione Integração e + Adicionar saída.

   

4. Use a configuração Criar Saída conforme especificado na tabela:

   

   Configuração	Valor sugerido	Descrição
   Tipo de Associação	Azure Cosmos DB	Nome do tipo de associação a ser selecionado para criar a associação de saída ao Azure Cosmos DB.
   Nome do parâmetro do documento	taskDocument	Nome que se refere ao objeto Azure Cosmos DB no código.
   Nome do banco de dados	taskDatabase	Nome do banco de dados para salvar os documentos.
   Nome da coleção	taskCollection	Nome da coleção de banco de dados.
   Quando é true, cria o banco de dados e a coleção do Azure Cosmos DB	Sim	A coleção ainda não existe, então crie uma.
   Conexão de conta do Azure Cosmos DB	Nova configuração	Selecione Novo e depois escolha sua Conta do Azure Cosmos DB e a Conta de banco de dados criada anteriormente e, em seguida, selecione OK. Isso cria uma configuração de aplicativo para sua conexão de conta. Essa configuração é usada pela associação para conexão com o banco de dados.

5. Selecione OK para criar a associação.

Atualizar o código de função

Substitua o código existente da função pelo código a seguir na linguagem que você escolheu:

#r "Newtonsoft.Json"

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

public static IActionResult Run(HttpRequest req, out object taskDocument, ILogger log)
{
    string name = req.Query["name"];
    string task = req.Query["task"];
    string duedate = req.Query["duedate"];

    // We need both name and task parameters.
    if (!string.IsNullOrEmpty(name) && !string.IsNullOrEmpty(task))
    {
        taskDocument = new
        {
            name,
            duedate,
            task
        };

        return (ActionResult)new OkResult();
    }
    else
    {
        taskDocument = null;
        return (ActionResult)new BadRequestResult();
    }
}

module.exports = async function (context, req) {

    // We need both name and task parameters.
    if (req.query.name && req.query.task) {

        // Set the output binding data from the query object.
        context.bindings.taskDocument = req.query;

        // Success.
        context.res = {
            status: 200
        };
    }
    else {
        context.res = {
            status: 400,
            body: "The query options 'name' and 'task' are required."
        };
    }
};

Esse exemplo de código lê as cadeias de consulta da Solicitação HTTP e as atribui a campos no objeto taskDocument. A associação taskDocument envia os dados do objeto desse parâmetro de associação para armazenamento no banco de dados de documento associado. O banco de dados é criado na primeira execução da função.

Testar a função e o banco de dados

1. Selecione Testar/Executar. Em Consulta, selecione + Adicionar parâmetro e adicione os seguintes parâmetros à cadeia de caracteres de consulta:

   • name
   • task
   • duedate

   

2. Selecione Executar e verifique se um status 200 é retornado.

   

3. No portal do Azure, pesquise e selecione Azure Cosmos DB.

   

4. Escolha sua conta do Azure Cosmos DB e selecione Data Explorer.

5. Expanda os nós TaskCollection, selecione o novo documento e confirme se o documento contém os valores de cadeia de caracteres de consulta, juntamente com alguns metadados adicionais.

   

Você adicionou com êxito uma associação ao gatilho HTTP para armazenar dados não estruturados em uma instância do Azure Cosmos DB.

Limpar os recursos

Nas etapas anteriores, você criou os recursos do Azure em um grupo de recursos. Se você não espera precisar desses recursos no futuro, poderá excluí-los ao excluir o grupo de recursos.

No menu do portal do Azure ou na Página inicial, selecione Grupos de recursos. Em seguida, na página Grupos de recursos, selecione myResourceGroup.

Na página myResourceGroup, certifique-se de que os recursos listados são aqueles que deseja excluir.

Selecione Excluir grupo de recursos, digite myResourceGroup na caixa de texto para confirmar e selecione Excluir.

Próximas etapas

Para saber mais sobre a associação a um banco de dados do Azure Cosmos DB, veja Associações do Azure Functions ao Azure Cosmos DB.

• Conceitos de gatilhos e de associações do Azure Functions
  Saiba como Functions se integra a outros serviços.
• Referência do desenvolvedor do Azure Functions
  Fornece informações mais técnicas sobre o runtime do Functions e uma referência para funções de codificação e definição de associações e gatilhos.
• Codificar e testar o Azure Functions localmente
  Descreve as opções para desenvolver suas funções localmente.