Criar uma função disparada pelo Azure Cosmos DBCreate a function triggered by Azure Cosmos DB

Saiba como criar uma função disparada quando dados são adicionados ou alterados no Azure Cosmos DB.Learn how to create a function triggered when data is added to or changed in 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.To learn more about Azure Cosmos DB, see Azure Cosmos DB: Serverless database computing using Azure Functions.

Exiba a mensagem nos logs.

Pré-requisitosPrerequisites

Para concluir este tutorial:To complete this tutorial:

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.If you don't have an Azure subscription, create a free account before you begin.

Observação

As associações do Azure Cosmos DB têm suporte apenas para usar com a API do SQL.Azure Cosmos DB bindings are only supported for use with the SQL API. Para todas as outras APIs do Azure Cosmos DB, você deve acessar o banco de dados por meio da sua função usando o cliente estático da API, incluindo a API do Azure Cosmos DB para MongoDB, a API do Cassandra, a API do Gremlin e a API de Tabela.For all other Azure Cosmos DB APIs, you should access the database from your function by using the static client for your API, including Azure Cosmos DB's API for MongoDB, Cassandra API, Gremlin API, and Table API.

Criar uma conta do Azure Cosmos DBCreate an Azure Cosmos DB account

Antes de criar o gatilho, você precisa ter uma conta do Azure Cosmos DB que use a API de SQL.You must have an Azure Cosmos DB account that uses the SQL API before you create the trigger.

  1. Entre no Portal do Azure.Sign in to the Azure portal.

  2. Selecione Criar um recurso > Bancos de dados > Azure Cosmos DB.Select Create a resource > Databases > Azure Cosmos DB.

    O painel Bancos de Dados do portal do Azure

  3. Na página Criar Conta do Azure Cosmos DB, insira as configurações básicas da nova conta do Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ConfiguraçãoSetting ValorValue DESCRIÇÃODescription
    SubscriptionSubscription Nome da assinaturaSubscription name Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Grupo de recursosResource Group Nome do grupo de recursosResource group name Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nome da contaAccount Name Um nome exclusivoA unique name Insira um nome para identificar a conta do Azure Cosmos.Enter a name to identify your Azure Cosmos account. Como documents.Azure.com é acrescentado à ID que você fornece para criar o URI, use uma ID exclusiva.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    A ID pode conter apenas letras minúsculas, números e o caractere de hífen (-).The ID can only contain lowercase letters, numbers, and the hyphen (-) character. Ela deve ter entre 3 e 31 caracteres.It must be between 3-31 characters in length.
    APIAPI O tipo de conta a ser criadaThe type of account to create Selecione Núcleo (SQL) para criar uma consulta e um banco de dados de documento usando a sintaxe SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    A API determina o tipo de conta a ser criada.The API determines the type of account to create. O Azure Cosmos DB fornece cinco APIs: Núcleo (SQL) e MongoDB para dados de documento, Gremlin para dados de grafo, Tabela do Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. No momento, você deve criar uma conta separada para cada API.Currently, you must create a separate account for each API.

    Saiba mais sobre a API do SQL.Learn more about the SQL API.
    LocationLocation A região mais próxima dos usuáriosThe region closest to your users Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.Use the location that is closest to your users to give them the fastest access to the data.

    A página da nova conta do Azure Cosmos DB

  4. Selecione Examinar + criar.Select Review + create. Você pode ignorar as seções Rede e Marcas.You can skip the Network and Tags sections.

  5. Examine as configurações da conta e selecione Criar.Review the account settings, and then select Create. São necessários alguns minutos para criar a conta.It takes a few minutes to create the account. Aguarde até que a página do portal exiba Sua implantação está concluída.Wait for the portal page to display Your deployment is complete.

    O painel Notificações do portal do Azure

  6. Selecione Ir para recurso para ir para a página da conta do Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    A página da conta do Azure Cosmos DB

Criar um Aplicativo de funções do AzureCreate an Azure Function app

  1. Selecione o botão Criar um recurso no canto superior esquerdo do portal do Azure e selecione Computação > Aplicativo de funções.Select the Create a resource button found on the upper left-hand corner of the Azure portal, then select Compute > Function App.

    Criar um aplicativo de funções no portal do Azure

  2. Use as configurações do aplicativo de funções especificadas na tabela abaixo da imagem.Use the function app settings as specified in the table below the image.

    Definir novas configurações do aplicativo de funções

    ConfiguraçãoSetting Valor sugeridoSuggested value DESCRIÇÃODescription
    Nome do aplicativoApp name Nome globalmente exclusivoGlobally unique name Nome que identifica seu novo aplicativo de funções.Name that identifies your new function app. Os caracteres válidos são a-z, 0-9 e -.Valid characters are a-z, 0-9, and -.
    AssinaturaSubscription Sua assinaturaYour subscription A assinatura na qual este novo aplicativo de funções será criado.The subscription under which this new function app is created.
    Grupo de RecursosResource Group myResourceGroupmyResourceGroup Nome do novo grupo de recursos no qual criar o seu aplicativo de funções.Name for the new resource group in which to create your function app.
    SOOS WindowsWindows As opções de linguagem disponíveis dependem do sistema operacional do aplicativo de funções.The language options available depend on the OS of the function app. Por exemplo, o Python requer o Linux.For example, Python requires Linux.
    Plano de hospedagemHosting plan Plano de consumoConsumption plan Plano de hospedagem que define como os recursos são alocados para seu aplicativo de funções.Hosting plan that defines how resources are allocated to your function app. No Plano de Consumo padrão, os recursos são adicionados dinamicamente conforme exigido por suas funções.In the default Consumption Plan, resources are added dynamically as required by your functions. Nesta hospedagem sem servidor, você só paga pelo tempo durante o qual suas funções são executadas.In this serverless hosting, you only pay for the time your functions run. Quando você executa em um Plano do Serviço de Aplicativo, deve gerenciar o dimensionamento do aplicativo de funções.When you run in an App Service plan, you must manage the scaling of your function app.
    LocalidadeLocation Europa OcidentalWest Europe Escolha uma região perto de você ou perto de outros serviços que suas funções acessam.Choose a region near you or near other services your functions access.
    Pilha de tempo de execuçãoRuntime stack Linguagem preferencialPreferred language Escolha um tempo de execução compatível com sua linguagem de programação de funções favorita.Choose a runtime that supports your favorite function programming language. Escolha .NET para funções C# e F#.Choose .NET for C# and F# functions.
    ArmazenamentoStorage Nome globalmente exclusivoGlobally unique name Crie uma conta de armazenamento usada pelo seu aplicativo de funções.Create a storage account used by your function app. Os nomes da conta de armazenamento devem ter entre 3 e 24 caracteres e podem conter apenas números e letras minúsculas.Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only. Você também pode usar uma conta existente, mas ela precisa atender aos requisitos da conta de armazenamento.You can also use an existing account, which must meets the storage account requirements.
    Application InsightsApplication Insights PadrãoDefault Cria um recurso do Application Insights do mesmo nome do aplicativo na região com suporte mais próxima.Creates an Application Insights resource of the same App name in the nearest supported region. Ao expandir essa configuração, você pode alterar o Novo nome do recurso ou escolher um Local diferente em uma geografia do Azure onde deseja armazenar seus dados.By expanding this setting, you can change the New resource name or choose a different Location in an Azure geography where you want to store your data.
  3. Selecione Criar para provisionar e implantar o aplicativo de funções.Select Create to provision and deploy the function app.

  4. Selecione o ícone da Notificação no canto superior direito do portal e veja se a mensagem Implantação concluída com êxito é exibida.Select the Notification icon in the upper-right corner of the portal and watch for the Deployment succeeded message.

    Definir novas configurações do aplicativo de funções

  5. Selecione Ir para recursos para exibir o novo aplicativo de funções.Select Go to resource to view your new function app. Você também pode selecionar Fixar no painel.You can also select Pin to dashboard. A fixação torna mais fácil retornar a esse recurso de aplicativo de função no seu painel.Pinning makes it easier to return to this function app resource from your dashboard.

Em seguida, crie uma nova função no novo aplicativo de funções.Next, you create a function in the new function app.

Criar gatilho do Azure Cosmos DBCreate Azure Cosmos DB trigger

  1. Expanda seu aplicativo de funções e clique no botão + ao lado de Functions.Expand your function app and click the + button next to Functions. Se essa for a primeira função em seu aplicativo de funções, selecione No portal e depois Continuar.If this is the first function in your function app, select In-portal then Continue. Caso contrário, vá para a etapa três.Otherwise, go to step three.

    Página de início rápido de funções no portal do Azure

  2. Escolha Mais modelos e, em seguida, Concluir e exibir modelos.Choose More templates then Finish and view templates.

    Início Rápido do Functions, escolher mais modelos

  3. No campo de pesquisa, digite cosmos e escolha o modelo Gatilho do Azure Cosmos DB.In the search field, type cosmos and then choose the Azure Cosmos DB trigger template.

  4. Se solicitado, selecione Instalar para instalar a extensão do Azure Cosmos DB no aplicativo de funções.If prompted, select Install to install the Azure Cosmos DB extension in the function app. Após a instalação ser bem-sucedida, selecione Continuar.After installation succeeds, select Continue.

    Instalar extensões de associação

  5. Configure o novo gatilho com as configurações conforme especificado na tabela abaixo da imagem.Configure the new trigger with the settings as specified in the table below the image.

    Criar a função acionada do Azure Cosmos DB

    ConfiguraçãoSetting Valor sugeridoSuggested value DescriçãoDescription
    NomeName PadrãoDefault Use o nome da função padrão sugerido pelo modelo.Use the default function name suggested by the template.
    Conexão de conta do Azure Cosmos DBAzure Cosmos DB account connection Nova configuraçãoNew setting Selecione Novo e depois escolha sua Assinatura, a Conta de banco de dados criada anteriormente e Selecionar.Select New, then choose your Subscription, the Database account you created earlier, and Select. Isso cria uma configuração de aplicativo para sua conexão de conta.This creates an application setting for your account connection. Essa configuração é usada pela associação para conexão com o banco de dados.This setting is used by the binding to connection to the database.
    Nome da coleçãoCollection name ItensItems Nome da coleção a ser monitorada.Name of collection to be monitored.
    Crie a coleção de concessão, se ela não existirCreate lease collection if it doesn't exist VerificadoChecked A coleção ainda não existe, então crie uma.The collection doesn't already exist, so create it.
    Nome do banco de dadosDatabase name TarefasTasks Nome do banco de dados com a coleção a ser monitorada.Name of database with the collection to be monitored.
  6. Clique em Criar para criar o banco de dados da função disparada do Azure Cosmos DB.Click Create to create your Azure Cosmos DB triggered function. Depois que a função for criada, o código de função baseado em modelo será exibido.After the function is created, the template-based function code is displayed.

    Modelo de função do Cosmos DB em C#

    Esse modelo de função grava o número de documentos e a primeira ID de documento para os logs.This function template writes the number of documents and the first document ID to the logs.

Em seguida, você conecta-se à sua conta do Azure Cosmos DB e cria a coleção Items no banco de dados Tasks.Next, you connect to your Azure Cosmos DB account and create the Items collection in the Tasks database.

Criar a coleção de itensCreate the Items collection

  1. Abra uma segunda instância do portal do Azure em uma nova guia no navegador.Open a second instance of the Azure portal in a new tab in the browser.

  2. No lado esquerdo do portal, expanda a barra de ícones, digite cosmos no campo de pesquisa e selecione Azure Cosmos DB.On the left side of the portal, expand the icon bar, type cosmos in the search field, and select Azure Cosmos DB.

    Pesquise o serviço do Azure Cosmos DB

  3. Escolha sua conta do Azure Cosmos DB e selecione o Data Explorer.Choose your Azure Cosmos DB account, then select the Data Explorer.

  4. Em Coleções, escolha taskDatabase e selecione Nova Coleção.In Collections, choose taskDatabase and select New Collection.

    Criar uma coleção

  5. Em Adicionar Coleção, use as configurações mostradas na tabela abaixo da imagem.In Add Collection, use the settings shown in the table below the image.

    Definir taskCollection

    ConfiguraçãoSetting Valor sugeridoSuggested value DESCRIÇÃODescription
    ID do banco de dadosDatabase ID TarefasTasks O nome do novo banco de dados.The name for your new database. Isso deve corresponder ao nome definido na sua associação de função.This must match the name defined in your function binding.
    ID da coleçãoCollection ID ItensItems O nome da nova coleção.The name for the new collection. Isso deve corresponder ao nome definido na sua associação de função.This must match the name defined in your function binding.
    Capacidade de armazenamentoStorage capacity Fixo (10 GB)Fixed (10 GB) Use o valor padrão.Use the default value. Esse valor é a capacidade de armazenamento do banco de dados.This value is the storage capacity of the database.
    Taxa de transferênciaThroughput 400 RU400 RU Use o valor padrão.Use the default value. Se quiser reduzir a latência, você poderá escalar verticalmente a taxa de transferência mais tarde.If you want to reduce latency, you can scale up the throughput later.
    Chave de partiçãoPartition key /category/category Uma chave de partição que distribui dados uniformemente para cada partição.A partition key that distributes data evenly to each partition. É importante selecionar a chave de partição correta ao criar uma coleção de alto desempenho.Selecting the correct partition key is important in creating a performant collection.
  6. Clique em OK para criar a coleção Itens.Click OK to create the Items collection. Pode levar alguns instantes para a coleção ser criada.It may take a short time for the collection to get created.

Depois que a coleção especificada na associação de função existir, você poderá testar a função adicionando documentos a essa nova coleção.After the collection specified in the function binding exists, you can test the function by adding documents to this new collection.

Testar a funçãoTest the function

  1. Expanda a nova coleção taskCollection no Data Explorer, escolha Documentos e, em seguida, selecione Novo Documento.Expand the new taskCollection collection in Data Explorer, choose Documents, then select New Document.

    Criar um documento em taskCollection

  2. Substitua o conteúdo do novo documento pelo conteúdo a seguir e então escolha Salvar.Replace the contents of the new document with the following content, then choose Save.

     {
         "id": "task1",
         "category": "general",
         "description": "some task"
     }
    
  3. Mude para a primeira guia do navegador que contém a função no portal.Switch to the first browser tab that contains your function in the portal. Expanda os logs de função e verifique se o novo documento disparou a função.Expand the function logs and verify that the new document has triggered the function. Veja se o valor de ID do documento task1 é gravado nos logs.See that the task1 document ID value is written to the logs.

    Exiba a mensagem nos logs.

  4. (Opcional) Volte para o seu documento, faça uma alteração e, em seguida, clique em Atualizar.(Optional) Go back to your document, make a change, and click Update. Em seguida, volte para os logs de função e verifique se a atualização também disparou a função.Then, go back to the function logs and verify that the update has also triggered the function.

Limpar recursosClean up resources

Outros inícios rápidos nessa coleção aproveitam esse início rápido.Other quick starts in this collection build upon this quick start. Se você planeja trabalhar com inícios rápidos subsequentes, tutoriais ou com qualquer serviço criado por você nesse início rápido, não limpe os recursos.If you plan to work with subsequent quick starts, tutorials, or with any of the services you have created in this quick start, do not clean up the resources.

Os Recursos no Azure se referem a aplicativos de funções, funções, contas de armazenamento e assim por diante.Resources in Azure refers to function apps, functions, storage accounts, and so forth. Eles são agrupados em grupos de recursos, e você pode excluir tudo junto ao excluir o grupo.They are grouped into resource groups, and you can delete everything in a group by deleting the group.

Você criou recursos para concluir esses guias de início rápido.You created resources to complete these quickstarts. Você pode ser cobrado por esses recursos, dependendo do status de conta e preços do serviço.You may be billed for these resources, depending on your account status and service pricing. Caso não precise mais dos recursos, é possível excluí-los desta maneira:If you don't need the resources anymore, here's how to delete them:

  1. No portal do Azure, vá até a página Grupo de recursos.In the Azure portal, go to the Resource group page.

    Para ir até essa página a partir da página de aplicativo de funções, selecione a guia Visão geral e depois selecione o link em Grupo de recursos.To get to that page from the function app page, select the Overview tab and then select the link under Resource group.

    Selecione o grupo de recursos para excluir a partir da página do aplicativo de funções.

    Para ir até essa página a partir do painel, selecione Grupos de recursos e depois selecione o grupo de recursos que você usou para esse guia de início rápido.To get to that page from the dashboard, select Resource groups, and then select the resource group that you used for this quickstart.

  2. Na página Grupo de recursos, examine a lista de recursos incluídos e verifique se eles são aqueles que deseja excluir.In the Resource group page, review the list of included resources, and verify that they are the ones you want to delete.

  3. Selecione Excluir grupo de recursos e siga as instruções.Select Delete resource group, and follow the instructions.

    A exclusão poderá levar alguns minutos.Deletion may take a couple of minutes. Ao ser concluída, uma notificação será exibida por alguns segundos.When it's done, a notification appears for a few seconds. Também é possível selecionar o ícone de sino na parte superior da página para exibir a notificação.You can also select the bell icon at the top of the page to view the notification.

Próximas etapasNext steps

Você criou uma função que é executada quando um documento é adicionado ou modificado no Azure Cosmos DB.You have created a function that runs when a document is added or modified in your Azure Cosmos DB. Para obter mais informações sobre gatilhos do Azure Cosmos DB, consulte Associações do Azure Cosmos DB para Azure Functions.For more information about Azure Cosmos DB triggers, see Azure Cosmos DB bindings for Azure Functions.

Agora que você criou sua primeira função, vamos adicionar uma associação de saída à função que grava uma mensagem na fila Armazenamento.Now that you have created your first function, let's add an output binding to the function that writes a message to a Storage queue.