Esta página foi traduzida pela API Cloud Translation.

Ampliar o Datastore com o Cloud Functions (2nd gen)

Com o Cloud Functions e o Eventarc, é possível implantar códigos em processar eventos acionados por alterações em seu banco de dados do Firestore no modo Datastore; Isso permite que você adicione funcionalidades do lado do servidor sem precisar executar seus próprios servidores.

Gatilhos do modo Datastore

O Eventarc é compatível com o seguinte evento do Firestore no modo Datastore gatilhos para permitir a criação de gerenciadores do Cloud Functions (2nd gen) vinculados a Eventos do Firestore no modo Datastore:

Tipo de evento	Acionador
`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 gatilhos de evento do modo Datastore respondem apenas às alterações de entidade. Uma atualização para uma entidade do modo Datastore em que os dados não for inalterada (uma gravação em ambiente autônomo), não gera um evento de atualização ou gravação. Você não pode gerar eventos somente para propriedades específicas.

Inclua o contexto de autenticação no evento

Para incluir outras informações de autenticação sobre o evento, use um evento com a extensão withAuthContext. Esta extensão agrega informações sobre o principal que acionou o evento. Ele adiciona Atributos authtype e authid, além das informações retornadas nos o evento base. Consulte a authcontext para mais informações sobre valores de atributos.

Escrever uma função acionada por entidade

Para escrever uma função que responda aos eventos do Firestore no modo Datastore, prepare-se para especificar o seguinte durante a implantação:

um tipo de evento acionador
um filtro de evento de gatilho para selecionar as entidades associadas à função
o código da função a ser executada

Acionar filtros de eventos

Ao especificar um filtro de evento, é possível especificar uma entidade exata ou um padrão de caminho. Use um padrão de caminho para corresponder a diversas entidades os caracteres curinga * ou **.

Por exemplo, você pode especificar uma correspondência de entidade exata para responder a alterações no seguinte entidade:

users/marie

Use caracteres curinga, * ou **, para responder a mudanças em entidades que correspondem a um padrão. O caractere curinga * corresponde a um único segmento. 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 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 de 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

A seção descreve situações que exigem o escape de caracteres em IDs de tipo e de entidade. O escape de um caractere permite que o evento filtre corretamente interpretar o ID.

Se um ID de tipo ou de entidade incluir um caractere ~ ou /, será necessário no ID do seu 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 ~ e Caracteres / substituídos por seus IDs de codificação, que são os seguintes:
- ~: ~0
- /: ~1
Por exemplo, o ID de tipo user/profile torna-se __escusers~1profile__. Um o padrão de caminho do exemplo com esse ID de tipo é __escusers~1profile__/{userId}
Se você usar o ID de tipo ou de entidade de . ou .. no seu filtro de eventos, é necessário fazer o escape do ID da seguinte forma:
- .: __esc~2__
- ..: __esc~2~2__
Será necessário usar escape para o caractere . somente se o ID for exatamente . ou ... Por exemplo, o ID de tipo customers.info não requer escape.
Se o ID de tipo ou entidade for um valor numérico em vez de um valor de string, é necessário fazer o escape do ID com __idNUMERIC_VALUE__. Por exemplo, o padrão de caminho de uma entidade do tipo 111 e o ID de entidade 222. é __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 fazer o escape desses IDs com __bytesBASE64_ENCODING__. Substitua BASE64_ENCODING pela codificação base64 do ID. Para exemplo, o padrão de caminho Task/{task} com escape para o ID do tipo não UTF8 Task se torna __bytesVGFzaw==__/{task}.

Exemplos de funções

O exemplo a seguir demonstra como receber eventos do modo Datastore. Para trabalhar com os dados de um evento, consulte as value e old_value.

value: um objeto EntityResult que contém um snapshot de entidade pós-operação. Este campo não é preenchido para eventos de exclusão.
old_value: um objeto EntityResult que contém uma entidade de pré-operação. snapshot. 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 no modo Datastore. Para mais informações, consulte a API Java do modo Datastore documentação de referência.

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.

import com.google.cloud.functions.CloudEventsFunction;
import com.google.events.cloud.datastore.v1.EntityEventData;
import com.google.protobuf.InvalidProtocolBufferException;
import io.cloudevents.CloudEvent;
import java.util.logging.Logger;

public class Datastore implements CloudEventsFunction {
  private static final Logger logger = Logger.getLogger(Datastore.class.getName());

  @Override
  public void accept(CloudEvent event) throws InvalidProtocolBufferException {
    EntityEventData datastoreEventData = EntityEventData.parseFrom(event.getData().toBytes());

    logger.info("Function triggered by event on: " + event.getSource());
    logger.info("Event type: " + event.getType());

    logger.info("Old value:");
    logger.info(datastoreEventData.getOldValue().toString());

    logger.info("New value:");
    logger.info(datastoreEventData.getValue().toString());
  }
}

Incluir as dependências do proto na origem

Você precisa incluir o modo Datastore data.proto no diretório de origem da função. Esse arquivo importa o seguinte: 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 tem não incluir esses arquivos, ele retornará um erro quando for executado.

Atributos do evento

Cada evento inclui atributos de dados que incluem informações sobre o evento, como o horário em que ele foi acionado. O Firestore no modo Datastore adiciona outros dados sobre o banco de dados e a entidade envolvidas no evento. Acesse esses atributos da seguinte forma:

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.

Ativar 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 uma nome da função. Em seguida, adicione as seguintes sinalizações:
- 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 a banco de dados do Firestore. Se o banco de dados do Firestore for em um local multirregional, defina o valor como us-central1 para bancos de dados em nam5 e para europe-west4 para bancos de dados em eur3. Para regional Locais do Firestore, definidos para a mesma região.
- O --trigger-location=TRIGGER_LOCATION especifica o local do acionador. Defina TRIGGER_LOCATION como o local do banco de dados do modo Datastore.
- A sinalização --runtime=RUNTIME especifica o ambiente de execução da linguagem que a função usa. Cloud Functions. oferece 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 o seguinte: para mais detalhes:
  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. Isso é o código que a função executa quando é executada. Você deve definir CODE_ENTRYPOINT como um nome de função ou uma classe totalmente qualificada que existe em seu código-fonte. Consulte Ponto de entrada da função para mais informações.
- O --trigger-event-filters as flags definem o filtro de eventos, que inclui o tipo de gatilho e a entidade ou o caminho que aciona os eventos. Configure os seguintes valores de atributo para definir seu filtro de eventos:
  - type=EVENT_FILTER_TYPE: Firestore oferece suporte aos seguintes tipos de evento:
    - 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 seja 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 foi enviado quando um documento é gravado pela primeira vez e o evento inclui outras informações de autenticação
    - google.cloud.datastore.entity.v1.updated.withAuthContext: o evento foi enviado quando um documento já existe e tem algum valor alterado. Inclui outras informações de autenticação
    - google.cloud.datastore.entity.v1.deleted.withAuthContext: o evento foi enviado quando um documento é excluído. Inclui informações extras de autenticação
    - google.cloud.datastore.entity.v1.written.withAuthContext: o evento foi enviado quando um documento é criado, atualizado ou excluído e um evento. Inclui outras informações de autenticação
    Defina EVENT_FILTER_TYPE como um desses tipos de evento.
  - database=DATABASE: o banco de dados do Firestore. Para o nome do banco de dados padrão, defina DATABASE como (default).
  - namespace=NAMESPACE: o banco de dados. namespace. Para o padrão Nome do banco de dados, defina NAMESPACE como (default). Remover a sinalização para corresponder a qualquer namespace.
    
    Observação: defina exatamente como (default) para o namespace padrão. Isso é um nome de recurso não canônico usado apenas para o Eventarc. Não Defina como [default], conforme mostrado no console do Google Cloud.
  - entity=ENTITY_OR_PATH: o caminho do banco de dados que aciona eventos quando os dados são criados, atualizados ou excluída. 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.
  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-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:

O pré-requisito do Cloud 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 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 Functions (2ª geração). O Cloud 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 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 campo functionName. Se o campo receiveTimestamp 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 do Firestore no modo Datastore

O Eventarc não oferece suporte a multirregiões para o evento do Firestore mas ainda é possível criar gatilhos para bancos de dados do Firestore em locais multirregionais. Mapas do Eventarc no Firestore locais multirregionais 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.