O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar acionadores com base em eventos do Firestore

Este guia aborda as instruções para criar gatilhos para serviços e funções do Cloud Run com base em eventos do Firestore.

É possível configurar os serviços do Cloud Run para que sejam acionados por eventos em um banco de dados do Firestore. Quando acionado, seu serviço lê e atualiza um banco de dados do Firestore em resposta a esses eventos pelas APIs do Firestore e 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:

O serviço espera por mudanças em um documento específico.
Quando uma mudança ocorre, o serviço é acionado e realiza as tarefas dele.
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 de acionamento.

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 curingas 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 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 gatilho invoca seu serviço com um evento semelhante a:

{
    "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

Verifique se você configurou um novo projeto para o Cloud Run conforme descrito na página de configuração.
Ative as APIs Artifact Registry, Cloud Build, API Cloud Run Admin, Eventarc, Firestore Cloud Logging e API Pub/Sub:

Ativar as APIs
Conceda as permissões e os papéis necessários do IAM.

Papéis necessários para a conta do implantador

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

Editor do Cloud Build (roles/cloudbuild.builds.editor)
Administrador do Cloud Run (roles/run.admin)
Proprietário do Datastore (roles/datastore.owner)
Administrador do Eventarc (roles/eventarc.admin)
Acessador de exibição de registros (roles/logging.viewAccessor)
Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
Usuário da conta de serviço (roles/iam.serviceAccountUser)
Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)

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 usando papéis personalizados ou outros papéis predefinidos.

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

Configurar o banco de dados do Firestore

Antes de implantar o serviço, crie um banco de dados do Firestore:

Acesse a página de dados do Firestore.
Selecione Criar banco de dados.
Clique em Modo nativo e selecione Continuar.
No campo Nomeie seu banco de dados, insira um ID do banco de dados, como firestore-db.
Em Tipo de local, selecione Região e escolha a região em que seu banco de dados vai ficar. Essa opção é permanente.
Deixe a seção Regras de segurança no estado em que se encontra.
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.