Armazenar dados não estruturados usando as funções do Azure e o Azure Cosmos DB

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

Nota

Neste momento, o acionador do Azure Cosmos DB, os enlaces de entrada e os enlaces de saída funcionam apenas com contas de API do SQL e do Graph API.

Nas Funções do Azure, os enlaces de entrada e saída proporcionam uma forma declarativa para ligar aos dados do serviço externo a partir da sua função. Neste artigo, saiba como atualizar uma função existente para adicionar um enlace de saída que armazena dados não estruturados num documento do Azure Cosmos DB.

Pré-requisitos

Para concluir este tutorial:

Este artigo usa como ponto de partida os recursos criados em Criar sua primeira função no portal do Azure. Se ainda não o fez, conclua estes passos agora para criar a sua aplicação de funções.

Criar uma conta do Azure Cosmos DB

Tem de ter uma conta do Azure Cosmos DB que utilize a API SQL antes de criar o enlace de saída.

1. A partir do menu do portal do Azure ou a partir da Home page, selecione Criar um recurso.

2. Procure o 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 para NoSQL.

   O Azure Cosmos DB fornece várias APIs:

   • NoSQL, para dados de documentos
   • PostgreSQL
   • MongoDB, para dados de documentos
   • Apache Cassandra
   • Tabela
   • Apache Gremlin, para dados gráficos

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

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

   Definição	valor	Description
   Subscrição	Nome da subscrição	Selecione a subscrição do Azure que pretende utilizar para esta conta do Azure Cosmos DB.
   Grupo de Recursos	Nome do grupo de recursos	Selecione um grupo de recursos ou selecione Criar novo e, em seguida, introduza um nome exclusivo para o novo grupo de recursos.
   Nome da Conta	Um nome exclusivo	Insira um nome para identificar sua conta do Azure Cosmos DB. Uma vez que documents.azure.com é anexado ao nome que indicar para criar o URI, utilize um nome exclusivo. O nome pode conter apenas letras minúsculas, números e o caractere hífen (-). Deve ter de 3 a 44 caracteres.
   Location	A região mais próxima dos seus utilizadores	Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o 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 de taxa de transferência provisionada. Selecione Serverless para criar uma conta no modo serverless .
   Aplicar desconto de nível gratuito do Azure Cosmos DB	Candidatar-se ou Não aplicar	Com o nível gratuito do Azure Cosmos DB, você obtém os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente 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 de taxa de transferência que pode ser provisionada nessa conta. Esse limite evita cobranças inesperadas relacionadas à 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 optar por participar ao criar a conta. Se você não vir a opção de aplicar o desconto de nível gratuito, outra conta na assinatura já foi habilitada com o nível gratuito.

   

   Nota

   As seguintes opções não estarão disponíveis se você selecionar Serverless como o modo de Capacidade:

   • Aplicar Desconto de Escalão Gratuito
   • Limitar a taxa de transferência total da conta

5. Na guia Distribuição Global, configure os seguintes detalhes. Você pode deixar os valores padrão para este início rápido:

   Definição	valor	Description
   Georredundância	Desativar	Habilite ou desative a distribuição global em sua conta emparelhando sua região com uma região par. Pode adicionar mais regiões à sua conta mais tarde.
   Escritas de várias regiões	Desativar	O recurso de gravação em 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 Disponibilidade	Desativar	As zonas de disponibilidade ajudam a melhorar ainda mais a disponibilidade e a resiliência do seu aplicativo.

   Nota

   As opções a seguir não estarão disponíveis se você selecionar Serverless como o modo de capacidade na página Noções básicas anterior:

   • Georredundância
   • Escritas 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 a política de backup periódico ou contínuo .
   • Encriptação. Use uma chave gerenciada pelo serviço ou uma chave gerenciada pelo cliente.
   • Etiquetas. As etiquetas são pares nome/valor que permitem categorizar recursos e ver faturação consolidada aplicando a mesma etiqueta a múltiplos recursos e grupos de recursos.

7. Selecione Rever + criar.

8. Reveja as definições da conta e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde até que a página do portal apresente A implementação está concluída.

   

9. Selecione Ir para recurso para aceder à página da conta do Azure Cosmos DB.

   

Adicionar um enlace de saída

1. No portal do Azure, navegue até o aplicativo de função criado anteriormente e selecione-o.

2. Selecione Funções e, em seguida, selecione a função HttpTrigger.

   

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

   

4. Use as configurações Criar saída conforme especificado na tabela:

   

   Definição	Valor sugerido	Description
   Tipo de vinculação	Azure Cosmos DB	Nome do tipo de associação a ser selecionado para criar a associação de saída para o Azure Cosmos DB.
   Nome do parâmetro do documento	taskDocument	Nome que se refere ao objeto do Azure Cosmos DB no código.
   Nome da base de dados	taskDatabase	Nome da base de dados para guardar os documentos.
   Nome da coleção	taskCollection	Nome da coleção da base de dados.
   Se verdadeiro, cria o banco de dados e a coleção do Azure Cosmos DB	Sim	A coleção ainda não existe, como tal, deve ser criada.
   Ligação de conta do Azure Cosmos DB	Nova definição	Selecione Novo, escolha Conta do Azure Cosmos DB e a conta de Banco de Dados criada anteriormente e selecione OK. Cria uma definição da aplicação para a sua ligação de conta. Esta definição é utilizada pelo enlace para a ligação à base de dados.

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

Atualizar o código da função

Substitua o código da função existente pelo seguinte código no idioma à sua escolha:

C#

Substitua a função C# existente pelo seguinte código:

#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();
    }
}

JavaScript

Substitua a função JavaScript existente pelo seguinte código:

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."
        };
    }
};

Este exemplo de código lê as cadeias de consulta do Pedido de HTTP e atribui-as a campos no objeto taskDocument. O enlace taskDocument envia os dados do objeto deste parâmetro de enlace para serem armazenados na base de dados de documentos vinculada. A base de dados é criada quando a função for executada pela primeira vez.

Testar a função e a base 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 foi retornado.

   

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

   

4. Escolha a sua conta do Azure Cosmos DB e, em seguida, selecione Explorador de Dados.

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

   

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

Clean up resources (Limpar recursos)

Nos passos anteriores, criou os recursos do Azure num grupo de recursos. Se provavelmente não necessitar desses recursos no futuro, pode eliminá-los ao eliminar 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 você deseja excluir.

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

Próximos passos

Para obter mais informações sobre a associação a uma instância do Azure Cosmos DB, consulte Azure Functions Azure Cosmos DB bindings.

• Conceitos dos acionadores e dos enlaces das Funções do Azure
  Saiba como o Functions se integra com outros serviços.
• Referência para programadores das Funções do Azure
  Fornece mais informações técnicas sobre o tempo de execução de funções e uma referência para funções de codificação e definição de gatilhos e associações.
• Criar código e testar as Funções do Azure localmente
  Descreve as opções para desenvolver suas funções localmente.