Com o Cloud Functions e o Eventarc, é possível implantar código para processar eventos acionados por alterações no seu banco de dados do Firestore no modo Datastore. Isso permite adicionar funcionalidades do lado do servidor sem executar seus próprios servidores.
Gatilhos do modo Datastore
O Eventarc é compatível com os seguintes acionadores de eventos do Firestore no modo Datastore para permitir que você crie gerenciadores do Cloud Functions (2nd gen) vinculados ao Firestore no modo Datastore:
Tipo de evento | Gatilho |
---|---|
google.cloud.datastore.entity.v1.created |
Acionado quando uma entidade é gravada pela primeira vez. |
google.cloud.datastore.entity.v1.updated |
Acionado quando uma entidade já existe e tem algum valor alterado. |
google.cloud.datastore.entity.v1.deleted |
Acionado quando uma entidade é excluída. |
google.cloud.datastore.entity.v1.written |
Acionado quando created , updated ou deleted é acionado. |
google.cloud.datastore.entity.v1.created.withAuthContext |
Igual a created , mas adiciona informações de autenticação. |
google.cloud.datastore.entity.v1.updated.withAuthContext |
Igual a updated , mas adiciona informações de autenticação. |
google.cloud.datastore.entity.v1.deleted.withAuthContext |
Igual a deleted , mas adiciona informações de autenticação. |
google.cloud.datastore.entity.v1.written.withAuthContext |
Igual a written , mas adiciona informações de autenticação. |
Os acionadores de evento do modo Datastore respondem apenas a alterações de entidade. Uma atualização em uma entidade do modo Datastore, 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 gerar eventos apenas para propriedades específicas.
Inclua o contexto de autenticação no evento
Para incluir mais informações de autenticação sobre o evento, use um acionador
de eventos com a extensão withAuthContext
. Essa extensão adiciona outras
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 valores de atributos.
Escrever uma função acionada por entidade
Para escrever uma função que responda a eventos do Firestore no modo Datastore, prepare-se para especificar o seguinte durante a implantação:
- um tipo de evento de gatilho
- um filtro de evento de gatilho para selecionar as entidades associadas à função
- o código de função a ser executado
Filtros de eventos de acionamento
Ao especificar um filtro de evento, você pode determinar uma correspondência exata de entidade ou um padrão de caminho. Use um padrão de caminho para corresponder várias entidades com
os caracteres curinga *
ou **
.
Por exemplo, é possível especificar uma correspondência exata de entidade para responder a mudanças na seguinte entidade:
users/marie
Use caracteres curinga, *
ou **
, para responder a alterações em entidades
que correspondam a um padrão. O caractere curinga *
corresponde a um único segmento, e o 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, como
users/{userId}
.
A tabela a seguir demonstra padrões de caminho válidos:
Padrão | Descrição |
---|---|
users/* ou users/{userId} |
Corresponde a todas as entidades do tipo users . Não corresponde ao nível das entidades descendentes, como /users/marie/messages/33e2IxYBD9enzS50SJ68 |
users/** |
Corresponde a todas as entidades do tipo users e a todas as entidades descendentes, como
/users/marie/messages/33e2IxYBD9enzS50SJ68 |
Para saber mais sobre padrões de caminho, consulte Padrões de caminho do Eventarc.
É preciso que seu gatilho aponte sempre para uma entidade, mesmo que você esteja usando um caractere curinga. Veja os exemplos a seguir:
users/{userId=*}/{messages=*}
não é válido porque{messages=*}
é um ID de tipo.users/{userId=*}/{messages}/{messageId=*}
é válido porque{messageId=*}
sempre aponta para uma entidade.
Escape de caracteres
Nesta seção, descrevemos situações em que é necessário usar caracteres de escape em IDs de tipo e de entidade. O escape de um caractere permite que o filtro de eventos interprete o ID corretamente.
Se um ID de tipo ou de entidade incluir um caractere
~
ou/
, faça o escape do ID no filtro de eventos. Para fazer o escape de um ID, use o formato__escENCODED_ID__
. Substitua ENCODED_ID por um ID de tipo ou de entidade que tenha todos os caracteres~
e/
substituídos pelos IDs de codificação, que são os seguintes:~
:~0
/
:~1
Por exemplo, o ID de tipo
user/profile
se torna__escusers~1profile__
. Um exemplo de padrão de caminho com esse ID de tipo é__escusers~1profile__/{userId}
.Se você usar o ID de tipo ou o ID da entidade de
.
ou..
no filtro de eventos, faça o escape do ID da seguinte maneira:.
:__esc~2__
..
:__esc~2~2__
É necessário inserir o caractere de escape
.
somente se o ID for exatamente.
ou..
. Por exemplo, o ID de tipocustomers.info
não requer escape.Se o ID do tipo ou da entidade for um valor numérico em vez de um valor de string, será necessário inserir o escape do ID com
__idNUMERIC_VALUE__
. Por exemplo, o padrão de caminho de uma entidade do tipo111
e ID222
é__id111__/__id222__
.Se você migrou do Cloud Datastore legado para o Firestore no modo Datastore, seu banco de dados pode conter IDs legados em uma codificação não UTF8. É necessário usar
__bytesBASE64_ENCODING__
como escape nesses IDs. Substitua BASE64_ENCODING pela codificação base64 do ID. Por exemplo, o padrão de caminhoTask/{task}
com escape para um ID de tipo não UTF8Task
se torna__bytesVGFzaw==__/{task}
.
Exemplos de funções
O exemplo a seguir demonstra como receber eventos do modo Datastore.
Para trabalhar com os dados envolvidos em um evento, consulte os campos value
e old_value
.
value
: um objetoEntityResult
que contém um snapshot da entidade pós-operação. Esse campo não é preenchido para eventos de exclusão.old_value
: um objetoEntityResult
que contém um snapshot da entidade pré-operação. Esse campo só é preenchido para eventos de atualização e exclusão.
Java
Para saber como instalar e usar a biblioteca de cliente para o modo Datastore, consulte Bibliotecas de cliente do modo Datastore. Para mais informações, consulte a documentação de referência da API Java do modo Datastore.
Para autenticar no modo Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Incluir as dependências do proto na sua origem
Inclua o arquivo data.proto
do modo Datastore no diretório de origem da sua função. Esse arquivo importa os seguintes
protos, que você também precisa incluir no diretório de origem:
Use a mesma estrutura de diretórios para as dependências. Por exemplo, coloque
struct.proto
em google/protobuf
.
Esses arquivos são necessários para decodificar dados de eventos. Se a fonte da função não incluir esses arquivos, ela retornará um erro quando for executada.
Atributos de evento
Cada evento tem atributos de dados com informações sobre o evento, como a hora em que ele foi acionado. O Firestore no modo Datastore adiciona outros dados sobre o banco de dados e a entidade envolvida no evento. Você pode acessar esses atributos da seguinte maneira:
Java
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 namespace: " + event.getExtension("namespace")); logger.info("Database entity: " + event.getExtension("entity")); // For withAuthContext events logger.info("Auth information: " + event.getExtension("authid")); logger.info("Auth information: " + event.getExtension("authtype"));
Implantar uma função
Os usuários que implantam o Cloud Functions precisam ter o papel do IAM de Desenvolvedor do Cloud Functions 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 detalhes sobre a implantação com o console do Google Cloud, consulte Implantar o Cloud Functions.
-
No Console do Google Cloud, ative o Cloud Shell.
Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Use o comando
gcloud functions deploy
para implantar uma função:gcloud functions deploy FUNCTION_NAME \ --gen2 \ --region=FUNCTION_LOCATION \ --trigger-location=TRIGGER_LOCATION \ --runtime=RUNTIME \ --source=SOURCE_LOCATION \ --entry-point=CODE_ENTRYPOINT \ --trigger-event-filters="type=EVENT_FILTER_TYPE" \ --trigger-event-filters="database=DATABASE" \ --trigger-event-filters="namespace=NAMESPACE" \ --trigger-event-filters-path-pattern="entity=ENTITY_OR_PATH" \
O primeiro argumento, 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úmero Substitua FUNCTION_NAME por um nome de função válido. Em seguida, adicione as seguintes flags:
A sinalização
--gen2
especifica que você quer implantar no Cloud Functions (2a geração). A omissão dessa sinalização resulta na implantação no Cloud Functions (1a geração).A sinalização
--region=FUNCTION_LOCATION
especifica a região em que a função será implantada.Para maximizar a proximidade, defina FUNCTION_LOCATION como uma região próxima ao banco de dados do Firestore. Se o banco de dados do Firestore estiver em um local multirregional, defina o valor 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 sinalização
--trigger-location=TRIGGER_LOCATION
especifica o local do gatilho. Defina TRIGGER_LOCATION como o local do seu banco de dados do modo Datastore.A sinalização
--runtime=RUNTIME
especifica o ambiente de execução da linguagem que a função usa. O Cloud Functions dá suporte a vários ambientes de execução. Consulte Ambientes de execução para mais informações. Defina RUNTIME como um ambiente de execução compatível.A sinalização
--source=SOURCE_LOCATION
especifica o local do código-fonte da função. Consulte os detalhes a seguir:- Implantar usando sua máquina local
- Implantar a partir do Cloud Storage
- Implantar a partir de um repositório de origem
Defina SOURCE_LOCATION como o local do código-fonte da função.
A sinalização
--entry-point=CODE_ENTRYPOINT
especifica o ponto de entrada da função no código-fonte. Esse é o código que sua função executa quando é executada. Defina CODE_ENTRYPOINT como um nome de função ou um nome de classe totalmente qualificado que exista no código-fonte. Consulte Ponto de entrada da função para mais informações.As flags
--trigger-event-filters
definem o filtro de eventos, que inclui o tipo de gatilho e a entidade ou o caminho que aciona os eventos. Defina os seguintes valores de atributo para definir o filtro de evento:type=EVENT_FILTER_TYPE
: o Firestore oferece suporte aos tipos de evento a seguir:google.cloud.datastore.entity.v1.created
: o evento é enviado quando uma entidade é gravada pela primeira vez.google.cloud.datastore.entity.v1.updated
: o evento é enviado quando uma entidade já existe e tem algum valor alterado.google.cloud.datastore.entity.v1.deleted
: o evento é enviado quando uma entidade é excluída.google.cloud.datastore.entity.v1.written
: o evento é enviado quando uma entidade é criada, atualizada ou excluída.google.cloud.datastore.entity.v1.created.withAuthContext
: o evento é enviado quando um documento é gravado pela primeira vez e inclui mais informações de autenticação.google.cloud.datastore.entity.v1.updated.withAuthContext
: o evento é enviado quando um documento já existe e tem algum valor alterado. Inclui informações extras de autenticaçãogoogle.cloud.datastore.entity.v1.deleted.withAuthContext
: o evento é enviado quando um documento é excluído. Inclui informações adicionais de autenticaçãogoogle.cloud.datastore.entity.v1.written.withAuthContext
: o evento é enviado quando um documento é criado, atualizado ou excluído e evento. Inclui informações extras de autenticação
Defina EVENT_FILTER_TYPE como um desses tipos de evento.
database=DATABASE
: o banco de dados do Firestore. Para o nome padrão do banco de dados, defina DATABASE como(default)
.namespace=NAMESPACE
: o namespace do banco de dados. Para o nome padrão do banco de dados, defina NAMESPACE como(default)
. Remova a sinalização para corresponder a qualquer namespace.entity=ENTITY_OR_PATH
: o caminho do banco de dados que aciona eventos quando os dados são criados, atualizados ou excluídos. Os valores aceitos para ENTITY_OR_PATH são:- Igual, por exemplo,
--trigger-event-filters="entity='users/marie'"
- Padrão do caminho por exemplo,
--trigger-event-filters-path-pattern="entity='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ção
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-datastore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"
Implante uma função para um banco de dados na multirregião nam5
:
gcloud functions deploy gcfv2-trigger-datastore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://example_bucket-1/datastoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.datastore.entity.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern="entity='messages/{pushId}'"
Limitações
Observe as seguintes limitações para acionadores do Firestore para Cloud Functions:
- 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 Functions (2ª geração). O Cloud Functions (1ª geração) não é compatível com o modo Datastore.
- O Cloud Functions (1ª geração) só funciona com o banco de dados "(padrão)" e não é compatível com bancos de dados nomeados do Firestore. Use o Cloud Functions (2ª geração) para configurar eventos para bancos de dados nomeados.
- 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 Functions (1ª geração).
- Os eventos não entregues devido ao tamanho da solicitação são registrados nos registros da plataforma e contam para o 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 ao limite para a 1a geração..." de gravidade
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 Functions (2ª geração)
- Reduza o tamanho do documento
- Exclua o Cloud 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 Firestore no modo Datastore
O Eventarc não oferece suporte a multirregiões para acionadores de eventos do Firestore, mas ainda é possível criar gatilhos para bancos de dados do Firestore em locais multirregionais. O Eventarc mapeia os locais multirregionais do Firestore para as seguintes regiões do Eventarc:
Multirregião do Firestore | Região do Eventarc |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |
A seguir
- Saiba mais sobre arquiteturas orientadas a eventos.
- Consulte exemplos de código para o modo Datastore.