Recuperando dados

Este documento aborda os princípios básicos 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 do Unity já usa o Firebase, ele já está registrado e configurado para o Firebase.

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

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

Observe que adicionar o Firebase ao seu projeto do Unity envolve tarefas no console do Firebase e no seu projeto aberto do Unity (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 anexando a um evento em uma referência FirebaseDatabase . O ouvinte de evento é chamado uma vez para o estado inicial dos dados e novamente sempre que os dados são alterados.

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

Leia os 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 filho. Se não houver dados, o instantâneo 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...
        }
      });

Ouça eventos

Você pode adicionar ouvintes de eventos para assinar alterações nos dados:

Evento Uso típico
ValueChanged Leia e ouça alterações em todo o conteúdo de um caminho.
ChildAdded Recuperar listas de itens ou ouvir adições a uma lista de itens. Uso sugerido com ChildChanged e ChildRemoved para monitorar alterações nas listas.
ChildChanged Ouça as alterações nos itens de uma lista. Use com ChildAdded e ChildRemoved para monitorar alterações nas listas.
ChildRemoved Ouça os itens sendo removidos de uma lista. Use com ChildAdded e ChildChanged para monitorar 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 causou a alteração da ordem do item (com base no seu método de ordenação atual).

Evento ValueChanged

Você pode usar o evento ValueChanged para assinar alterações no conteúdo em um determinado caminho. Este evento é acionado uma vez quando o ouvinte é anexado e novamente sempre que os dados, incluindo 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 instantâneo retornado será null .

O exemplo a seguir demonstra um jogo recuperando as pontuações de um placar 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 snapshot retorna um Dictionary<string, object> que representa os dados. Se não existirem 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 poderá ser cancelada se o cliente não tiver permissão para ler em um local de banco de dados do Firebase. O DatabaseError indicará porque ocorreu a falha.

Posteriormente, você poderá cancelar a assinatura do evento usando qualquer DatabaseReference que tenha o mesmo caminho. As instâncias DatabaseReference são efêmeras e podem ser pensadas 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 aos filhos de um nó a partir 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. Isto inclui quaisquer modificações nos descendentes do nó filho. Geralmente é usado em conjunto com os eventos ChildAdded e ChildRemoved para responder às alterações em uma lista de itens. O instantâneo passado para o ouvinte de evento contém os dados atualizados do filho.

O evento ChildRemoved é acionado quando um filho imediato é removido. Geralmente é 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 a reordenação do filho. É 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 ordenados por 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 ordenado várias vezes na mesma consulta gera um erro.

O exemplo a seguir demonstra como você pode se inscrever em um placar 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 o placar no banco de dados, ordenado pela pontuação de cada entrada. Você pode ler mais sobre como estruturar seus dados de forma eficiente em Estruture seu banco de dados .

A chamada ao método OrderByChild() especifica a chave filha pela qual ordenar os resultados. Neste caso, os resultados são ordenados 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 de limite ou intervalo com um método ordenado por ao construir uma consulta.

Método Uso
LimitToFirst() Define o número máximo de itens a serem retornados do 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 ordenação 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 ordenação escolhido.

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

Mesmo quando há apenas uma 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 métodos 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, inicialmente receberá apenas até 100 retornos de chamada ChildAdded . Se você tiver menos de 100 itens armazenados no banco de dados do Firebase, um callback ChildAdded será 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, de modo que o número total permaneça em 100.

Por exemplo, o código abaixo retorna a pontuação máxima de um placar:

      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
    }

Filtrar por chave ou valor

Você pode usar StartAt() , EndAt() e EqualTo() para escolher pontos iniciais, finais e de equivalência arbitrários para consultas. Isso pode ser útil para paginar dados ou encontrar 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 ordenados 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. Os 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. Os 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. Os filhos com 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. Os filhos com uma chave que pode ser analisada como um número inteiro de 32 bits vêm primeiro, classificados em ordem crescente.
  2. Os 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.