Confira tudo que foi anunciado no Firebase Summit e veja como usar o Firebase para acelerar o desenvolvimento de apps e executar os aplicativos com confiança. Saiba mais

Acionadores do Realtime Database

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

  1. Aguarda alterações em um determinado caminho do Realtime Database.
  2. Dispara quando um evento ocorre e executa suas tarefas.
  3. Recebe um objeto de dados que contém um instantâneo dos dados armazenados nesse caminho.

Você pode 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.

Acionar uma função nas alterações do Firebase Realtime Database

Use o subpacote firebase-functions/v2/database para criar uma função que manipula eventos do Firebase Realtime Database. Para controlar quando a função é acionada, especifique um dos manipuladores de eventos e especifique o caminho do Realtime Database onde ele escutará os eventos.

Definindo o local da função

A distância entre o local de uma instância do Realtime Database e o local da função pode criar uma latência de rede significativa. Além disso, uma incompatibilidade entre regiões pode resultar em falha de 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.

Manipulando eventos do Realtime Database

As funções permitem lidar com eventos do Realtime Database em dois níveis de especificidade; você pode ouvir especificamente apenas eventos de gravação, criação, atualização ou exclusão, ou pode ouvir qualquer alteração de qualquer tipo em uma referência.

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

  • onValueWritten() Acionado apenas quando os dados são gravados no Realtime Database.
  • onValueCreated() Acionado apenas quando os dados são criados no Realtime Database.
  • onValueUpdated() Acionado apenas quando os dados são atualizados no Realtime Database.
  • onValueDeleted() Acionado apenas quando os dados são excluídos no Realtime Database.

Especifique a instância e o caminho

Para controlar quando e onde sua função deve ser acionada, configure sua função com um caminho e, opcionalmente, uma instância do Realtime Database. Se você não especificar uma instância, a função será implantada em todas as instâncias do Realtime Database na região da função. Você também pode especificar um padrão de instância do Realtime Database para implantar em um subconjunto seletivo de instâncias na mesma região.

Por exemplo, usando onValueWritten() para ilustração:

# 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) => {
    // …
  }
);

Esses parâmetros direcionam sua função para lidar com gravações em um determinado caminho dentro da instância do Realtime Database.

As especificações de caminho correspondem a todas as gravações que tocam um caminho, incluindo gravações que ocorrem em qualquer lugar abaixo dele. Se você definir o caminho para sua função como /foo/bar , ele corresponderá aos eventos em ambos os 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 o uso de várias funções em caminhos mais profundos em vez de uma única função próxima à raiz de seu banco de dados. Para obter o melhor desempenho, solicite apenas dados no nível mais profundo possível.

Curinga e captura

Você pode usar {key} , {key=*} , {key=prefix*} , {key=*suffix} para capturar. * , prefix* , *suffix para caractere curinga de segmento único. Observação: ** representa caracteres curinga de vários segmentos, que o RTDB não suporta. Consulte Compreender os padrões de caminho .

Curinga de caminho. Você pode especificar um componente de caminho como um curinga:

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

Caminhos com curingas podem corresponder a vários eventos de, por exemplo, uma única gravação. Uma inserção de

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

corresponde ao caminho "/foo/*" duas vezes: uma vez com "hello": "world" e novamente com "firebase": "functions" .

Captura de caminho. Você pode capturar correspondências de caminho em variáveis ​​nomeadas para serem usadas em 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 de sua função.

Curinga de instância. Você também pode especificar um componente de instância usando caracteres curinga. Um curinga de instância pode ter prefixo, sufixo ou ambos (por exemplo my-app-*-prod ).

Curinga e referência de captura

Com o Cloud Functions (2ª geração) e o Realtime Database, um padrão pode ser usado ao especificar ref e instance . Cada interface de gatilho terá as seguintes opções para definir o escopo de uma função:

Especificando ref Especificando a instance Comportamento
Simples ( /foo/bar ) Não especificando Define o manipulador para todas as instâncias na região da função.
Simples ( /foo/bar ) Único ( 'my-new-db' ) Define o manipulador para a instância específica na região da função.
Simples ( /foo/bar ) Padrão ( 'inst-prefix*' ) Define o manipulador para todas as instâncias que correspondem ao padrão na região da função.
Padrão ( /foo/{bar} ) Não especificando Define o manipulador para todas as instâncias na região da função.
Padrão ( /foo/{bar} ) Único ( 'my-new-db' ) Define o manipulador para a instância específica na região da função.
Padrão ( /foo/{bar} ) Padrão ( 'inst-prefix*' ) Define o manipulador para todas as instâncias que correspondem ao padrão na região da função.

Processar dados de eventos

Ao manipular um evento do Realtime Database, o objeto de dados retornado é um DataSnapshot .

Para eventos onValueWritten ou onValueUpdated , o primeiro parâmetro é um objeto Change que contém dois instantâneos que representam o estado dos dados antes e depois do evento acionador.

Para eventos onValueCreated e onValueDeleted , o objeto de dados retornado é um instantâneo dos dados criados ou excluídos.

Neste exemplo, a função recupera o instantâneo para o caminho especificado foo/bar como snap , converte a string nesse local para letras maiúsculas e grava essa string modificada no banco de dados:

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
export makeuppercase = onValueCreated("foo/bar", (event) => {
      // Grab the current value of what was written to the Realtime Database.
      const original = event.data.val();
      functions.logger.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.ref.parent.child('uppercase').set(uppercase);
    });

Lendo o valor anterior

O objeto Change tem uma propriedade before que permite inspecionar o que foi salvo no Realtime Database antes do evento. A propriedade before retorna um DataSnapshot onde todos os métodos (por exemplo, val() e exists() ) referem-se ao valor anterior. Você pode ler o novo valor novamente usando o DataSnapshot original ou lendo a propriedade after . Esta propriedade em qualquer Change é outro DataSnapshot que representa o estado dos dados depois que o evento aconteceu.

Por exemplo, a propriedade before pode ser usada para garantir que a função apenas coloque o texto em letras maiúsculas quando for criada pela primeira vez:

    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);
        });