Gatilhos do Data Connect para Cloud Functions

Com Cloud Functions for Firebase, você pode lidar com eventos em Firebase Data Connect. Cloud Functions permite que você execute código do lado do servidor em resposta a eventos, como a execução de uma mutação em seu serviço Data Connect. Isso permite adicionar lógica personalizada sem precisar implantar seus próprios servidores.

Casos de uso comuns

  • Sincronização de dados: Replicar ou sincronizar dados com outros sistemas (como Cloud Firestore, BigQuery ou APIs externas) após a ocorrência de uma mutação.

  • Fluxos de trabalho assíncronos: Inicie processos de longa duração, como processamento de imagem ou agregação de dados, após uma alteração no banco de dados.

  • Engajamento do usuário: Envie e-mails ou Cloud Messaging notificações aos usuários após um evento de mutação específico em seu aplicativo, como a criação de uma conta.

Acionar uma função em uma mutação Data Connect

Você pode acionar uma função sempre que uma mutação Data Connect for executada usando o manipulador de eventos onMutationExecuted. Este gatilho ocorre na execução de uma mutação .

Uma função básica de evento de mutação

O exemplo básico a seguir é uma função que registra os detalhes de qualquer mutação executada em seu serviço Data Connect:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

export const logMutation = onMutationExecuted(
  {
    /* Trigger on all mutations, spanning all services and connectors
       in us-central1 */
  },
  (event) => {
    logger.info("A mutation was executed!", {
      data: event.data,
    });
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed()
def log_mutation(event: dataconnect_fn.Event):
  logger.info("A mutation was executed!", event.data)

Ao disparar todas as mutações do seu projeto, você não deve executar nenhuma mutação no manipulador de gatilho, caso contrário, você causará um loop infinito. Se você deseja realizar mutações em um gatilho de evento, use as opções de filtragem descritas abaixo e certifique-se de que a mutação não seja acionada por ela mesma.

Definir o local da função

A localização da função deve corresponder à localização do serviço Data Connect para que os eventos acionem a função. Por padrão, a região da função é us-central1.

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

export const onMutationRegionOption = onMutationExecuted(
  {
    region: "europe-west1"  // Set if Data Connect service location is not us-central1
  },
  (event) => { /* ... */ }
);

Python

@dataconnect_fn.on_mutation_executed(
  region="europe-west1"  # Set if Data Connect service location is not us-central1
)
def mutation_executed_handler_region_option(event: dataconnect_fn.Event):
  pass

Filtrar eventos

O manipulador onMutationExecuted pode ser configurado com opções para filtrar eventos com base em atributos específicos. Isso é útil quando você deseja ativar sua função apenas para determinadas mutações.

É possível filtrar por service, connector e operation:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

// Trigger this function only for the CreateUser mutation
// in the users connector of the myAppService service.
export const onUserCreate = onMutationExecuted(
  {
    service: "myAppService",
    connector: "users",
    operation: "CreateUser",
  },
  (event) => {
    logger.info("A new user was created!", event.data);
    // Add logic here: for example, sending a welcome email.
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  connector="users",
  operation="CreateUser"
):
def on_user_create(event: dataconnect_fn.Event):
  logger.info("A new user was created!", event.data)

Caracteres curinga e grupos de captura

Você pode usar curingas e grupos de captura para filtrar seus gatilhos com base em vários valores. Quaisquer grupos capturados estão disponíveis em event.params para uso. Consulte Entender os padrões de caminho para mais informações.

Exemplos:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

// Trigger on all operations that match the pattern `User*`, on any service and
// connector.
export const onMutationWildcards = onMutationExecuted(
  {
    operation: "User*",
  },
  (event) => {}
);

// Trigger on all operations that match the pattern `User*`, on any service and
// connector. Capture the operation name in the variable `op`.
export const onMutationCaptureWildcards = onMutationExecuted(
  {
    operation: "{op=User*}",
  },
  (event) => {
    // `event.params.op` contains the operation name.
  }
);

// Trigger on all operations on the service `myAppService`. Capture the
// operation name in the variable `operation`.
export const onMutationCaptures = onMutationExecuted(
  {
    service: "myAppService",
    operation: "{operation}",
  },
  (event) => {
    // `event.params.operation` contains the operation name.
  }
);

Python

from firebase_functions import dataconnect_fn

# Trigger on all operations that match the pattern `User*`, on any service and
# connector.
@dataconnect_fn.on_mutation_executed(
  operation="User*"
)
def on_mutation_wildcards(event: dataconnect_fn.Event):
  pass

# Trigger on all operations that match the pattern `User*`, on any service and
# connector. Capture the operation name in the variable `op`.
@dataconnect_fn.on_mutation_executed(
  operation="{op=User*}"
)
def on_mutation_capture_wildcards(event: dataconnect_fn.Event):
  # `event.params["op"]` contains the operation name.
  pass

# Trigger on all operations on the service `myAppService`. Capture the
# operation name in the variable `operation`.
@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  operation="{operation}"
)
def on_mutation_captures(event: dataconnect_fn.Event):
  # `event.params["operation"]` contains the operation name.
  pass

Acessar informações de autenticação do usuário

Você pode acessar informações de autenticação do usuário referentes à entidade que acionou o evento. Para obter mais informações sobre os dados disponíveis no contexto de autenticação, consulte Contexto de Autenticação.

O exemplo a seguir demonstra como recuperar informações de autenticação:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

export const onMutation = onMutationExecuted(
  { operation: "MyMutation" },
  (event) => {
    // mutationExecuted event provides authType and authId:
    // event.authType
    // event.authId
  }
);

Python

from firebase_functions import dataconnect_fn

@dataconnect_fn.on_mutation_executed(operation="MyMutation")
def mutation_executed_handler(event: dataconnect_fn.Event):
  # mutationExecuted event provides auth_type and auth_id, which are accessed as follows
  # event.auth_type
  # event.auth_id
  pass

O tipo de autenticação e o ID de autenticação serão preenchidos da seguinte forma:

Mutação iniciada por authtype authid
Usuário final autenticado app_user UID do token de autenticação do Firebase
Usuário final não autenticado unauthenticated vazio
SDK de administrador se passando por um usuário final app_user UID do token de autenticação do Firebase do usuário representado
O SDK de administração está se passando por uma solicitação não autenticada. unauthenticated vazio
SDK de administrador com permissões completas admin vazio

Acessar dados de eventos

O objeto CloudEvent passado para sua função contém informações sobre o evento que a desencadeou.

Atributos do evento

Atributo Tipo Descrição
id string Um identificador único para o evento.
source string O recurso de conector que gerou o evento (por exemplo, //firebasedataconnect.googleapis.com/projects/*/locations/*/services/*/connectors/*).
specversion string A versão de especificação CloudEvents (por exemplo, "1.0").
type string Tipo do evento: google.firebase.dataconnect.connector.v1.mutationExecuted.
time string O registro de data e hora (formato ISO 8601) de quando o evento foi produzido.
subject string Opcional. Informações adicionais sobre o contexto do evento, como o nome da operação.
params object Um mapa dos padrões de trajetória capturados.
authType string Uma enumeração que representa o tipo de entidade principal que desencadeou o evento.
authId string Um identificador único da entidade principal que desencadeou o evento.
data MutationEventData A carga útil do evento Data Connect. Consulte a próxima seção.

Carga útil de dados

O objeto MutationEventData contém a carga útil do evento Data Connect:

{
  // ...
  "authType": // ...
  "data": {
    "payload": {
      "variables": {
        "userId": "user123",
        "updateData": {
          "displayName": "New Name"
        }
      },
      "data": {
        "updateUser": {
          "id": "user123",
          "displayName": "New Name",
          "email": "user@example.com"
        }
      },
      "errors": []
    }
  }
}
  • payload.variablesUm objeto contendo as variáveis que foram passadas para a mutação.
  • payload.dataUm objeto contendo os dados retornados pela mutação.
  • payload.errors: Uma matriz contendo todos os erros que ocorreram durante a execução da mutação. Se a mutação for bem-sucedida, essa matriz ficará vazia.

Exemplo

Eis como você pode acessar as variáveis de mutação e os dados retornados:

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

export const processNewUserData = onMutationExecuted(
  {
    "service": "myAppService",
    "connector": "users",
    "operation": "CreateUser",
  },
  (event) => {
    // The variables passed to the mutation
    const mutationVariables = event.data.payload.variables;

    // The data returned by the mutation
    const returnedData = event.data.payload.data;

    logger.info("Processing mutation with variables:", mutationVariables);
    logger.info("Mutation returned:", returnedData);

    // ... your custom logic here
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  connector="users",
  operation="CreateUser"
):
def process_new_user_data(event: dataconnect_fn.Event):
  # The variables passed to the mutation
  mutation_vars = event.data.payload.variables
  # The data returned by the mutation
  returned_data = event.data.payload.data

  logger.info("Processing mutation with variables:", mutationVariables)
  logger.info("Mutation returned", returnedData)

  # ... your custom logic here

Note que, ao contrário de alguns outros gatilhos de banco de dados, como Cloud Firestore ou Realtime Database, o evento Data Connect não fornece um instantâneo "anterior" dos dados. Como o Data Connect encaminha solicitações ao banco de dados subjacente, o snapshot "antes" dos dados não pode ser obtido de maneira transacional. Em vez disso, você tem acesso aos argumentos enviados à mutação e aos dados que ela retornou.

Uma consequência disso é que você não pode usar a estratégia de comparar instantâneos "antes" e "depois" para evitar loops infinitos, nos quais um gatilho de evento dispara o mesmo evento. Se você precisar realizar uma mutação a partir de uma função desencadeada por um evento de mutação, utilize filtros de eventos e certifique-se de que nenhuma mutação possa ser desencadeada por si mesma, mesmo que indiretamente.