Crie acionadores a partir de eventos do 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.

Pode configurar os seus serviços do Cloud Run para serem acionados por eventos numa base de dados do Firestore. Quando acionado, o seu serviço lê e atualiza uma base de dados do Firestore em resposta a estes eventos através das APIs e bibliotecas de cliente do Firestore.

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

  1. O serviço aguarda alterações a um documento específico.

  2. Quando ocorre uma alteração, o serviço é acionado e executa as respetivas tarefas.

  3. O serviço recebe um objeto de dados com um instantâneo do documento afetado. Para eventos write ou update, o objeto de dados contém instantâneos que representam o estado do documento antes e depois do evento de acionamento.

Tipos de eventos

O Firestore suporta eventos create, update, delete e write. O evento write abrange todas as modificações a um documento.

Tipo de evento Acionador
google.cloud.firestore.document.v1.created (predefinição) Acionado quando um documento é escrito pela primeira vez.
google.cloud.firestore.document.v1.updated Acionado quando já existe um documento e qualquer valor é alterado.
google.cloud.firestore.document.v1.deleted Acionado quando um documento com dados é eliminado.
google.cloud.firestore.document.v1.written Acionado quando um documento é criado, atualizado ou eliminado.

Os carateres universais são escritos em acionadores com chavetas, por exemplo: projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

Especifique o caminho do documento

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

Seguem-se alguns exemplos de caminhos de documentos válidos:

  • users/marie: acionador válido. Monitoriza um único documento, /users/marie.

  • users/{username}: acionador válido. Monitoriza todos os documentos do utilizador. Os carateres universais são usados para monitorizar todos os documentos na coleção.

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

  • users/{username}/addresses/home: acionador válido. Monitoriza o documento de morada para todos os utilizadores.

  • users/{username}/addresses/{addressId}: acionador válido. Monitoriza todos os documentos de morada.

  • users/{user=**}: acionador válido. Monitoriza todos os documentos de utilizadores e todos os documentos em subcoleções em cada documento de utilizador, como /users/userID/address/home ou /users/userID/phone/work.

Carateres universais e parâmetros

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

  • users/{username} ouve as alterações a todos os documentos do utilizador.

Neste exemplo, quando qualquer campo em qualquer documento em users é alterado, corresponde a um caráter universal denominado {username}.

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

As correspondências com carateres universais são extraídas dos caminhos dos documentos. Pode definir quantos carateres universais quiser para substituir IDs de documentos ou coleções explícitos. Pode usar até um caráter universal de vários segmentos, como {username=**}.

Estruturas de eventos

Este acionador invoca o seu serviço com um evento semelhante ao seguinte: 

{
    "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 Value documentação para referências de tipos.

Antes de começar

  1. Certifique-se de que 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:

    Ative as APIs

Funções necessárias

O utilizador ou o administrador tem de conceder à conta de implementação, à identidade do acionador e, opcionalmente, ao agente do serviço Pub/Sub as seguintes funções de IAM.

Funções necessárias para a conta do implementador

Para receber as autorizações de que precisa para acionar a partir de eventos do Firestore, peça ao seu administrador para lhe conceder as seguintes funções de IAM no seu projeto:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Tenha em atenção que, por predefinição, as autorizações do Cloud Build incluem autorizações para carregar e transferir artefactos do Artifact Registry.

Funções necessárias para a identidade do acionador

  1. Tome nota da conta de serviço predefinida do Compute Engine, uma vez que a vai anexar a um acionador do Eventarc para representar a identidade do acionador para fins de teste. Esta conta de serviço é criada automaticamente depois de ativar ou usar um Google Cloud serviço que usa o Compute Engine e com o seguinte formato de email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Substitua PROJECT_NUMBER pelo seu Google Cloud número do projeto. Pode encontrar o número do projeto na página Boas-vindas da Google Cloud consola ou executando o seguinte comando:

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

    Para ambientes de produção, recomendamos vivamente que crie uma nova conta de serviço e lhe conceda uma ou mais funções do IAM que contenham as autorizações mínimas necessárias e siga o princípio do privilégio mínimo.

  2. Por predefiniçã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. Pode controlar o acesso por serviço. No entanto, para fins de teste, conceda a função de invocador do Cloud Run (run.invoker) no Google Cloud projeto à conta de serviço do Compute Engine. Isto concede a função em todos os serviços e tarefas do Cloud Run num projeto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Tenha em atenção que, se criar um acionador para um serviço do Cloud Run autenticado sem conceder a função de invocador do Cloud Run, o acionador é criado com êxito e está ativo. No entanto, o acionador não funciona conforme esperado e é apresentada uma mensagem semelhante à seguinte nos registos:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  3. Conceda a função de recetor de eventos do Eventarc (roles/eventarc.eventReceiver) no projeto à conta de serviço predefinida do Compute Engine para que o acionador do Eventarc possa receber eventos de fornecedores de eventos. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Função opcional para o agente do serviço Pub/Sub

  • Se ativou o agente do serviço Cloud Pub/Sub a 8 de abril de 2021 ou antes, para suportar pedidos de envio do Pub/Sub autenticados, conceda a função de criador de tokens de conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente do serviço. Caso contrário, esta função é concedida por predefinição: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Configure a base de dados do Firestore

Antes de implementar o seu serviço, tem de criar uma base de dados do Firestore:

  1. Aceda à página de dados do Firestore.

  2. Selecione Criar base de dados.

  3. Clique em Modo nativo e, de seguida, selecione Continuar.

  4. No campo Dê um nome à sua base de dados, introduza um ID da base de dados, como firestore-db.

  5. Em Tipo de localização, selecione Região e escolha a região onde a sua base de dados vai residir. Esta escolha é permanente.

  6. Deixe a secção Regras seguras tal como está.

  7. Clique em Criar base de dados.

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

Crie acionadores

Consoante o tipo de serviço que está a implementar, pode:

Crie um acionador para serviços

Pode especificar um acionador depois de implementar um serviço.

Clique no separador para ver instruções sobre como usar a ferramenta da sua escolha.

Consola

  1. Implemente o seu serviço do Cloud Run através de contentores ou a partir de origem.

  2. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  3. Na lista de serviços, clique num serviço existente.

  4. Na página Detalhes do serviço, navegue para o separador Acionadores.

  5. Clique em Adicionar acionador e selecione Acionador do Firestore.

  6. No painel Acionador do Eventarc, modifique os detalhes do acionador da seguinte forma:

    1. No campo Nome do acionador, introduza um nome para o acionador ou use o nome predefinido.

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

      • Origens Google para especificar acionadores para o Pub/Sub, o Cloud Storage, o Firestore e outros fornecedores de eventos Google.

      • Terceiros para integrar com fornecedores que não sejam da Google que oferecem uma origem do Eventarc. Para mais informações, consulte o artigo Eventos de terceiros no Eventarc.

    3. Selecione Firestore na lista Fornecedor de eventos para selecionar um produto que forneça o tipo de evento para acionar o seu serviço. Para ver a lista de fornecedores de eventos, consulte o artigo Fornecedores de eventos e destinos.

    4. Selecione type=google.cloud.firestore.document.v1.created na lista Tipo de evento. A configuração do acionador varia consoante o tipo de evento suportado. Para mais informações, consulte o artigo Tipos de eventos.

    5. Na secção Filtros, selecione uma base de dados, uma operação e valores de atributos, ou use as seleções predefinidas.

    6. Se o campo Região estiver ativado, selecione uma localização para o acionador do Eventarc. Em geral, a localização de um acionador do Eventarc deve corresponder à localização do recurso que quer monitorizar para eventos. Google Cloud Na maioria dos cenários, também deve implementar o serviço na mesma região. Consulte o artigo Compreenda as localizações do Eventarc para ver mais detalhes sobre as localizações dos acionadores do Eventarc.

    7. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc estão associados a contas de serviço para usar como identidade quando invocam o seu serviço. A conta de serviço do acionador do Eventarc tem de ter a autorização para invocar o seu serviço. Por predefinição, o Cloud Run usa a conta de serviço predefinida do Compute Engine.

    8. Opcionalmente, especifique o caminho do URL do serviço para o qual enviar o pedido recebido. Este é o caminho relativo no serviço de destino para o qual os eventos do acionador devem ser enviados. Por exemplo: /, /route, route e route/subroute.

    9. Depois de preencher os campos obrigatórios, clique em Guardar acionador.

  7. Depois de criar o acionador, verifique o respetivo estado certificando-se de que existe uma marca de verificação no separador Acionadores.

gcloud

  1. Implemente o seu serviço do Cloud Run através de contentores ou a partir de origem.

  2. Execute o seguinte comando 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

    Substituir:

    • TRIGGER_NAME com o nome do acionador.

    • EVENTARC_TRIGGER_LOCATION com a localização do acionador do Eventarc. Em geral, a localização de um acionador do Eventarc deve corresponder à localização do Google Cloud recurso que quer monitorizar para eventos. Na maioria dos cenários, também deve implementar o seu serviço na mesma região. Para mais informações, consulte o artigo Localizações do Eventarc.

    • SERVICE com o nome do serviço que está a implementar.

    • REGION com a região do Cloud Run do serviço. Por exemplo, europe-west1.

    • PROJECT_NUMBER com o seu Google Cloud número do projeto. Os acionadores do Eventarc estão associados a contas de serviço para usar como identidade quando invoca o seu serviço. A conta de serviço do seu acionador do Eventarc tem de ter autorização para invocar o seu serviço. Por predefinição, o Cloud Run usa a conta de serviço de computação predefinida.

    Cada sinalização event-filters especifica um tipo de evento, com a função a ser acionada apenas quando um evento cumpre todos os critérios especificados nas respetivas sinalizações event-filters. Cada acionador tem de ter uma flag event-filters que especifique um tipo de evento suportado, como um novo documento escrito no Firestore ou um ficheiro carregado para o Cloud Storage. Não pode alterar o tipo de filtro de eventos após a criação. Para alterar o tipo de filtro de eventos, tem de criar um novo acionador e eliminar o antigo. Opcionalmente, pode repetir a flag --event-filters com um filtro suportado no formato ATTRIBUTE=VALUE para adicionar mais filtros.

Terraform

Para criar um acionador do Eventarc para um serviço do Cloud Run, consulte o artigo Crie um acionador com o Terraform.

Crie um acionador para funções

Clique no separador para ver instruções sobre como usar a ferramenta da sua escolha.

Consola

Quando usa a Google Cloud consola para criar uma função, também pode adicionar um acionador à sua função. Siga estes passos para criar um acionador para a sua função:

  1. Na Google Cloud consola, aceda ao Cloud Run:

    Aceda ao Cloud Run

  2. Clique em Escrever uma função e introduza os detalhes da função. Para mais informações sobre a configuração de funções durante a implementação, consulte Implementar funções.

  3. Na secção Acionador, clique em Adicionar acionador.

  4. Selecione Acionador do Firestore.

  5. No painel Acionador do Eventarc, modifique os detalhes do acionador da seguinte forma:

    1. Introduza um nome para o acionador no campo Nome do acionador ou use o nome predefinido.

    2. Selecione um Tipo de acionador na lista:

      • Origens Google para especificar acionadores para o Pub/Sub, o Cloud Storage, o Firestore e outros fornecedores de eventos Google.

      • Terceiros para integrar com fornecedores que não sejam da Google que oferecem uma origem do Eventarc. Para mais informações, consulte o artigo Eventos de terceiros no Eventarc.

    3. Selecione Firestore na lista Fornecedor de eventos para selecionar um produto que forneça o tipo de evento para acionar a sua função. Para ver a lista de fornecedores de eventos, consulte o artigo Fornecedores de eventos e destinos.

    4. Selecione type=google.cloud.firestore.document.v1.created na lista Tipo de evento. A configuração do acionador varia consoante o tipo de evento suportado. Para mais informações, consulte o artigo Tipos de eventos.

    5. Na secção Filtros, selecione uma base de dados, uma operação e valores de atributos, ou use as seleções predefinidas.

    6. Se o campo Região estiver ativado, selecione uma localização para o acionador do Eventarc. Em geral, a localização de um acionador do Eventarc deve corresponder à localização do recurso que quer monitorizar para eventos. Google Cloud Na maioria dos cenários, também deve implementar a função na mesma região. Consulte o artigo Compreenda as localizações do Eventarc para ver mais detalhes sobre as localizações dos acionadores do Eventarc.

    7. No campo Conta de serviço, selecione uma conta de serviço. Os acionadores do Eventarc estão associados a contas de serviço para usar como identidade quando invocam a sua função. A conta de serviço do acionador do Eventarc tem de ter a autorização para invocar a sua função. Por predefinição, o Cloud Run usa a conta de serviço predefinida do Compute Engine.

    8. Opcionalmente, especifique o caminho do URL do serviço para o qual enviar o pedido recebido. Este é o caminho relativo no serviço de destino para o qual os eventos do acionador devem ser enviados. Por exemplo: /, /route, route e route/subroute.

  6. Depois de preencher os campos obrigatórios, clique em Guardar acionador.

gcloud

Quando cria uma função através da CLI gcloud, tem primeiro de implementar a função e, em seguida, criar um acionador. Siga estes passos para criar um acionador para a sua função:

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

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

    Substituir:

    • FUNCTION com o nome da função que está a implementar. Pode omitir este parâmetro por completo, mas é-lhe pedido o nome se o omitir.

    • FUNCTION_ENTRYPOINT com o ponto de entrada da sua função no código-fonte. Este é o código que o Cloud Run executa quando a sua função é executada. O valor desta flag tem de ser um nome de função ou um nome de classe totalmente qualificado que exista no seu código-fonte.

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

    • REGION com a Google Cloud região onde quer implementar a sua função. Por exemplo, europe-west1.

  2. Execute o seguinte comando 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

    Substituir:

    • TRIGGER_NAME com o nome do acionador.

    • EVENTARC_TRIGGER_LOCATION com a localização do acionador do Eventarc. Em geral, a localização de um acionador do Eventarc deve corresponder à localização do Google Cloud recurso que quer monitorizar para eventos. Na maioria dos cenários, também deve implementar a função na mesma região. Para mais informações, consulte o artigo Localizações do Eventarc.

    • FUNCTION com o nome da função que está a implementar.

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

    • PROJECT_NUMBER com o seu Google Cloud número do projeto. Os acionadores do Eventarc estão associados a contas de serviço para serem usados como uma identidade quando invocam a sua função. A conta de serviço do seu acionador do Eventarc tem de ter autorização para invocar a sua função. Por predefinição, o Cloud Run usa a conta de serviço de computação predefinida.

    Cada sinalização event-filters especifica um tipo de evento, com a função a ser acionada apenas quando um evento cumpre todos os critérios especificados nas respetivas sinalizações event-filters. Cada acionador tem de ter uma flag event-filters que especifique um tipo de evento suportado, como um novo documento escrito no Firestore ou um ficheiro carregado para o Cloud Storage. Não pode alterar o tipo de filtro de eventos após a criação. Para alterar o tipo de filtro de eventos, tem de criar um novo acionador e eliminar o antigo. Opcionalmente, pode repetir a flag --event-filters com um filtro suportado no formato ATTRIBUTE=VALUE para adicionar mais filtros.

Terraform

Para criar um acionador do Eventarc para uma função do Cloud Run, consulte o artigo Crie um acionador com o Terraform.

Consulte o artigo Estenda o Firestore com acionadores de eventos através de funções do Cloud Run para mais informações.

O que se segue?

  • Veja exemplos de funções que são acionadas quando faz alterações a um documento numa coleção especificada.