Criar gatilhos com o Firestore

Este guia aborda as instruções para criar acionadores para serviços e funções do Cloud Run a partir de eventos do Firestore.

É possível configurar os serviços do Cloud Run para serem acionados por eventos em um banco de dados do Firestore. Quando acionado, o serviço lê e atualiza um banco de dados do Firestore em resposta a esses eventos usando as APIs do Firestore e as bibliotecas de cliente.

Em um ciclo de vida típico, o seguinte acontece quando um serviço do Cloud Run é acionado por eventos do Firestore:

  1. O serviço aguarda mudanças em um documento específico.

  2. Quando uma mudança ocorre, o serviço é acionado e realiza as tarefas dele.

  3. O serviço recebe um objeto de dados com um snapshot do documento afetado. Para eventos write ou update, o objeto de dados contém snapshots que representam o estado do documento antes e depois do evento acionador.

Tipos de evento

O Firestore oferece suporte aos eventos create, update, delete e write. O evento write engloba todas as modificações em um documento.

Tipo de evento Gatilho
google.cloud.firestore.document.v1.created (padrão) Acionado quando um documento é gravado pela primeira vez.
google.cloud.firestore.document.v1.updated Acionado quando um documento já existe e tem algum valor alterado.
google.cloud.firestore.document.v1.deleted Acionado quando um documento com dados é excluído.
google.cloud.firestore.document.v1.written Acionado quando um documento é criado, atualizado ou excluído.

Os caracteres curinga são escritos em gatilhos usando chaves, por exemplo: projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

Especificar o caminho do documento

Para acionar seu serviço, especifique um caminho de documento para detectar. O caminho do documento precisa estar no mesmo projeto do Google Cloud que o serviço.

Confira a seguir alguns exemplos de caminhos de documentos válidos:

  • users/marie: gatilho válido. Monitora um único documento, /users/marie.

  • users/{username}: gatilho válido. Monitora todos os documentos do usuário. Caracteres curingas são usados para monitorar todos os documentos na coleção.

  • users/{username}/addresses: gatilho inválido. Refere-se à subcoleção addresses, não a um documento.

  • users/{username}/addresses/home: gatilho válido. Monitora o documento de endereço residencial de todos os usuários.

  • users/{username}/addresses/{addressId}: gatilho válido. Monitora todos os documentos de endereço.

  • users/{user=**}: gatilho válido. Monitora todos os documentos do usuário e quaisquer documentos em subcoleções em cada documento do usuário, como /users/userID/address/home ou /users/userID/phone/work.

Caracteres curinga e parâmetros

Se você não souber o documento específico que quer monitorar, use um {wildcard} em vez do ID do documento:

  • users/{username} detecta alterações feitas em todos os documentos do usuário.

Neste exemplo, quando qualquer campo em qualquer documento em users é alterado, ele corresponde a um caractere curinga chamado {username}.

Se um documento em users tiver subcoleções e um campo em um dos documentos dessas subcoleções for alterado, o caractere curinga {username} não será acionado. Se o objetivo é responder a eventos em subcoleções também, use o caractere curinga de vários segmentos {username=**}.

As correspondências de caractere curinga são extraídas dos caminhos do documento. Defina quantos caracteres curinga você quiser para substituir a coleção explícita ou os IDs dos documentos. É possível usar até um caractere curinga de vários segmentos, como {username=**}.

Estruturas de eventos

Esse acionador invoca seu serviço com um evento semelhante a este: 

{
    "oldValue": { // Update and Delete operations only
        A Document object containing a pre-operation document snapshot
    },
    "updateMask": { // Update operations only
        A DocumentMask object that lists changed fields.
    },
    "value": {
        // A Document object containing a post-operation document snapshot
    }
}

Cada objeto Document contém um ou mais objetos Value. Consulte a documentação Value para referências de tipo.

Antes de começar

  1. Verifique se você configurou um novo projeto para o Cloud Run conforme descrito na página de configuração.

  2. Ative as APIs Artifact Registry, Cloud Build, Cloud Run Admin, Eventarc, Firestore Cloud Logging e Pub/Sub:

    Ativar as APIs

Funções exigidas

  1. Se você for o criador do projeto, receberá o papel de proprietário básico (roles/owner). Por padrão, esse papel do gerenciamento de identidade e acesso (IAM) inclui as permissões necessárias para acesso total à maioria dos recursos do Google Cloud, e você pode pular esta etapa.

    Se você não é o criador do projeto, as permissões necessárias precisam ser concedidas ao principal apropriado. Por exemplo, um principal pode ser uma Conta do Google (para usuários finais) ou uma conta de serviço (para aplicativos e cargas de trabalho de computação). Para mais informações, consulte a página Papéis e permissões do destino do evento.

    Observe que, por padrão, as permissões do Cloud Build incluem permissões para upload e download de artefatos do Artifact Registry.

    Permissões necessárias

    Para receber as permissões necessárias para configurar gatilhos do Firestore, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

  2. Anote as propriedades da conta de serviço padrão do Compute Engine, porque você vai anexá-la a um gatilho do Eventarc para representar a identidade do acionador para fins de teste. Essa conta de serviço é criada automaticamente depois de ativar ou usar um serviço do Google Cloud que usa o Compute Engine e com o seguinte formato de e-mail:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua PROJECT_NUMBER pelo número do projeto do Google Cloud. Encontre o número do projeto na página Boas-vindas do console do Google Cloud ou executando o seguinte comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Para ambientes de produção, é altamente recomendável criar uma nova conta de serviço, conceder a ela um ou mais papéis do IAM que contenham as permissões mínimas necessárias, bem como seguir o princípio de privilégio mínimo.

  3. Por padrão, os serviços do Cloud Run só podem ser chamados por proprietários do projeto, editores do projeto e administradores e invocadores do Cloud Run. É possível controlar o acesso por serviço. No entanto, para fins de teste, conceda o papel de chamador do Cloud Run (run.invoker) no projeto do Google Cloud à conta de serviço do Compute Engine. Isso concede o papel em todos os serviços e jobs do Cloud Run em um projeto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Se você criar um gatilho para um serviço autenticado do Cloud Run sem conceder o papel de chamador do Cloud Run, o gatilho será criado com sucesso e estará ativo. No entanto, o acionador não funcionará conforme o esperado e uma mensagem semelhante à seguinte aparecerá nos registros:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  4. Conceda o papel de receptor de eventos do Eventarc (roles/eventarc.eventReceiver) no projeto à conta de serviço padrão do Compute Engine para que o gatilho do Eventarc possa receber eventos de provedores de eventos. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
  5. Se você ativou o agente de serviço do Cloud Pub/Sub até 8 de abril de 2021, para oferecer compatibilidade com solicitações push autenticadas do Pub/Sub, conceda o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente de serviço. Caso contrário, esse papel é concedido por padrão: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Configurar o banco de dados do Firestore

Antes de implantar o serviço, é preciso criar um banco de dados do Firestore:

  1. Acesse a página de dados do Firestore.

  2. Selecione Criar banco de dados.

  3. Clique em Modo nativo e selecione Continuar.

  4. No campo Nome do banco de dados, insira um ID do banco de dados, como firestore-db.

  5. Em Tipo de local, selecione Região e escolha a região em que o banco de dados vai ficar. Essa opção é permanente.

  6. Deixe a seção Regras de segurança como está.

  7. Clique em Criar banco de dados.

O modelo de dados do Firestore consiste em coleções que contêm documentos. Cada documento contém um conjunto de pares de chave-valor.

Criar acionadores

Dependendo do tipo de serviço que você está implantando, é possível:

Criar um gatilho para serviços

É possível especificar um acionador depois de implantar um serviço.

Clique na guia para ver instruções usando a ferramenta de sua preferência.

Console

  1. Implante seu serviço do Cloud Run usando contêineres ou a origem.

  2. No console do Google Cloud, acesse o Cloud Run:

    Acesse o Cloud Run

  3. Na lista de serviços, clique em um serviço atual.

  4. Na página "Detalhes do serviço", navegue até a guia Acionadores.

  5. Clique em Adicionar gatilho e selecione Gatilho do Firestore.

  6. No painel Gatilho do Eventarc, modifique os detalhes do gatilho da seguinte maneira:

    1. No campo Nome do gatilho, digite um nome ou use o nome padrão.

    2. Selecione um Tipo de acionador na lista para especificar um dos seguintes tipos de acionador:

      • Fontes do Google para especificar acionadores para Pub/Sub, Cloud Storage, Firestore, e outros provedores de eventos do Google.

      • Terceiros para integração com provedores que não são do Google que oferecem uma origem do Eventarc. Para mais informações, consulte Eventos de terceiros no Eventarc.

    3. Selecione Firestore na lista Provedor de eventos para selecionar um produto que ofereça o tipo de evento para acionar seu serviço. Para ver a lista de provedores de eventos, consulte Provedores e destinos de eventos.

    4. Selecione type=google.cloud.firestore.document.v1.created na lista Tipo de evento. A configuração do gatilho varia de acordo com o tipo de evento compatível: Para mais informações, consulte Tipos de eventos.

    5. Na seção "Filtros", selecione um banco de dados, uma operação e valores de atributo ou use as seleções padrão.

    6. Se o campo Região estiver ativado, selecione um local para o acionador do Eventarc. Em geral, o local de um acionador do Eventarc precisa corresponder ao local do recurso do Google Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar o serviço na mesma região. Consulte Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de acionador do Eventarc.

    7. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar seu serviço. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar o serviço. Por padrão, o Cloud Run usa a conta de serviço padrão do Compute Engine.

    8. Se quiser, especifique o caminho do URL do serviço para enviar a solicitação recebida. Esse é o caminho relativo no serviço de destino para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route e route/subroute.

    9. Depois de preencher os campos obrigatórios, clique em Salvar gatilho.

  7. Depois de criar o gatilho, verifique a integridade garantindo que haja uma marca de seleção na guia Gatilhos.

gcloud

  1. Implante seu serviço do Cloud Run usando contêineres ou a origem.

  2. Execute o comando a seguir para criar um acionador que filtra eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua:

    • TRIGGER_NAME pelo nome do gatilho.

    • EVENTARC_TRIGGER_LOCATION com o local do gatilho do Eventarc. Em geral, o local de um acionador do Eventarc precisa corresponder ao local do recurso do Google Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar o serviço na mesma região. Saiba mais em Locais do Eventarc.

    • SERVICE pelo nome do serviço que você está implantando.

    • REGION pela região do Cloud Run do serviço.

    • PROJECT_NUMBER pelo número do projeto do Google Cloud. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar seu serviço. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar o serviço. Por padrão, o Cloud Run usa a conta de serviço de computação padrão.

    • A flag event-filters especifica os filtros de evento que o acionador monitora. Um evento que corresponde a todos os filtros de event-filters aciona chamadas para seu serviço. Cada acionador precisa ter um tipo de evento compatível. Não é possível mudar o tipo de filtro de evento após a criação. Para mudar o tipo de filtro de evento, crie um novo gatilho e exclua o antigo. Opcionalmente, é possível repetir a flag --event-filters com um filtro compatível no formato ATTRIBUTE=VALUE para adicionar mais filtros.

Criar um acionador para funções

Clique na guia para ver instruções usando a ferramenta de sua preferência.

Console

Ao usar o console do Google Cloud para criar uma função, você também pode adicionar um acionador a ela. Siga estas etapas para criar um acionador para sua função:

  1. No console do Google Cloud, acesse o Cloud Run:

    Acessar o Cloud Run

  2. Clique em Escrever uma função e insira os detalhes da função. Para mais informações sobre como configurar funções durante a implantação, consulte Implantar funções.

  3. Na seção Gatilho, clique em Adicionar gatilho.

  4. Selecione Gatilho do Firestore.

  5. No painel Gatilho do Eventarc, modifique os detalhes do gatilho da seguinte maneira:

    1. Insira um nome para o acionador no campo Nome do acionador ou use o nome padrão.

    2. Selecione um Tipo de acionador na lista para especificar um dos seguintes tipos de acionador:

      • Fontes do Google para especificar acionadores para Pub/Sub, Cloud Storage, Firestore, e outros provedores de eventos do Google.

      • Terceiros para integração com provedores que não são do Google que oferecem uma origem do Eventarc. Para mais informações, consulte Eventos de terceiros no Eventarc.

    3. Selecione Firestore na lista Provedor de eventos para selecionar um produto que ofereça o tipo de evento para acionar sua função. Para ver a lista de provedores de eventos, consulte Provedores e destinos de eventos.

    4. Selecione type=google.cloud.firestore.document.v1.created na lista Tipo de evento. A configuração do gatilho varia de acordo com o tipo de evento compatível: Para mais informações, consulte Tipos de eventos.

    5. Na seção "Filtros", selecione um banco de dados, uma operação e valores de atributo ou use as seleções padrão.

    6. Se o campo Região estiver ativado, selecione um local para o acionador do Eventarc. Em geral, o local de um acionador do Eventarc precisa corresponder ao local do recurso do Google Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar a função na mesma região. Consulte Noções básicas sobre locais do Eventarc para mais detalhes sobre locais de acionador do Eventarc.

    7. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar a função. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar a função. Por padrão, o Cloud Run usa a conta de serviço padrão do Compute Engine.

    8. Se quiser, especifique o caminho do URL do serviço para enviar a solicitação recebida. Esse é o caminho relativo no serviço de destino para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route e route/subroute.

  6. Depois de preencher os campos obrigatórios, clique em Salvar gatilho.

gcloud

Ao criar uma função usando a CLI gcloud, primeiro é preciso deploy a função e, em seguida, criar um gatilho. Siga estas etapas para criar um acionador para sua função:

  1. Execute o seguinte comando no diretório que contém o exemplo de código para implantar a função:

    gcloud beta run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION

    Substitua:

    • FUNCTION pelo nome da função que você está implantando. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome, se você omiti-lo.

    • FUNCTION_ENTRYPOINT: o ponto de entrada da função no código-fonte. Esse é o código que o Cloud Run executa quando é executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte.

    • BASE_IMAGE_ID com o ambiente de imagem base da sua função. Para mais detalhes sobre as imagens de base e os pacotes incluídos em cada imagem, consulte Imagens de base dos ambientes de execução.

    • REGION com o Google Cloud região onde você quer implantar sua função. Por exemplo, us-central1.

  2. Execute o comando a seguir para criar um acionador que filtra eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua:

    • TRIGGER_NAME pelo nome do gatilho.

    • EVENTARC_TRIGGER_LOCATION com o local do gatilho do Eventarc. Em geral, o local de um acionador do Eventarc precisa corresponder ao local do recurso do Google Cloud que você quer monitorar para eventos. Na maioria dos cenários, você também precisa implantar a função na mesma região. Saiba mais em Locais do Eventarc.

    • FUNCTION pelo nome da função que você está implantando.

    • REGION pela região do Cloud Run da função.

    • PROJECT_NUMBER pelo número do projeto do Google Cloud. Os acionadores do Eventarc são vinculados a contas de serviço para usar como uma identidade ao invocar a função. A conta de serviço do acionador do Eventarc precisa ter permissão para invocar a função. Por padrão, o Cloud Run usa a conta de serviço de computação padrão.

    • A flag event-filters especifica os filtros de evento que o acionador monitora. Um evento que corresponde a todos os filtros de event-filters aciona chamadas para sua função. Cada acionador precisa ter um tipo de evento compatível. Não é possível mudar o tipo de filtro de evento após a criação. Para mudar o tipo de filtro de evento, crie um novo gatilho e exclua o antigo. Opcionalmente, é possível repetir a flag --event-filters com um filtro compatível no formato ATTRIBUTE=VALUE para adicionar mais filtros.

A seguir

  • Confira exemplos de funções que são acionadas quando você faz alterações em um documento dentro de uma coleção especificada.