Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Recuperando dados

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

Este documento aborda os fundamentos da recuperação de dados e como ordenar e filtrar dados do Firebase.

Antes de você começar

Antes de poder usar o Realtime Database , você precisa:

  • Registre seu projeto Unity e configure-o para usar o Firebase.

    • Se o seu projeto Unity já usa o Firebase, ele já está registrado e configurado para o Firebase.

    • Se você não tiver um projeto Unity, poderá baixar um aplicativo de exemplo .

  • Adicione o Firebase Unity SDK (especificamente, FirebaseDatabase.unitypackage ) ao seu projeto Unity.

Observe que adicionar o Firebase ao seu projeto do Unity envolve tarefas no console do Firebase e em seu projeto Unity aberto (por exemplo, você baixa os arquivos de configuração do Firebase do console e os move para o seu projeto do Unity).

Recuperando dados

Os dados do Firebase são recuperados por uma chamada única para GetValueAsync() ou anexados a um evento em uma referência FirebaseDatabase . O ouvinte de eventos é chamado uma vez para o estado inicial dos dados e novamente sempre que os dados forem alterados.

Obter uma referência de banco de dados

Para ler dados do banco de dados, você precisa de uma instância de DatabaseReference :

using Firebase;
using Firebase.Database;
using Firebase.Extensions.TaskExtension; // for ContinueWithOnMainThread

public class MyScript: MonoBehaviour {
  void Start() {
    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

Ler dados uma vez

Você pode usar o método GetValueAsync para ler um instantâneo estático do conteúdo em um determinado caminho uma vez. O resultado da tarefa conterá um instantâneo contendo todos os dados naquele local, incluindo dados filhos. Se não houver dados, o snapshot retornado será null .

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWithOnMainThread(task => {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

Ouvir eventos

Você pode adicionar ouvintes de eventos para se inscrever em alterações nos dados:

Evento Uso típico
ValueChanged Leia e ouça alterações em todo o conteúdo de um caminho.
ChildAdded Recupere listas de itens ou ouça adições a uma lista de itens. Uso sugerido com ChildChanged e ChildRemoved para monitorar alterações em listas.
ChildChanged Ouça as alterações nos itens de uma lista. Use com ChildAdded e ChildRemoved para monitorar as alterações nas listas.
ChildRemoved Ouça os itens sendo removidos de uma lista. Use com ChildAdded e ChildChanged para monitorar as alterações nas listas.
ChildMoved Ouça as alterações na ordem dos itens em uma lista ordenada. Os eventos ChildMoved sempre seguem o evento ChildChanged que fez com que a ordem do item fosse alterada (com base no seu método order-by atual).

Evento ValueChanged

Você pode usar o evento ValueChanged para se inscrever em alterações do conteúdo em um determinado caminho. Esse evento é acionado uma vez quando o ouvinte é conectado e novamente toda vez que os dados, incluindo os filhos, são alterados. O retorno de chamada do evento recebe um instantâneo contendo todos os dados naquele local, incluindo dados filho. Se não houver dados, o snapshot retornado será null .

O exemplo a seguir demonstra um jogo recuperando as pontuações de uma tabela de classificação do banco de dados:

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

ValueChangedEventArgs contém um DataSnapshot que contém os dados no local especificado no banco de dados no momento do evento. Chamar Value em um instantâneo retorna um Dictionary<string, object> representando os dados. Se não houver dados no local, chamar Value retornará null .

Neste exemplo, args.DatabaseError também é examinado para ver se a leitura foi cancelada. Por exemplo, uma leitura pode ser cancelada se o cliente não tiver permissão para ler de um local do banco de dados do Firebase. O DatabaseError indicará o motivo da falha.

Posteriormente, você pode cancelar a assinatura do evento usando qualquer DatabaseReference que tenha o mesmo caminho. As instâncias DatabaseReference são efêmeras e podem ser consideradas como uma forma de acessar qualquer caminho e consulta.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged.
    }

eventos infantis

Os eventos filho são acionados em resposta a operações específicas que acontecem com os filhos de um nó de uma operação, como um novo filho adicionado por meio do método Push() ou um filho sendo atualizado por meio do método UpdateChildrenAsync() . Cada um deles juntos pode ser útil para ouvir alterações em um nó específico em um banco de dados. Por exemplo, um jogo pode usar esses métodos juntos para monitorar a atividade nos comentários de uma sessão de jogo, conforme mostrado abaixo:

      var ref = FirebaseDatabase.DefaultInstance
      .GetReference("GameSessionComments");

      ref.ChildAdded += HandleChildAdded;
      ref.ChildChanged += HandleChildChanged;
      ref.ChildRemoved += HandleChildRemoved;
      ref.ChildMoved += HandleChildMoved;
    }

    void HandleChildAdded(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildChanged(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildRemoved(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildMoved(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

O evento ChildAdded normalmente é usado para recuperar uma lista de itens em um banco de dados Firebase. O evento ChildAdded é gerado uma vez para cada filho existente e novamente sempre que um novo filho é adicionado ao caminho especificado. O ouvinte recebe um instantâneo contendo os dados do novo filho.

O evento ChildChanged é gerado sempre que um nó filho é modificado. Isso inclui quaisquer modificações nos descendentes do nó filho. Ele é normalmente usado em conjunto com os eventos ChildAdded e ChildRemoved para responder a alterações em uma lista de itens. O instantâneo passado para o ouvinte de eventos contém os dados atualizados para o filho.

O evento ChildRemoved é acionado quando um filho imediato é removido. Ele é normalmente usado em conjunto com os retornos de chamada ChildAdded e ChildChanged . O instantâneo passado para o retorno de chamada do evento contém os dados do filho removido.

O evento ChildMoved é acionado sempre que o evento ChildChanged é gerado por uma atualização que causa o reordenamento do filho. Ele é usado com dados ordenados com OrderByChild ou OrderByValue .

Classificando e filtrando dados

Você pode usar a classe Realtime Database Query para recuperar dados classificados por chave, por valor ou por valor de um filho. Você também pode filtrar o resultado classificado para um número específico de resultados ou um intervalo de chaves ou valores.

Classificar dados

Para recuperar dados classificados, comece especificando um dos métodos order-by para determinar como os resultados são ordenados:

Método Uso
OrderByChild() Ordene os resultados pelo valor de uma chave filha especificada.
OrderByKey() Ordene os resultados por chaves filhas.
OrderByValue() Ordene os resultados por valores filhos.

Você só pode usar um método de ordem por vez. Chamar um método order-by várias vezes na mesma consulta gera um erro.

O exemplo a seguir demonstra como você pode se inscrever em um placar de pontuação ordenado por pontuação.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders").OrderByChild("score")
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

Isso define uma consulta que, quando combinada com um ouvinte de evento valuechanged, sincroniza o cliente com a tabela de classificação no banco de dados, ordenada pela pontuação de cada entrada. Você pode ler mais sobre como estruturar seus dados de forma eficiente em Estruturar seu banco de dados.

A chamada para o método OrderByChild() especifica a chave filha para ordenar os resultados. Nesse caso, os resultados são classificados pelo valor da "score" em cada filho. Para obter mais informações sobre como outros tipos de dados são ordenados, consulte Como os dados de consulta são ordenados .

Filtrando dados

Para filtrar dados, você pode combinar qualquer um dos métodos limit ou range com um método order-by ao construir uma consulta.

Método Uso
LimitToFirst() Define o número máximo de itens a serem retornados desde o início da lista ordenada de resultados.
LimitToLast() Define o número máximo de itens a serem retornados do final da lista ordenada de resultados.
StartAt() Retorna itens maiores ou iguais à chave ou valor especificado, dependendo do método de ordem escolhido.
EndAt() Retorna itens menores ou iguais à chave ou valor especificado, dependendo do método de ordenação escolhido.
EqualTo() Retorna itens iguais à chave ou valor especificado, dependendo do método de ordem escolhido.

Ao contrário dos métodos de ordem, você pode combinar várias funções de limite ou intervalo. Por exemplo, você pode combinar os StartAt() e EndAt() para limitar os resultados a um intervalo de valores especificado.

Mesmo quando há apenas uma única correspondência para a consulta, o instantâneo ainda é uma lista; ele contém apenas um único item.

Limite o número de resultados

Você pode usar os LimitToFirst() e LimitToLast() para definir um número máximo de filhos a serem sincronizados para um determinado retorno de chamada. Por exemplo, se você usar LimitToFirst() para definir um limite de 100, receberá inicialmente apenas até 100 retornos de chamada ChildAdded . Se você tiver menos de 100 itens armazenados em seu banco de dados do Firebase, um retorno de chamada ChildAdded acionado para cada item.

À medida que os itens mudam, você recebe retornos de chamada ChildAdded para itens que entram na consulta e retornos de chamada ChildRemoved para itens que saem dela para que o número total permaneça em 100.

Por exemplo, o código abaixo retorna a pontuação máxima de uma tabela de classificação:

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders").OrderByChild("score").LimitToLast(1)
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

Filtre por chave ou valor

Você pode usar StartAt() , EndAt() e EqualTo() para escolher pontos de início, término e equivalência arbitrários para consultas. Isso pode ser útil para paginar dados ou localizar itens com filhos que tenham um valor específico.

Como os dados da consulta são ordenados

Esta seção explica como os dados são classificados por cada um dos métodos order-by na classe Query .

OrderByChild

Ao usar OrderByChild() , os dados que contêm a chave filha especificada são ordenados da seguinte forma:

  1. Os filhos com um valor null para a chave filha especificada vêm primeiro.
  2. Filhos com um valor false para a chave filha especificada vêm em seguida. Se vários filhos tiverem um valor false , eles serão classificados lexicograficamente por chave.
  3. Filhos com um valor true para a chave filha especificada vêm em seguida. Se vários filhos tiverem um valor true , eles serão classificados lexicograficamente por chave.
  4. Filhos com um valor numérico vêm em seguida, classificados em ordem crescente. Se vários filhos tiverem o mesmo valor numérico para o nó filho especificado, eles serão classificados por chave.
  5. As strings vêm depois dos números e são classificadas lexicograficamente em ordem crescente. Se vários filhos tiverem o mesmo valor para o nó filho especificado, eles serão ordenados lexicograficamente por chave.
  6. Os objetos vêm por último e são classificados lexicograficamente por chave em ordem crescente.

OrderByKey

Ao usar OrderByKey() para classificar seus dados, os dados são retornados em ordem crescente por chave.

  1. Filhos com uma chave que pode ser analisada como um número inteiro de 32 bits vêm primeiro, classificados em ordem crescente.
  2. Filhos com um valor de string como chave vêm em seguida, classificados lexicograficamente em ordem crescente.

OrderByValue

Ao usar OrderByValue() , os filhos são ordenados por seu valor. Os critérios de ordenação são os mesmos de OrderByChild() , exceto que o valor do nó é usado em vez do valor de uma chave filha especificada.