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 Cloud Firestore

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

Com o Cloud Functions, você pode lidar com eventos no Cloud Firestore sem precisar atualizar o código do cliente. Você pode fazer alterações no Cloud Firestore por meio da interface DocumentSnapshot ou do Admin SDK .

Em um ciclo de vida típico, uma função do Cloud Firestore faz o seguinte:

  1. Aguarda alterações em um determinado documento.
  2. Aciona quando um evento ocorre e executa suas tarefas (consulte O que posso fazer com o Cloud Functions? para obter exemplos de casos de uso).
  3. Recebe um objeto de dados que contém um instantâneo dos dados armazenados no documento especificado. Para eventos onWrite ou onUpdate , o objeto de dados contém dois instantâneos que representam o estado dos dados antes e depois do evento de disparo.

A distância entre o local da instância do Firestore e o local da função pode criar uma latência de rede significativa. Para otimizar o desempenho, considere especificar o local da função onde aplicável.

Gatilhos de função do Cloud Firestore

O SDK do Cloud Functions para Firebase exporta um objeto functions.firestore que permite criar gerenciadores vinculados a eventos específicos do Cloud Firestore.

Tipo de evento Desencadear
onCreate Acionado quando um documento é gravado pela primeira vez.
onUpdate Acionado quando um documento já existe e tem algum valor alterado.
onDelete Acionado quando um documento com dados é excluído.
onWrite Acionado quando onCreate , onUpdate ou onDelete é acionado.

Se você ainda não tiver um projeto habilitado para Cloud Functions para Firebase, leia Get Started: Write and Deploy Your First Functions para configurar e definir seu projeto Cloud Functions para Firebase.

Como escrever funções acionadas pelo Cloud Firestore

Definir um gatilho de função

Para definir um gatilho do Cloud Firestore, especifique um caminho de documento e um tipo de evento:

Node.js

const functions = require('firebase-functions');

exports.myFunction = functions.firestore
  .document('my-collection/{docId}')
  .onWrite((change, context) => { /* ... */ });

Os caminhos do documento podem fazer referência a um documento específico ou a um padrão curinga .

Especificar um único documento

Se você deseja acionar um evento para qualquer alteração em um documento específico, pode usar a seguinte função.

Node.js

// Listen for any change on document `marie` in collection `users`
exports.myFunctionName = functions.firestore
    .document('users/marie').onWrite((change, context) => {
      // ... Your code here
    });

Especifique um grupo de documentos usando curingas

Se você deseja anexar um gatilho a um grupo de documentos, como qualquer documento em uma determinada coleção, use um {wildcard} no lugar do ID do documento:

Node.js

// Listen for changes in all documents in the 'users' collection
exports.useWildcard = functions.firestore
    .document('users/{userId}')
    .onWrite((change, context) => {
      // If we set `/users/marie` to {name: "Marie"} then
      // context.params.userId == "marie"
      // ... and ...
      // change.after.data() == {name: "Marie"}
    });

Neste exemplo, quando qualquer campo em qualquer documento em users é alterado, ele corresponde a um curinga chamado userId .

Se um documento em users tiver subcoleções e um campo em um dos documentos dessas subcoleções for alterado, o curinga userId não será acionado.

Correspondências curinga são extraídas do caminho do documento e armazenadas em context.params . Você pode definir quantos curingas quiser para substituir coleções explícitas ou IDs de documentos, por exemplo:

Node.js

// Listen for changes in all documents in the 'users' collection and all subcollections
exports.useMultipleWildcards = functions.firestore
    .document('users/{userId}/{messageCollectionId}/{messageId}')
    .onWrite((change, context) => {
      // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
      // context.params.userId == "marie";
      // context.params.messageCollectionId == "incoming_messages";
      // context.params.messageId == "134";
      // ... and ...
      // change.after.data() == {body: "Hello"}
    });

Gatilhos de evento

Acionar uma função quando um novo documento é criado

Você pode acionar uma função para disparar sempre que um novo documento for criado em uma coleção usando um manipulador onCreate() com um curinga . Esta função de exemplo chama createUser toda vez que um novo perfil de usuário é adicionado:

Node.js

exports.createUser = functions.firestore
    .document('users/{userId}')
    .onCreate((snap, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = snap.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });

Acionar uma função quando um documento é atualizado

Você também pode acionar uma função para disparar quando um documento é atualizado usando a função onUpdate() com um curinga . Esta função de exemplo chama updateUser se um usuário alterar seu perfil:

Node.js

exports.updateUser = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });

Acionar uma função quando um documento é excluído

Você também pode acionar uma função quando um documento é excluído usando a função onDelete() com um curinga . Esta função de exemplo chama deleteUser quando um usuário exclui seu perfil de usuário:

Node.js

exports.deleteUser = functions.firestore
    .document('users/{userID}')
    .onDelete((snap, context) => {
      // Get an object representing the document prior to deletion
      // e.g. {'name': 'Marie', 'age': 66}
      const deletedValue = snap.data();

      // perform desired operations ...
    });

Acionar uma função para todas as alterações em um documento

Se você não se importa com o tipo de evento acionado, pode ouvir todas as alterações em um documento do Cloud Firestore usando a função onWrite() com um caractere curinga . Esta função de exemplo chama modifyUser se um usuário for criado, atualizado ou excluído:

Node.js

exports.modifyUser = functions.firestore
    .document('users/{userID}')
    .onWrite((change, context) => {
      // Get an object with the current document value.
      // If the document does not exist, it has been deleted.
      const document = change.after.exists ? change.after.data() : null;

      // Get an object with the previous document value (for update or delete)
      const oldDocument = change.before.data();

      // perform desired operations ...
    });

Lendo e gravando dados

Quando uma função é acionada, ela fornece um instantâneo dos dados relacionados ao evento. Você pode usar esse instantâneo para ler ou gravar no documento que acionou o evento ou usar o Firebase Admin SDK para acessar outras partes do seu banco de dados.

Dados do Evento

Dados de leitura

Quando uma função é acionada, você pode querer obter dados de um documento que foi atualizado ou obter os dados antes da atualização. Você pode obter os dados anteriores usando change.before.data() , que contém o instantâneo do documento antes da atualização. Da mesma forma, change.after.data() contém o estado instantâneo do documento após a atualização.

Node.js

exports.updateUser2 = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the current document
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();
    });

Você pode acessar as propriedades como faria em qualquer outro objeto. Como alternativa, você pode usar a função get para acessar campos específicos:

Node.js

// Fetch data using standard accessors
const age = snap.data().age;
const name = snap.data()['name'];

// Fetch data using built in accessor
const experience = snap.get('experience');

Dados de gravação

Cada chamada de função está associada a um documento específico em seu banco de dados do Cloud Firestore. Você pode acessar esse documento como um DocumentReference na propriedade ref do instantâneo retornado para sua função.

Este DocumentReference vem do Cloud Firestore Node.js SDK e inclui métodos como update() , set() e remove() para que você possa modificar facilmente o documento que acionou a função.

Node.js

// Listen for updates to any `user` document.
exports.countNameChanges = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Retrieve the current and previous value
      const data = change.after.data();
      const previousData = change.before.data();

      // We'll only update if the name has changed.
      // This is crucial to prevent infinite loops.
      if (data.name == previousData.name) {
        return null;
      }

      // Retrieve the current count of name changes
      let count = data.name_change_count;
      if (!count) {
        count = 0;
      }

      // Then return a promise of a set operation to update the count
      return change.after.ref.set({
        name_change_count: count + 1
      }, {merge: true});
    });

Dados fora do evento de gatilho

As Cloud Functions são executadas em um ambiente confiável, o que significa que são autorizadas como uma conta de serviço em seu projeto. Você pode realizar leituras e gravações usando o Firebase Admin SDK :

Node.js

const admin = require('firebase-admin');
admin.initializeApp();

const db = admin.firestore();

exports.writeToFirestore = functions.firestore
  .document('some/doc')
  .onWrite((change, context) => {
    db.doc('some/otherdoc').set({ ... });
  });

Limitações

Observe as seguintes limitações para gatilhos do Cloud Firestore para Cloud Functions:

  • O pedido não é garantido. Alterações rápidas podem acionar chamadas de função em uma ordem inesperada.
  • Os eventos são entregues pelo menos uma vez, mas um único evento pode resultar em várias chamadas de função. Evite depender da mecânica exatamente uma vez e escreva funções idempotentes .
  • Os gatilhos do Cloud Firestore para Cloud Functions estão disponíveis apenas para o Cloud Firestore no modo nativo . Não está disponível para Cloud Firestore no modo Datastore.