Anúncio do Cloud Firestore (Beta): conheça o novo banco de dados flexível e escalável do Firebase e do Google Cloud Platform. Saiba mais sobre o Cloud Firestore.

Ler e gravar dados na Web

Receber uma referência do banco de dados

Para ler ou gravar dados do banco de dados, você precisa de uma instância de firebase.database.Reference:

// Get a reference to the database service
var database = firebase.database();

Ler e gravar dados

Este documento abrange os conceitos básicos para recuperar dados e como ordenar e filtrar dados do Firebase.

Os dados do Firebase são recuperados quando um listener assíncrono é anexado a uma firebase.database.Reference. Ele é acionado uma vez no estado inicial dos dados e posteriormente, quando há alterações.

Operações básicas de gravação

Em operações básicas de gravação, use set() para salvar dados em uma referência e substitua os dados existentes no caminho. Por exemplo, um aplicativo de blog em rede social poderia adicionar um usuário com set() da seguinte maneira:

function writeUserData(userId, name, email, imageUrl) {
  firebase.database().ref('users/' + userId).set({
    username: name,
    email: email,
    profile_picture : imageUrl
  });
}

O set() substitui os dados no local especificado, incluindo qualquer node filho.

Detectar eventos de valor

Para ler dados em um caminho e detectar as alterações, use os métodos on() ou once() do firebase.database.Reference para observar eventos.

Evento Uso normal
value Ler e detectar alterações em todo o conteúdo de um caminho.

Você pode usar o evento value para ler um instantâneo estático do conteúdo de um determinado caminho, já que ele existia no momento do evento. Esse método será acionado uma vez quando o listener for anexado e sempre que os dados forem alterados, incluindo os filhos. O retorno de chamada do evento recebe um instantâneo que contém todos os dados no local, incluindo dados filhos. Se não houver dados, o instantâneo retornará false quando você chamar exists() e null quando você chamar val() nele.

O exemplo a seguir mostra um app de blog em rede social recuperando o número de estrelas de uma postagem do banco de dados:

var starCountRef = firebase.database().ref('posts/' + postId + '/starCount');
starCountRef.on('value', function(snapshot) {
  updateStarCount(postElement, snapshot.val());
});

O listener recebe um snapshot que contém os dados no local especificado no banco de dados no momento do evento. Você pode recuperar os dados no snapshot com o método val().

Ler dados uma vez

Em alguns casos, você pode desejar um instantâneo dos seus dados sem detectar as alterações. Por exemplo, ao inicializar um elemento de IU que não deve ser alterado. Você pode usar o método once() para simplificar esse cenário: ele é acionado somente uma vez.

Isso é útil para dados que só precisam ser carregados uma vez, não são alterados com frequência nem exigem detecção ativa. Por exemplo, o app de blog dos exemplos anteriores usa esse método para carregar o perfil de um usuário quando ele começa a escrever uma nova postagem:

var userId = firebase.auth().currentUser.uid;
return firebase.database().ref('/users/' + userId).once('value').then(function(snapshot) {
  var username = (snapshot.val() && snapshot.val().username) || 'Anonymous';
  // ...
});

Atualização ou exclusão de dados

Atualizar campos específicos

Para gravar simultaneamente filhos específicos de um node sem substituir outros nodes filhos, use o método update().

Ao chamar update(), atualize valores de filhos de nível inferior especificando um caminho para a chave. Se os dados estiverem armazenados em vários locais para aprimorar a escalabilidade, atualize todas as instâncias usando a distribuição de dados.

Por exemplo, um app de blog em rede social pode criar uma postagem e atualizá-la simultaneamente no feed de atividades recentes e no feed do autor da postagem usando um código como este:

function writeNewPost(uid, username, picture, title, body) {
  // A post entry.
  var postData = {
    author: username,
    uid: uid,
    body: body,
    title: title,
    starCount: 0,
    authorPic: picture
  };

  // Get a key for a new Post.
  var newPostKey = firebase.database().ref().child('posts').push().key;

  // Write the new post's data simultaneously in the posts list and the user's post list.
  var updates = {};
  updates['/posts/' + newPostKey] = postData;
  updates['/user-posts/' + uid + '/' + newPostKey] = postData;

  return firebase.database().ref().update(updates);
}

Esse exemplo usa push() para criar uma postagem no node que armazena as postagens para todos os usuários em /posts/$postid e, simultaneamente, recuperar a chave. A chave pode ser usada para criar uma segunda entrada em /user-posts/$userid/$postid.

Com esses caminhos, você faz atualizações simultâneas em vários locais da árvore JSON com uma única chamada ao update(), da mesma forma que esse exemplo cria a nova postagem nos dois locais. Essas atualizações são atômicas: ou todas funcionam ou todas falham.

Adicionar um retorno de chamada de conclusão

Se você quiser saber quando seus dados foram confirmados, adicione um retorno de chamada de conclusão. set() e update() recebem um retorno de chamada de conclusão opcional, que será chamado quando a gravação for confirmada no banco de dados. Se uma chamada falhar, o retorno de chamada será transmitido por um objeto de erro indicando por que a falha ocorreu.

  firebase.database().ref('users/' + userId).set({
    username: name,
    email: email,
    profile_picture : imageUrl
  }, function(error) {
    if (error) {
      // The write failed...
    } else {
      // Data saved successfully!
    }
  });
}

Excluir dados

A maneira mais simples de excluir os dados é chamar remove() em uma referência ao local onde estão localizados.

Também é possível exclui-los especificando null como valor para outra operação de gravação, como set() ou update(). Você pode usar esta técnica com update() para excluir vários filhos em uma única chamada de API.

Receber uma Promise

Para saber quando seus dados forem confirmados no servidor do Firebase Realtime Database, use uma Promise. Tanto set() como update() podem retornar uma Promise que você pode usar para saber quando a gravação está confirmada no banco de dados.

Remover listeners

Retornos de chamada são removidos chamando o método off() na sua referência ao banco de dados do Firebase.

Você pode remover um único listener ao transmiti-lo como um parâmetro para off(). Chamar off() no local sem argumentos remove todos os listeners desse local.

Chamar off() em um listener pai não remove automaticamente os listeners registrados nos nodes filho dele. off() também precisa ser chamado nos listeners filho para remover o retorno de chamada.

Salvar dados como transações

Para tratar dados corrompidos por modificações simultâneas, como contadores incrementais, use uma operação de transação. Essa operação aceita uma função de atualização e um retorno de chamada de conclusão opcional. A função de atualização usa o estado atual dos dados como um argumento e retorna o novo estado desejado de acordo com suas preferências. Se outro cliente fizer uma gravação no local antes que seu novo valor seja gravado com sucesso, sua função de atualização será chamada novamente com o novo valor atual e a gravação será repetida.

Por exemplo, no app de blog social que mencionamos, você pode permitir que os usuários adicionem ou removam estrelas de postagens e acompanhem quantas estrelas uma postagem recebeu da seguinte maneira:

function toggleStar(postRef, uid) {
  postRef.transaction(function(post) {
    if (post) {
      if (post.stars && post.stars[uid]) {
        post.starCount--;
        post.stars[uid] = null;
      } else {
        post.starCount++;
        if (!post.stars) {
          post.stars = {};
        }
        post.stars[uid] = true;
      }
    }
    return post;
  });
}

A transação impede uma contagem incorreta de estrelas se vários usuários adicionam simultaneamente estrelas à mesma postagem ou se o cliente tem dados desatualizados. Se a transação for rejeitada, o servidor retornará o valor atual ao cliente, que executará a transação novamente com o valor atualizado. Isso se repete até que a transação seja aceita ou cancelada.

Gravar dados off-line

Se um cliente perder a conexão de rede, o app continuará funcionando.

Todos os clientes conectados a um banco de dados do Firebase mantêm a própria versão interna de dados ativos. A gravação deles ocorre primeiro nessa versão local. Depois, o cliente do Firebase sincroniza esses dados com os servidores remotos e com outros de acordo com o modelo “melhor esforço".

Consequentemente, todas as gravações no banco de dados acionam eventos locais, antes de qualquer dado ser gravado no servidor, e o app continua responsivo, independentemente da conectividade ou da latência da rede.

Para que a conectividade seja restabelecida, seu app recebe o conjunto apropriado de eventos, e o cliente faz a sincronização com o estado atual do servidor, sem precisar de um código personalizado.

Próximas etapas

Enviar comentários sobre…

Firebase Realtime Database
Precisa de ajuda? Acesse nossa página de suporte.