Gatilhos do Google Cloud Firestore (1a geração)
O Cloud Run functions pode processar eventos no Firestore no mesmo projeto do Google Cloud que a função. É possível ler ou atualizar o Firestore em resposta a esses eventos usando as APIs do Firestore e as bibliotecas de cliente.
Em um ciclo de vida comum, uma função do Firestore realiza as seguintes tarefas:
Espera alterações em um documento específico.
É acionada quando um evento ocorre e realiza as tarefas dela.
Recebe um objeto de dados com um snapshot do documento afetado. Para eventos
write
ouupdate
, o objeto de dados contém instantâneos 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 |
---|---|
providers/cloud.firestore/eventTypes/document.create (padrão) |
Acionado quando um documento é gravado pela primeira vez. |
providers/cloud.firestore/eventTypes/document.update |
Acionado quando um documento já existe e tem algum valor alterado. |
providers/cloud.firestore/eventTypes/document.delete |
Acionado quando um documento com dados é excluído. |
providers/cloud.firestore/eventTypes/document.write |
Acionado quando um documento é criado, atualizado ou excluído. |
Os caracteres curingas são escritos em gatilhos usando chaves, da seguinte maneira: "projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}"
Como especificar o caminho do documento
Para acionar sua função, especifique um caminho de documento para detectar. As funções só respondem às alterações em documentos e não podem monitorar campos ou coleções específicos. Veja 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çãoaddresses
, 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.
Uso de caracteres curingas 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.
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.
Estrutura do evento
Esse gatilho invoca sua função com um evento semelhante ao mostrado abaixo:
{ "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. Isso é especialmente útil se você estiver usando uma linguagem tipada (como Go) para escrever suas funções.
Exemplo de código
A amostra da função do Cloud exemplificada abaixo imprime os campos de um evento de acionamento do Cloud Firestore:
Node.js
Python
Go
Java
C#
Ruby
PHP
O exemplo abaixo recupera o valor adicionado pelo usuário, converte a string nesse local para letras maiúsculas e substitui o valor pela string de caracteres maiúsculos:
Node.js
Python
Go
Java
C#
Ruby
PHP
Como implantar a função
O comando gcloud
a seguir implanta uma função que é acionada por eventos de gravação no documento /messages/{pushId}
:
gcloud functions deploy FUNCTION_NAME \ --no-gen2 \ --entry-point ENTRY_POINT \ --runtime RUNTIME \ --set-env-vars GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID \ --trigger-event "providers/cloud.firestore/eventTypes/document.write" \ --trigger-resource "projects/YOUR_PROJECT_ID/databases/(default)/documents/messages/{pushId}"
Argumento | Descrição |
---|---|
FUNCTION_NAME |
O nome registrado da função do Cloud que você está implantando.
Pode ser o nome de uma função no código-fonte ou uma string arbitrária. Se FUNCTION_NAME for uma string arbitrária, você precisará incluir a sinalização --entry-point .
|
--entry-point ENTRY_POINT |
O nome de uma função ou classe no código-fonte. Opcional, a menos que
você não tenha usado FUNCTION_NAME
para especificar a
função no código-fonte a ser executada durante a implantação. Nesse caso, use --entry-point para fornecer o nome da função executável.
|
--runtime RUNTIME |
O nome do ambiente de execução que você está usando. Para obter uma lista completa, consulte a referência do gcloud .
|
--set-env-vars GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID |
O identificador exclusivo do projeto como uma variável de ambiente do ambiente de execução. |
--trigger-event NAME |
O tipo de evento que a função vai monitorar (um de write , create , update ou delete ). |
--trigger-resource NAME |
O caminho completo do banco de dados em que a função vai detectar.
Isso deve estar de acordo com o seguinte formato: "projects/YOUR_PROJECT_ID/databases/(default)/documents/PATH" O texto {pushId} é um parâmetro curinga descrito acima em Especificação do caminho do documento.
|
Limitações
As seguintes limitações para gatilhos do Firestore do Cloud Run functions:
- O pré-requisito do Cloud Run functions (1ª geração) é um banco de dados "(padrão)" no modo nativo do Firestore. Ele não é compatível com bancos de dados nomeados do Firestore ou com o modo Datastore. Use o Cloud Run functions (2ª geração) para configurar eventos nesses casos.
- Não garantimos acionamentos em ordem. Alterações rápidas podem acionar invocações de função em uma ordem inesperada.
- Os eventos são entregues pelo menos uma vez, mas um único evento pode resultar em invocações de várias funções. Evite depender de mecanismos do tipo "apenas uma vez" e escreva funções idempotentes.
- O Firestore no modo Datastore requer o Cloud Run functions (2ª geração). O Cloud Run functions (1ª geração) não é compatível com o modo Datastore.
- Um gatilho está associado a um único banco de dados. Não é possível criar um gatilho que corresponda a vários bancos de dados.
- A exclusão de um banco de dados não remove automaticamente nenhum gatilho dele. O gatilho deixa de entregar eventos, mas continua existindo até que você o exclua.
- Se um evento correspondente exceder o tamanho máximo da solicitação, ele
pode não ser entregue ao Cloud Run functions (1ª geração).
- Os eventos não entregues devido ao tamanho da solicitação são registrados nos registros da plataforma e contabilizados no uso de registros do projeto.
- É possível encontrar esses registros na Análise de registros com a mensagem "O evento não pode ser entregue à
função do Cloud devido ao tamanho excedido em relação ao limite para a 1ª geração..." da gravidade
de
error
. Encontre o nome da função no campofunctionName
. Se o camporeceiveTimestamp
ainda estiver dentro de uma hora, será possível inferir o conteúdo real do evento lendo o documento em questão com um snapshot antes e depois do carimbo de data/hora. - Para evitar isso, faça o seguinte:
- Migre e faça upgrade para o Cloud Run functions (2ª geração)
- Reduza o tamanho do documento
- Exclua o Cloud Run functions em questão
- É possível desativar a geração de registros usando exclusões, mas os eventos ofensivos ainda não serão entregues.