Criar uma função disparada pelo Azure Cosmos DB

  • Artigo

Saiba como criar uma função no portal do Azure que é acionada quando os dados são adicionados ou alterados no Azure Cosmos DB. Para saber mais sobre o Azure Cosmos DB, confira Azure Cosmos DB: computação de banco de dados sem servidor usando o Azure Functions.

Observação

A edição no portal só tem suporte para funções JavaScript, PowerShell e C# Script. A edição no portal do Python é suportada somente quando executada no plano de Consumo. Quando possível, você deve desenvolver suas funções localmente.

Para saber mais sobre as limitações na edição do código de função no portal do Azure, consulte Limitações de desenvolvimento no portal do Azure.

Pré-requisitos

Para concluir este tutorial:

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Observação

Só há suporte para uso das associações do Azure Cosmos DB com o Azure Cosmos DB for NoSQL. O suporte para o Azure Cosmos DB for Table é fornecido por meio das associações de armazenamento de Tabela, começando com a extensão 5.x. Para todas as outras APIs do Azure Cosmos DB, você deve acessar o banco de dados da sua função usando o cliente estático da API, incluindo o Azure Cosmos DB for MongoDB, o Azure Cosmos DB for Cassandra e o Azure Cosmos DB for Apache Gremlin.

Entrar no Azure

Entre no portal do Azure com sua conta do Azure.

Criar uma conta do Azure Cosmos DB

Antes de criar o gatilho, 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.

    Screenshot shows the Create Azure Cosmos DB Account page.

    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.

    Screenshot shows that your deployment is complete.

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

    Screenshot shows the Azure Cosmos DB account page.

Criar um aplicativo de funções no Azure

  1. No menu do portal do Azure ou na Página inicial, selecione Criar um recurso.

  2. Na página Novo, selecione Computação>Aplicativo de Funções.

  3. Na página Informações básicas, use as configurações do aplicativo de funções conforme especificado na seguinte tabela:

    Configuração Valor sugerido Descrição
    Assinatura Sua assinatura A assinatura sob a qual você cria seu novo aplicativo de funções.
    Grupo de Recursos myResourceGroup Nome do novo grupo de recursos no qual você cria o aplicativo de funções. Você deve criar um novo grupo de recursos porque há limitações conhecidas ao criar novos aplicativos de funções em um grupo de recursos existente.
    Nome do aplicativo de funções Nome globalmente exclusivo Nome que identifica seu novo aplicativo de funções. Os caracteres válidos são a-z (não diferencia maiúsculas de minúsculas), 0-9 e -.
    Deseja implantar código ou imagem de contêiner? Código Opção para publicar arquivos de código ou um contêiner do Docker.
    Pilha de runtime Linguagem preferencial Escolha um runtime compatível com sua linguagem de programação de funções favorita. A edição no portal só está disponível para scripts JavaScript, PowerShell, Python v1, TypeScript e C#. A biblioteca de classes C# e as funções Java devem ser desenvolvidas localmente.
    Versão Número de versão Escolha a versão do seu runtime instalado.
    Região Região preferencial Selecione uma região perto de você ou perto de outros serviços que suas funções podem acessar.
    Sistema operacional Windows Um sistema operacional é pré-selecionado para você com base na seleção da pilha de runtime, mas você pode alterar a configuração, se necessário. Só há suporte para edição no portal no Windows. A publicação de contêiner só tem suporte no Linux.
    Opções e planos de hospedagem Consumo (Sem servidor) Plano de hospedagem que define como os recursos são alocados para seu aplicativo de funções. No plano Consumo padrão, os recursos são adicionados dinamicamente conforme exigido por suas funções. Nesta hospedagem sem servidor, você paga somente pelo tempo durante o qual suas funções são executadas. O plano Premium também oferece colocação em escala dinâmica. Quando você executa em um Plano do Serviço de Aplicativo, deve gerenciar o dimensionamento do aplicativo de funções.

  4. Aceite as opções padrão de criação de uma nova conta de armazenamento na guia Armazenamento e uma nova instância do Application Insights na guia Monitoramento. Você também pode optar por usar uma conta de armazenamento existente ou uma instância do Application Insights.

  5. Selecione Examinar + criar para examinar as configurações do aplicativo escolhidas e selecione Criar para provisionar e implantar o aplicativo de funções.

  6. Selecione o ícone Notificações no canto superior direito do portal e veja se a mensagem Implantação concluída com êxito é exibida.

  7. Selecione Ir para recursos para exibir o novo aplicativo de funções. Você também pode selecionar Fixar no painel. A fixação torna mais fácil retornar a esse recurso de aplicativo de função no seu painel.

    Screenshot of deployment notification.

Em seguida, crie uma nova função no novo aplicativo de funções.

Criar gatilho do Azure Cosmos DB

  1. Na sua aplicação de função, selecione Descrição Geral e, em seguida, selecione + Criar em Funções.

  2. Em Selecionar um modelo, role para baixo e escolha o modelo de gatilho do Azure Cosmos DB.

  3. Em Detalhes do modelo, configure o novo gatilho com as configurações especificadas nesta tabela e selecione Criar:

    Configuração Valor sugerido Descrição
    Nova função Aceite o nome padrão O nome da função.
    Conexão de conta do Azure Cosmos DB Aceite o nome do novo padrão Selecione Novo, a Conta de Banco de Dados criada anteriormente e depois OK. Essa ação 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.
    Nome do banco de dados Tarefas Nome do banco de dados que inclui a coleção a ser monitorada.
    Nome da coleção Itens O nome da coleção a ser monitorada.
    Nome da coleção para concessões concessões O nome da coleção para armazenar as concessões.
    Criar coleção de concessões se ela não existir Sim Verifica a existência da coleção de concessões e cria-a automaticamente.

    O Azure cria a função acionada do Azure Cosmos DB com base nos valores fornecidos.

  4. Para exibir o código de função baseado em modelo, selecione Código + Teste.

    Azure Cosmos DB function template in C#

    Esse modelo de função grava o número de documentos e a primeira ID de documento para os logs.

Em seguida, você se conecta à sua conta do Azure Cosmos DB e cria o contêiner Items no banco de dados Tasks.

Criar o contêiner Itens

  1. Abra uma segunda instância do portal do Azure em uma nova guia no navegador.

  2. No lado esquerdo do portal, expanda a barra de ícones, digite cosmos no campo de pesquisa e selecione cosmos.

    Search for the Azure Cosmos DB service

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

  4. Em API SQL, escolha o banco de dados Tarefas e selecione Novo Contêiner.

    Create a container

  5. Em Adicionar Contêiner, use as configurações mostradas na tabela embaixo da imagem.

    Define the Tasks container

    Configuração Valor sugerido Descrição
    ID do banco de dados Tarefas O nome do novo banco de dados. Isso deve corresponder ao nome definido na sua associação de função.
    ID do contêiner Itens O nome do novo contêiner. Isso deve corresponder ao nome definido na sua associação de função.
    Chave de partição /category Uma chave de partição que distribui dados uniformemente para cada partição. É importante selecionar a chave de partição correta ao criar um contêiner de alto desempenho.
    Taxa de transferência 400 RU Use o valor padrão. Se quiser reduzir a latência, você poderá escalar verticalmente a taxa de transferência mais tarde.

  6. Clique em OK para criar o contêiner Itens. Pode levar alguns instantes para o contêiner ser criado.

Depois que o contêiner especificado na associação de função existir, você poderá testar a função adicionando itens a esse novo contêiner.

Testar a função

  1. Expanda o novo contêiner Itens no Data Explorer, escolha Itens e selecione Novo Item.

    Create an item in Items container

  2. Substitua o conteúdo do novo item pelo conteúdo a seguir e então escolha Salvar.

    {
    "id": "task1",
    "category": "general",
    "description": "some task"
}

  3. Mude para a primeira guia do navegador que contém a função no portal. Expanda os logs de função e verifique se o novo documento disparou a função. Veja se o valor de ID do documento task1 é gravado nos logs.

    View message in the logs.

  4. (Opcional) Volte para o seu documento, faça uma alteração e, em seguida, clique em Atualizar. Em seguida, volte para os logs de função e verifique se a atualização também disparou a função.

Limpar os recursos

Outros inícios rápidos nessa coleção aproveitam esse início rápido. Se você planeja trabalhar com guias de início rápido subsequentes, tutoriais ou com qualquer serviço criado por você nesse início rápido, não limpe os recursos.

Os Recursos no Azure 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. Esses recursos podem ser cobrados, dependendo do status da sua conta e do preço do serviço. Caso não precise mais dos recursos, é possível excluí-los desta maneira:

  1. No portal do Azure, vá até a página Grupo de recursos.

    Para acessar essa página por meio da página de aplicativo de funções, selecione a guia Visão geral e o link em Grupo de recursos.

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

    Para acessar essa página no painel, selecione Grupos de recursos, depois o grupo de recursos usado para este artigo.

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

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

    A exclusão pode 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ê criou uma função que é executada quando um documento é adicionado ou modificado no Azure Cosmos DB. Para obter mais informações sobre gatilhos do Azure Cosmos DB, consulte Associações do Azure Cosmos DB para Azure Functions.

Agora que você criou sua primeira função, vamos adicionar uma associação de saída à função, que grava uma mensagem em uma fila do Armazenamento.

Adicionar mensagens a uma fila do Armazenamento do Azure usando o Functions