O Firebase vai estar de volta no Cloud Next de 9 a 11 de abril. Inscreva-se agora.

Ampliar o Realtime Database com o Cloud Functions

Com o Cloud Functions, é possível processar eventos no Firebase Realtime Database sem precisar atualizar o código do cliente. Com o Cloud Functions, é possível executar operações do Realtime Database com todos os privilégios de administrador e garantir que cada alteração no Realtime Database seja processada individualmente. É possível fazer alterações no Firebase Realtime Database usando o snapshot dos dados ou o SDK Admin.

Em um ciclo de vida típico, uma função do Firebase Realtime Database faz o seguinte:

Espera alterações em um caminho específico do Realtime Database.
É acionada quando um evento ocorre e realiza as tarefas dela.
Recebe um objeto de dados que contém um snapshot dos dados armazenados naquele caminho.

É possível acionar uma função em resposta à gravação, criação, atualização ou exclusão de nós de banco de dados no Firebase Realtime Database. Para controlar quando a função é acionada, especifique um dos manipuladores de eventos e o caminho do Realtime Database em que ela vai detectar eventos.

Como definir o local da função

A distância entre os locais da instância do Realtime Database e da função pode criar uma latência de rede significativa. Além disso, uma incompatibilidade entre as regiões pode resultar em uma falha na implantação. Para evitar essas situações, especifique o local da função para que corresponda ao local da instância do banco de dados.

Como lidar com eventos do Realtime Database

O Functions processa os eventos do Realtime Database em dois níveis de especificidade. É possível detectar especificamente apenas eventos de gravação, criação, atualização ou exclusão ou detectar alterações de qualquer tipo em uma referência.

Estes gerenciadores para responder a eventos do Realtime Database estão disponíveis:

Node.js

onValueWritten(): acionado quando dados são criados, atualizados ou excluídos no Realtime Database.
onValueCreated(): acionado apenas quando dados são criados no Realtime Database.
onValueUpdated(): acionado apenas quando dados são atualizados no Realtime Database.
onValueDeleted(): acionado apenas quando dados são excluídos do Realtime Database.

Python

on_value_written(): acionado quando dados são criados, atualizados ou excluídos no Realtime Database.
on_value_created(): acionado apenas quando dados são criados no Realtime Database.
on_value_updated(): acionado apenas quando dados são atualizados no Realtime Database.
on_value_deleted(): acionado apenas quando dados são excluídos do Realtime Database.

Importar módulos obrigatórios

Na fonte da função, você precisa importar os módulos do SDK que quer usar. Para essa amostra, é necessário importar módulos HTTP e do Realtime Database com o módulo do Firebase Admin SDK para realizar gravações no Realtime Database.

Node.js

// The Cloud Functions for Firebase SDK to setup triggers and logging.
const {onRequest} = require("firebase-functions/v2/https");
const {onValueCreated} = require("firebase-functions/v2/database");
const {logger} = require("firebase-functions");

// The Firebase Admin SDK to access the Firebase Realtime Database.
const admin = require("firebase-admin");
admin.initializeApp();index.js

Python

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import db_fn, https_fn

# The Firebase Admin SDK to access the Firebase Realtime Database.
from firebase_admin import initialize_app, db

app = initialize_app()main.py

Especificar a instância e o caminho

Para controlar quando e onde a função deve ser acionada, faça a configuração dela com um caminho e, se preferir, com uma instância do Realtime Database. Se você não especificar uma instância, a função vai detectar todas as instâncias do Realtime Database na região da função. Também é possível especificar um padrão de instância do Realtime Database para implantação em um subconjunto seletivo de instâncias na mesma região.

Por exemplo:

Node.js

// All Realtime Database instances in default function region us-central1 at path "/user/{uid}"
// There must be at least one Realtime Database present in us-central1.
const onWrittenFunctionDefault = onValueWritten("/user/{uid}", (event) => {
  // …
});

// Instance named "my-app-db-2", at path "/user/{uid}".
// The "my-app-db-2" instance must exist in this region.
const OnWrittenFunctionInstance = onValueWritten(
  {
    ref: "/user/{uid}",
    instance: "my-app-db-2"
    // This example assumes us-central1, but to set location:
    // region: "europe-west1"
  },
  (event) => {
    // …
  }
);

// Instance with "my-app-db-" prefix, at path "/user/{uid}", where uid ends with @gmail.com.
// There must be at least one Realtime Database with "my-app-db-*" prefix in this region.
const onWrittenFunctionInstance = onValueWritten(
  {
    ref: "/user/{uid=*@gmail.com}",
    instance: "my-app-db-*"
    // This example assumes us-central1, but to set location:
    // region: "europe-west1"
  },
  (event) => {
    // …
  }
);

Python

# All Realtime Database instances in default function region us-central1 at path "/user/{uid}"
# There must be at least one Realtime Database present in us-central1.
@db_fn.on_value_written(r"/user/{uid}")
def onwrittenfunctiondefault(event: db_fn.Event[db_fn.Change]):
    # ...
    pass

# Instance named "my-app-db-2", at path "/user/{uid}".
# The "my-app-db-2" instance must exist in this region.
@db_fn.on_value_written(
    reference=r"/user/{uid}",
    instance="my-app-db-2",
    # This example assumes us-central1, but to set location:
    # region="europe-west1",
)
def on_written_function_instance(event: db_fn.Event[db_fn.Change]):
    # ...
    pass

# Instance with "my-app-db-" prefix, at path "/user/{uid}", where uid ends with @gmail.com.
# There must be at least one Realtime Database with "my-app-db-*" prefix in this region.
@db_fn.on_value_written(
    reference=r"/user/{uid=*@gmail.com}",
    instance="my-app-db-*",
    # This example assumes us-central1, but to set location:
    # region="europe-west1",
)
def on_written_function_instance(event: db_fn.Event[db_fn.Change]):
    # ...
    pass

Esses parâmetros direcionam a função para lidar com as gravações feitas em um determinado caminho na instância do Realtime Database.

As especificações de caminho correspondem a todas as gravações realizadas em um caminho, incluindo as que ocorrem em qualquer lugar abaixo dele. Se você definir o caminho para sua função como /foo/bar, ele vai corresponder aos eventos nestes dois locais:

 /foo/bar
 /foo/bar/baz/really/deep/path

Em ambos os casos, o Firebase interpreta que o evento ocorre em /foo/bar, e os dados do evento incluem os dados antigos e novos em /foo/bar. Se os dados do evento forem grandes, considere usar várias funções em caminhos mais profundos em vez de uma única função próxima à raiz do banco de dados. Para ter o melhor desempenho, solicite dados no nível mais profundo possível.

Caracteres curinga e captura

Use {key}, {key=*}, {key=prefix*}, {key=*suffix} para fazer a captura. *, prefix*, *suffix para caracteres curinga em segmento único. Observação: ** representa caracteres curinga com vários segmentos, que não são compatíveis com o Realtime Database. Consulte Entender os padrões de caminho.

Caracteres curinga de caminho. É possível especificar um componente de caminho como caractere curinga:

Usando asterisco, *. Por exemplo, foo/* corresponde a qualquer nível filho da hierarquia de nós abaixo de foo/.
Usando um segmento que contenha exatamente o asterisco, *. Por exemplo: foo/app*-us corresponde a qualquer segmento filho abaixo de foo/ com o prefixo app e o sufixo -us.

Os caminhos com caracteres curinga podem corresponder a vários eventos, como uma única gravação. Uma inserção de

{
  "foo": {
    "hello": "world",
    "firebase": "functions"
  }
}

corresponde ao caminho "/foo/*" duas vezes: em "hello": "world" e depois em "firebase": "functions".

Captura de caminho. É possível capturar correspondências de caminho em variáveis nomeadas que serão usadas no seu código de função (por exemplo, /user/{uid}, /user/{uid=*-us}).

Os valores das variáveis de captura estão disponíveis no objeto database.DatabaseEvent.params da sua função.

Caracteres curinga de instância. Também é possível especificar um componente de instância usando caracteres curinga. Um caractere curinga de instância pode ter prefixo, sufixo ou ambos (por exemplo, my-app-*-prod).

Referência de caracteres curinga e de captura.

Com o Cloud Functions (2ª geração) e o Realtime Database, é possível usar um padrão ao especificar ref e instance. Cada interface de gatilho terá as opções a seguir de escopo de uma função:

Como especificar `ref`	Como especificar `instance`	Comportamento
Única (`/foo/bar`)	Não especificado	Gerenciador de escopos para todas as instâncias na região da função.
Única (`/foo/bar`)	Única (`‘my-new-db'`)	Gerenciador de escopos da instância específica na região da função.
Única (`/foo/bar`)	Padrão (`‘inst-prefix*'`)	Gerenciador de escopos para todas as instâncias que correspondem ao padrão na região da função.
Padrão (`/foo/{bar}`)	Não especificado	Gerenciador de escopos para todas as instâncias na região da função.
Padrão (`/foo/{bar}`)	Única (`‘my-new-db'`)	Gerenciador de escopos da instância específica na região da função.
Padrão (`/foo/{bar}`)	Padrão (`‘inst-prefix*'`)	Gerenciador de escopos para todas as instâncias que correspondem ao padrão na região da função.

Processar dados de eventos

Quando um evento do Realtime Database é acionado, ele transmite um objeto Event para a função do gerenciador. Esse objeto tem uma propriedade data que, para eventos de criação e exclusão, contém um snapshot dos dados criados ou excluídos.

No exemplo em questão, a função recupera os dados do caminho referenciado, converte a string no local para caixa alta e grava a string modificada no banco de dados:

Node.js

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
// for all databases in 'us-central1'
exports.makeuppercase = onValueCreated(
    "/messages/{pushId}/original",
    (event) => {
    // Grab the current value of what was written to the Realtime Database.
      const original = event.data.val();
      logger.log("Uppercasing", event.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing
      // asynchronous tasks inside a function, such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the
      // Realtime Database returns a Promise.
      return event.data.ref.parent.child("uppercase").set(uppercase);
    },
);index.js

Python

@db_fn.on_value_created(reference="/messages/{pushId}/original")
def makeuppercase(event: db_fn.Event[Any]) -> None:
    """Listens for new messages added to /messages/{pushId}/original and
    creates an uppercase version of the message to /messages/{pushId}/uppercase
    """

    # Grab the value that was written to the Realtime Database.
    original = event.data
    if not isinstance(original, str):
        print(f"Not a string: {event.reference}")
        return

    # Use the Admin SDK to set an "uppercase" sibling.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    parent = db.reference(event.reference).parent
    if parent is None:
        print("Message can't be root node.")
        return
    parent.child("uppercase").set(upper)main.py

Como ler o valor anterior

Para eventos write ou update, a propriedade data é um objeto Change que contém dois snapshots que representam o estado dos dados antes e depois do evento de acionamento. O objeto Change tem uma propriedade before que permite a inspeção do que foi salvo no Realtime Database antes do evento e uma propriedade after que representa o estado dos dados após o evento.

Por exemplo, a propriedade before pode ser usada para garantir que a função só transcreva texto em caixa alta quando ele é criado pela primeira vez:

Node.js

  exports makeUppercase = onValueWritten("/messages/{pushId}/original", (event) => {
        // Only edit data when it is first created.
        if (event.data.before.exists()) {
          return null;
        }
        // Exit when the data is deleted.
        if (!event.data.after.exists()) {
          return null;
        }
        // Grab the current value of what was written to the Realtime Database.
        const original = event.data.after.val();
        console.log('Uppercasing', event.params.pushId, original);
        const uppercase = original.toUpperCase();
        // You must return a Promise when performing asynchronous tasks inside a Functions such as
        // writing to the Firebase Realtime Database.
        // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
        return event.data.after.ref.parent.child('uppercase').set(uppercase);
      });

Python

@db_fn.on_value_written(reference="/messages/{pushId}/original")
def makeuppercase2(event: db_fn.Event[db_fn.Change]) -> None:
    """Listens for new messages added to /messages/{pushId}/original and
    creates an uppercase version of the message to /messages/{pushId}/uppercase
    """

    # Only edit data when it is first created.
    if event.data.before is not None:
        return

    # Exit when the data is deleted.
    if event.data.after is None:
        return

    # Grab the value that was written to the Realtime Database.
    original = event.data.after
    if not hasattr(original, "upper"):
        print(f"Not a string: {event.reference}")
        return

    # Use the Admin SDK to set an "uppercase" sibling.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    parent = db.reference(event.reference).parent
    if parent is None:
        print("Message can't be root node.")
        return
    parent.child("uppercase").set(upper)main.py