Ampliar com o Cloud Run functions (2ª geração)
Com o Cloud Run functions, é possível implantar o código para processar eventos acionados por alterações no banco de dados do Firestore. Isso permite que você adicione funcionalidade do lado do servidor sem executar seus próprios servidores.
Ampliar o Firestore com o Cloud Run (2ª geração)
O Cloud Run functions (2nd gen) oferece suporte aos seguintes gatilhos de evento do Firestore para permitir que você crie gerenciadores vinculados a eventos do Firestore:
Tipo de evento | Gatilho |
---|---|
google.cloud.firestore.document.v1.created |
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 é excluído. |
google.cloud.firestore.document.v1.written |
Acionado quando created , updated ou deleted é acionado. |
google.cloud.firestore.document.v1.created.withAuthContext |
Igual a created , mas adiciona informações de autenticação. |
google.cloud.firestore.document.v1.updated.withAuthContext |
Igual a updated , mas adiciona informações de autenticação. |
google.cloud.firestore.document.v1.deleted.withAuthContext |
Igual a deleted , mas adiciona informações de autenticação. |
google.cloud.firestore.document.v1.written.withAuthContext |
Igual a written , mas adiciona informações de autenticação. |
Os eventos do Firestore são acionados somente se houver mudanças nos documentos. Uma atualização em um documento do Firestore, em que os dados permanecem inalterados (uma gravação em ambiente autônomo), não gera um evento de atualização ou gravação. Não é possível adicionar eventos a campos específicos.
Incluir o contexto de autenticação no evento
Para incluir outras informações de autenticação sobre o evento, use um acionador
de evento com a extensão withAuthContext
. Essa extensão adiciona mais
informações sobre o principal que acionou o evento. Ele adiciona os atributos authtype
e authid
, além das informações retornadas no evento base. Consulte a referência
authcontext
para mais informações sobre os valores de atributo.
Gravar uma função acionada pelo Firestore
Para escrever uma função que responda a eventos do Firestore, prepare-se para especificar o seguinte durante a implantação:
- um tipo de evento acionador
- um filtro de evento acionador para selecionar os documentos associados à função
- o código da função a ser executado
Acionar filtros de eventos
Ao especificar um filtro de evento, é possível especificar uma correspondência de documento exata ou um padrão de caminho. Use um padrão de caminho para corresponder a vários documentos com
caracteres curinga, *
ou **
.
Por exemplo, você pode responder a mudanças no seguinte documento:
users/marie
Use caracteres curinga, *
ou **
, para responder a mudanças em documentos
que correspondam a um padrão. Um caractere curinga *
corresponde a um único segmento, e
um caractere curinga de vários segmentos **
corresponde a zero ou mais segmentos no padrão.
Para correspondências de segmento único (*
), você também pode usar um grupo de captura nomeado. Por exemplo, users/{userId}
.
Exemplo:
Padrão | Descrição |
---|---|
/users/* ou /users/{userId} |
Corresponde a todos os documentos na coleção /users . Não corresponde a documentos em subcoleções como /users/marie/messages/33e2IxYBD9enzS50SJ68 |
/users/** |
Corresponde a todos os documentos na coleção /users e em subcoleções como /users/marie/messages/33e2IxYBD9enzS50SJ68 |
Para saber mais sobre os padrões de caminho, consulte Padrões de caminho do Eventarc.
É preciso que seu gatilho aponte sempre para um documento, mesmo que você esteja usando um caractere curinga.
Por exemplo, users/{userId=*}/{messageCollectionId=*}
não é válido porque {messageCollectionId=*}
é uma coleção. No entanto, users/{userId=*}/{messageCollectionId}/{messageId=*}
é válido porque {messageId=*}
sempre vai apontar para um documento.
Exemplos de funções
O exemplo a seguir demonstra como receber eventos do Firestore.
Para trabalhar com os dados do documento envolvidos em um evento, consulte os campos value
e
old_value
.
value
: um objetoDocument
que contém um snapshot de documento pós-operação. Esse campo não é preenchido para eventos de exclusão.old_value
: um objetoDocument
que contém um instantâneo de documento de pré-operação. Esse campo é preenchido apenas para eventos de atualização e exclusão.
Go
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Use protobufjs para decodificar os dados do evento. Incluagoogle.events.cloud.firestore.v1
data.proto
na sua origem.
Python
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
C#
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Os exemplos a seguir convertem strings adicionadas ao campo original
de um
documento afetado para letras maiúsculas e gravam o novo valor no mesmo documento:
Go
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Use protobufjs para decodificar os dados do evento. Incluagoogle.events.cloud.firestore.v1
data.proto
na sua origem.
Python
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
C#
Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Inclua as dependências de proto na sua origem
É necessário incluir o arquivo data.proto
do Firestore
no diretório de origem da função. Esse arquivo importa os seguintes
protos, que também precisam ser incluídos no diretório de origem:
Use a mesma estrutura de diretório para as dependências. Por exemplo, coloque
struct.proto
dentro de google/protobuf
.
Esses arquivos são necessários para decodificar os dados do evento. Se a origem da função não incluir esses arquivos, ela vai retornar um erro quando for executada.
Atributos do evento
Cada evento inclui atributos de dados que contêm informações sobre o evento, como o horário em que ele foi acionado. O Firestore adiciona mais dados sobre o banco de dados e o documento envolvidos no evento. É possível acessar esses atributos da seguinte maneira:
Java
logger.info("Function triggered by event on: " + event.getSource()); logger.info("Event type: " + event.getType()); logger.info("Event time " + event.getTime()); logger.info("Event project: " + event.getExtension("project")); logger.info("Event location: " + event.getExtension("location")); logger.info("Database name: " + event.getExtension("database")); logger.info("Database document: " + event.getExtension("document")); // For withAuthContext events logger.info("Auth information: " + event.getExtension("authid")); logger.info("Auth information: " + event.getExtension("authtype"));
Node.js
console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log(`Event time: ${cloudEvent.time}`); console.log(`Event project: ${cloudEvent.project}`); console.log(`Event location: ${cloudEvent.location}`); console.log(`Database name: ${cloudEvent.database}`); console.log(`Document name: ${cloudEvent.document}`); // For withAuthContext events console.log(`Auth information: ${cloudEvent.authid}`); console.log(`Auth information: ${cloudEvent.authtype}`);
Python
print(f"Function triggered by change to: {cloud_event['source']}") print(f"Event type: {cloud_event['type']}") print(f"Event time: {cloud_event['time']}") print(f"Event project: {cloud_event['project']}") print(f"Location: {cloud_event['location']}") print(f"Database name: {cloud_event['database']}") print(f"Document: {cloud_event['document']}") // For withAuthContext events print(f"Auth information: {cloud_event['authid']}") print(f"Auth information: {cloud_event['authtype']}")
Implantar uma função
Os usuários que implantam funções do Cloud Run precisam ter o papel do IAM de Desenvolvedor de funções do Cloud Run ou um papel que inclua as mesmas permissões. Consulte também Outras configurações para implantação.
É possível implantar uma função usando a CLI gcloud ou o console do Google Cloud. O exemplo abaixo demonstra a implantação com a CLI gcloud. Para saber mais sobre a implantação com o console do Google Cloud, consulte Implantar funções do Cloud Run.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Use o comando
gcloud functions deploy
para implantar uma função:gcloud functions deploy YOUR_FUNCTION_NAME \ --gen2 \ --region=FUNCTION_LOCATION \ --trigger-location=TRIGGER_LOCATION \ --runtime=YOUR_RUNTIME \ --source=YOUR_SOURCE_LOCATION \ --entry-point=YOUR_CODE_ENTRYPOINT \ --trigger-event-filters="type=EVENT_FILTER_TYPE" \ --trigger-event-filters="database=DATABASE" \ --trigger-event-filters-path-pattern="document=DOCUMENT" \
O primeiro argumento,
YOUR_FUNCTION_NAME
, é um nome para a função implantada. O nome da função deve começar com uma letra, seguida por até 62 letras, números, hífens e sublinhados, e terminar com uma letra ou um númeroA flag
--gen2
especifica que você quer implantar nas funções do Cloud Run (2ª geração). A omissão dessa flag resulta na implantação no Cloud Run functions (1ª geração).A sinalização
--region
especifica a região em que a função será implantada.Para maximizar a proximidade, defina uma região perto do seu banco de dados do Firestore. Se o banco de dados do Firestore estiver em um local multirregional, defina como
us-central1
para bancos de dados emnam5
e comoeurope-west4
para bancos de dados emeur3
. Para locais regionais do Firestore, defina a mesma região.A flag
--trigger-location
especifica o local do acionador. Defina essa flag como o local do seu banco de dados do Firestore.A sinalização
--runtime
especifica o ambiente de execução da linguagem que a função usa. O Cloud Run functions aceita vários ambientes de execução. Consulte Tempos de execução para mais informações.A sinalização
--source
especifica o local do código-fonte da função. Confira mais detalhes neste link:A sinalização
--entry-point
especifica o ponto de entrada da função no código-fonte. Este é o código que será executado quando a função for executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte. Consulte Ponto de entrada de função para mais informações.EVENT_FILTER_TYPE
: o Firestore oferece suporte aos seguintes tipos de evento.google.cloud.firestore.document.v1.created
: o evento é enviado quando um documento é gravado pela primeira vez.google.cloud.firestore.document.v1.updated
: o evento é enviado quando um documento já existe e algum valor é alterado.google.cloud.firestore.document.v1.deleted
: o evento é enviado quando um documento é excluído.google.cloud.firestore.document.v1.written
: o evento é enviado quando um documento é criado, atualizado ou excluído.google.cloud.firestore.document.v1.created.withAuthContext
: o evento é enviado quando um documento é gravado pela primeira vez e inclui mais informações de autenticação.google.cloud.firestore.document.v1.updated.withAuthContext
: o evento é enviado quando um documento já existe e algum valor é alterado. Inclui outras informações de autenticaçãogoogle.cloud.firestore.document.v1.deleted.withAuthContext
: o evento é enviado quando um documento é excluído. Inclui outras informações de autenticaçãogoogle.cloud.firestore.document.v1.written.withAuthContext
: o evento é enviado quando um documento é criado, atualizado ou excluído e evento. Inclui outras informações de autenticação
DATABASE
: o banco de dados do Firestore. Para o nome padrão do banco de dados, use(default)
.DOCUMENT
: o caminho do banco de dados que aciona eventos quando os dados são criados, atualizados ou excluídos. O operador pode ser um dos seguintes:- Igual por exemplo,
--trigger-event-filters=document='users/marie'
- Padrão do caminho por exemplo,
--trigger-event-filters-path-pattern=document='users/*'
. Para mais informações, consulte Entender os padrões de caminho.
- Igual por exemplo,
Também é possível especificar opções adicionais de configuração, rede e segurança ao implantar uma função.
Para ver uma referência completa sobre o comando de implantação e as sinalizações dele, consulte a documentação
gcloud functions deploy
.
Exemplos de implantações
Os exemplos a seguir demonstram implantações com a Google Cloud CLI.
Implante uma função para um banco de dados na região us-west2
:
gcloud functions deploy gcfv2-trigger-firestore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
Implante uma função para um banco de dados na multirregião nam5
:
gcloud functions deploy gcfv2-trigger-firestore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
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.
Locais do Eventarc e do Firestore
O Eventarc não oferece suporte a várias regiões para gatilhos de eventos do Firestore, mas você ainda pode criar gatilhos para bancos de dados do Firestore em locais multirregionais. O Eventarc mapeia os locais de várias regiões do Firestore para as seguintes regiões do Eventarc:
Multirregião do Firestore | Região do Eventarc |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |
Diferenças entre as funções do Cloud Run de 1ª e 2ª geração
As funções do Cloud Run (2a geração) usam eventos do Eventarc para todos os ambientes de execução. Anteriormente, as funções do Cloud Run (1ª geração) usavam eventos do Eventarc para apenas alguns ambientes de execução. Os eventos do Eventarc apresentam as seguintes diferenças em relação às funções do Cloud Run (1ª geração).
Os gatilhos do Firestore para o Eventarc oferecem suporte a outros destinos além das funções do Cloud Run. É possível encaminhar
CloudEvents
para vários destinos, incluindo, mas não se limitando a Cloud Run, GKE e Workflows.Os acionadores do Firestore para o Eventarc recuperam a definição do acionador no início de uma operação de gravação de banco de dados e usam essa definição para decidir se o Firestore precisa emitir um evento. A operação de gravação não considera as mudanças na definição do acionador que podem acontecer durante a execução.
O Cloud Run functions (1ª geração) recupera a definição do acionador durante a avaliação da gravação do banco de dados, e as alterações no acionador durante a avaliação podem afetar se o Firestore emite um evento ou não.
Para mais detalhes, consulte Comparação de versões das funções do Cloud Run.