Expanda o Datastore com as Cloud Functions (2.ª geração)

Com as funções do Cloud Run e o Eventarc, pode implementar código para processar eventos acionados por alterações na sua base de dados do Firestore no modo Datastore. Isto permite-lhe adicionar funcionalidades do lado do servidor sem executar os seus próprios servidores.

Acionadores do modo Datastore

O Eventarc suporta os seguintes acionadores de eventos do Firestore no modo Datastore para lhe permitir criar controladores de funções do Cloud Run (2.ª geração) associados a eventos do Firestore no modo Datastore:

Tipo de evento Acionador
google.cloud.datastore.entity.v1.created Acionado quando uma entidade é escrita 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 é eliminada.
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 eventos do modo Datastore só respondem a alterações de entidades. Uma atualização a uma entidade do modo Datastore em que os dados permanecem inalterados (uma gravação sem operação) não gera um evento de atualização ou gravação. Não pode gerar eventos apenas para propriedades específicas.

Inclua o contexto de autenticação no evento

Para incluir informações de autenticação adicionais sobre o evento, use um acionador de evento com a extensão withAuthContext. Esta extensão adiciona informações adicionais sobre o principal que acionou o evento. Adiciona os atributos authtype e authid, além das informações devolvidas no evento base. Consulte a referência authcontext para mais informações sobre os valores dos atributos.

Escreva uma função acionada por entidades

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

  • um tipo de evento do acionador
  • Um filtro de eventos do acionador para selecionar as entidades associadas à função
  • O código da função a executar

Filtros de eventos de acionador

Quando especifica um filtro de eventos, pode especificar uma correspondência exata de uma entidade ou um padrão de caminho. Use um padrão de caminho para fazer corresponder várias entidades com os carateres universais * ou **.

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

users/marie

Use carateres universais, * ou **, para responder a alterações nas entidades que correspondem a um padrão. O caráter universal * corresponde a um único segmento e o caráter universal de vários segmentos ** corresponde a zero ou mais segmentos no padrão.

Para correspondências de segmento único (*), também pode usar um grupo de captura com nome, como users/{userId}.

A tabela seguinte demonstra padrões de caminhos 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 caminhos, consulte o artigo Padrões de caminhos do Eventarc.

O acionador tem de apontar sempre para uma entidade, mesmo que esteja a usar um caráter universal. Veja os exemplos seguintes:

  • users/{userId=*}/{messages=*} não é válido porque {messages=*} é um ID de tipo.

  • users/{userId=*}/{messages}/{messageId=*} é válido porque {messageId=*} aponta sempre para uma entidade.

Carateres de escape

Esta secção descreve situações que requerem que escape carateres em IDs de tipo e IDs de entidades. A anulação de um caráter permite que o filtro de eventos interprete corretamente o ID.

  • Se um ID de tipo ou um ID de entidade incluir um caráter ~ ou /, tem de escapar o ID no filtro de eventos. Para escapar um ID, use o formato __escENCODED_ID__. Substitua ENCODED_ID por um ID de tipo ou um ID de entidade que tenha todos os carateres ~ e / substituídos pelos respetivos IDs de codificação, que são os seguintes:

    • ~: ~0
    • /: ~1

    Por exemplo, o ID do tipo user/profile torna-se __escusers~1profile__. Um exemplo de padrão de caminho com este ID de tipo é __escusers~1profile__/{userId}

  • Se usar o ID do tipo ou o ID da entidade de . ou .. no filtro de eventos, tem de usar carateres de escape no ID da seguinte forma:

    • .: __esc~2__
    • ..: __esc~2~2__

    Só tem de usar o caráter de escape . se o ID for exatamente . ou ... Por exemplo, o ID do tipo customers.info não requer a utilização de carateres de escape.

  • Se o tipo ou o ID da entidade for um valor numérico em vez de um valor de string, tem de usar o caráter de escape __idNUMERIC_VALUE__ no ID. Por exemplo, o padrão do caminho para uma entidade do tipo 111 e ID da entidade 222 é __id111__/__id222__.

  • Se migrou do Cloud Datastore antigo para o Firestore no modo Datastore, a sua base de dados pode conter IDs antigos numa codificação não UTF-8. Tem de usar o caráter de escape __bytesBASE64_ENCODING__ nestes IDs. Substitua BASE64_ENCODING pela codificação base-64 do ID. Por exemplo, o padrão do caminho Task/{task} com carateres de escape para o ID do tipo não UTF8 Task torna-se __bytesVGFzaw==__/{task}.

Exemplos de funções

O exemplo seguinte demonstra como receber eventos do modo Datastore. Para trabalhar com os dados envolvidos num evento, consulte os campos value e old_value.

  • value: um objeto EntityResult que contém uma captura de ecrã da entidade pós-operação. Este campo não é preenchido para eventos de eliminação.
  • old_value: um objeto EntityResult que contém uma captura instantânea da entidade de pré-operação. Este campo só é preenchido para eventos de atualização e eliminação.

Java

Para saber como instalar e usar a biblioteca cliente para o modo Datastore, consulte o artigo Bibliotecas 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 as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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());
  }
}

Inclua as dependências proto na sua origem

Tem de incluir o ficheiro Datastore mode data.proto no diretório de origem da sua função. Este ficheiro importa os seguintes protos, que também tem de incluir no diretório de origem:

Use a mesma estrutura de diretórios para as dependências. Por exemplo, coloque struct.proto dentro de google/protobuf.

Estes ficheiros são necessários para descodificar os dados de eventos. Se a origem da função não incluir estes ficheiros, devolve um erro quando é executada.

Atributos de eventos

Cada evento inclui atributos de dados que incluem informações sobre o evento, como a hora em que o evento foi acionado. O Firestore no modo Datastore adiciona dados adicionais sobre a base de dados e a entidade envolvida no evento. Pode aceder a estes 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"));

Implemente uma função

Os utilizadores que implementam funções do Cloud Run têm de ter a função do IAM Programador de funções do Cloud Run ou uma função que inclua as mesmas autorizações. Consulte também a secção Configuração adicional para implementação.

Pode implementar uma função através da CLI gcloud ou da Google Cloud consola. O exemplo abaixo demonstra a implementação com a CLI gcloud. Para ver detalhes sobre a implementação com a Google Cloud consola, consulte o artigo Implemente funções do Cloud Run.

  1. In the Google Cloud console, activate Cloud Shell.

    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.

  2. Use o comando gcloud functions deploy para implementar 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 implementada. O nome da função tem de começar com uma letra, seguida de até 62 letras, números, hífenes ou 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 flag --gen2 especifica que quer fazer a implementação nas funções do Cloud Run (2.ª geração). Se omitir esta flag, a implementação é feita em funções do Cloud Run (1.ª geração).

    • A flag --region=FUNCTION_LOCATION especifica a região na qual implementar a sua função.

      Para maximizar a proximidade, defina FUNCTION_LOCATION para uma região perto da sua base de dados do Firestore. Se a sua base de dados do Firestore estiver numa localização multirregional, defina o valor como us-central1 para bases de dados em nam5 e como europe-west4 para bases de dados em eur3. Para localizações do Firestore regionais, defina a mesma região.

    • A flag --trigger-location=TRIGGER_LOCATION especifica a localização do acionador. Tem de definir TRIGGER_LOCATION para a localização da sua base de dados do modo Datastore.

    • A flag --runtime=RUNTIME especifica o tempo de execução do idioma que a sua função usa. As funções do Cloud Run suportam vários tempos de execução. Consulte a secção Tempos de execução para mais informações. Defina o RUNTIME para um tempo de execução suportado.

    • A flag --source=SOURCE_LOCATION especifica a localização do código-fonte da sua função. Para ver detalhes, consulte o seguinte:

      Defina SOURCE_LOCATION para a localização do código-fonte da sua função.

    • A flag --entry-point=CODE_ENTRYPOINT especifica o ponto de entrada para a sua função no código-fonte. Este é o código que a sua função executa quando é executada. Tem de definir CODE_ENTRYPOINT para um nome de função ou um nome de classe totalmente qualificado que exista no seu código-fonte. Consulte o 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 acionador e a entidade ou o caminho que aciona os eventos. Defina os seguintes valores de atributos para definir o filtro de eventos:

      • type=EVENT_FILTER_TYPE: o Firestore suporta os seguintes tipos de eventos:

        • google.cloud.datastore.entity.v1.created: o evento é enviado quando uma entidade é escrita 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 é eliminada.
        • google.cloud.datastore.entity.v1.written: o evento é enviado quando uma entidade é criada, atualizada ou eliminada.
        • google.cloud.datastore.entity.v1.created.withAuthContext: o evento é enviado quando um documento é escrito pela primeira vez e o evento inclui informações de autenticação adicionais
        • google.cloud.datastore.entity.v1.updated.withAuthContext: o evento é enviado quando já existe um documento e qualquer valor é alterado. Inclui informações de autenticação adicionais
        • google.cloud.datastore.entity.v1.deleted.withAuthContext: event is sent when a document is deleted. Inclui informações de autenticação adicionais
        • google.cloud.datastore.entity.v1.written.withAuthContext: o evento é enviado quando um documento é criado, atualizado ou eliminado e event. Inclui informações de autenticação adicionais

        Defina EVENT_FILTER_TYPE para um destes tipos de eventos.

      • database=DATABASE: a base de dados do Firestore. Para o nome da base de dados predefinido, defina DATABASE como (default).

      • namespace=NAMESPACE: o espaço de nomes da base de dados. Para o nome da base de dados predefinido, defina NAMESPACE como (default). Remova a flag para corresponder a qualquer espaço de nomes.

        .

      • entity=ENTITY_OR_PATH: o caminho da base de dados que aciona eventos quando os dados são criados, atualizados ou eliminados. Os valores aceites para ENTITY_OR_PATH são:

        • Igual; por exemplo, --trigger-event-filters="entity='users/marie'"
        • Padrão de caminho; por exemplo, --trigger-event-filters-path-pattern="entity='users/*'". Para mais informações, consulte o artigo Compreenda os padrões de caminhos.

      Opcionalmente, pode especificar opções adicionais de configuração, rede e segurança quando implementa uma função.

      Para uma referência completa sobre o comando de implementação e as respetivas flags, consulte a gcloud functions deploy documentação.

    3. Exemplos de implementações

    Os exemplos seguintes demonstram implementações com a CLI Google Cloud.

    Implemente uma função para uma base 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}'"

    Implemente uma função para uma base de dados na nam5multirregião:

    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

    Tenha em atenção as seguintes limitações para acionadores do Firestore para funções do Cloud Run:

    • As funções do Cloud Run (1.ª geração) requerem uma base de dados "(default)" existente no modo nativo do Firestore. Não suporta bases de dados com nome do Firestore nem o modo Datastore. Use as funções do Cloud Run (2.ª geração) para configurar eventos nesses casos.
    • A ordenação não é garantida. As alterações rápidas podem acionar invocações de funções numa ordem inesperada.
    • Os eventos são entregues, pelo menos, uma vez, mas um único evento pode resultar em várias invocações de funções. Evite depender de mecanismos de execução única e escreva funções idempotentes.
    • O Firestore no modo Datastore requer funções do Cloud Run (2.ª geração). As funções do Cloud Run (1.ª geração) não suportam o modo Datastore.
    • Um acionador está associado a uma única base de dados. Não pode criar um acionador que corresponda a várias bases de dados.
    • A eliminação de uma base de dados não elimina automaticamente os acionadores dessa base de dados. O acionador deixa de enviar eventos, mas continua a existir até eliminar o acionador.
    • Se um evento correspondente exceder o tamanho máximo do pedido, o evento pode não ser entregue às funções do Cloud Run (1.ª geração).
      • Os eventos não entregues devido ao tamanho do pedido são registados nos registos da plataforma e contam para a utilização de registos do projeto.
      • Pode encontrar estes registos no Explorador de registos com a mensagem "Event cannot deliver to Cloud function due to size exceeding the limit for 1st gen..." de error gravidade. Pode encontrar o nome da função no campo functionName. Se o campo receiveTimestamp ainda estiver dentro de uma hora a partir de agora, pode inferir o conteúdo real do evento lendo o documento em questão com uma captura de ecrã antes e depois da data/hora.
      • Para evitar esta cadência, pode:
        • Migre e atualize para as funções do Cloud Run (2.ª geração)
        • Reduza o tamanho do documento
        • Elimine as funções do Cloud Run em questão
      • Pode desativar o próprio registo através de exclusões, mas tenha em atenção que os eventos ofensivos continuam a não ser enviados.

    Localizações do Eventarc e do Firestore no modo Datastore

    O Eventarc não suporta várias regiões para acionadores de eventos do Firestore, mas ainda pode criar acionadores para bases de dados do Firestore em localizações de várias regiões. O Eventarc mapeia localizações multirregionais do Firestore para as seguintes regiões do Eventarc:

    Multirregião do Firestore Região do Eventarc
    nam5 us-central1
    eur3 europe-west4

    O que se segue?