Recuperando datos

Este documento cubre los conceptos básicos de la recuperación de datos y cómo ordenar y filtrar datos de Firebase.

Antes de que empieces

Antes de poder utilizar Realtime Database , debe:

  • Registre su proyecto de Unity y configúrelo para usar Firebase.

    • Si tu proyecto de Unity ya usa Firebase, entonces ya está registrado y configurado para Firebase.

    • Si no tiene un proyecto de Unity, puede descargar una aplicación de muestra .

  • Agregue el SDK de Firebase Unity (específicamente, FirebaseDatabase.unitypackage ) a su proyecto de Unity.

Tenga en cuenta que agregar Firebase a su proyecto de Unity implica tareas tanto en Firebase console como en su proyecto de Unity abierto (por ejemplo, descarga archivos de configuración de Firebase desde la consola y luego los mueve a su proyecto de Unity).

Recuperando datos

Los datos de Firebase se recuperan mediante una llamada única a GetValueAsync() o adjuntándolos a un evento en una referencia FirebaseDatabase . El detector de eventos se llama una vez para el estado inicial de los datos y nuevamente cada vez que cambian los datos.

Obtener una referencia de base de datos

Para leer datos de la base de datos, necesita una instancia 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;
  }
}

Leer datos una vez

Puede utilizar el método GetValueAsync para leer una vez una instantánea estática del contenido en una ruta determinada. El resultado de la tarea contendrá una instantánea que contendrá todos los datos en esa ubicación, incluidos los datos del niño. Si no hay datos, la instantánea devuelta es 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...
        }
      });

Escuche eventos

Puede agregar detectores de eventos para suscribirse a los cambios en los datos:

Evento Uso típico
ValueChanged Lea y escuche los cambios en todo el contenido de una ruta.
ChildAdded Recupera listas de elementos o escucha adiciones a una lista de elementos. Uso sugerido con ChildChanged y ChildRemoved para monitorear cambios en las listas.
ChildChanged Escuche los cambios en los elementos de una lista. Úselo con ChildAdded y ChildRemoved para monitorear los cambios en las listas.
ChildRemoved Escuche los elementos que se eliminan de una lista. Úselo con ChildAdded y ChildChanged para monitorear los cambios en las listas.
ChildMoved Escuche los cambios en el orden de los elementos en una lista ordenada. Los eventos ChildMoved siempre siguen al evento ChildChanged que provocó que cambiara el orden del artículo (según su método de ordenamiento actual).

Evento de cambio de valor

Puede utilizar el evento ValueChanged para suscribirse a cambios de contenido en una ruta determinada. Este evento se activa una vez cuando se adjunta el oyente y nuevamente cada vez que cambian los datos, incluidos los secundarios. A la devolución de llamada del evento se le pasa una instantánea que contiene todos los datos en esa ubicación, incluidos los datos secundarios. Si no hay datos, la instantánea devuelta es null .

El siguiente ejemplo muestra un juego que recupera las puntuaciones de una tabla de clasificación de la base de datos:

      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 contiene una DataSnapshot que contiene los datos en la ubicación especificada en la base de datos en el momento del evento. Llamar Value en una instantánea devuelve un Dictionary<string, object> que representa los datos. Si no existen datos en la ubicación, llamar a Value devuelve null .

En este ejemplo, también se examina args.DatabaseError para ver si se cancela la lectura. Por ejemplo, una lectura se puede cancelar si el cliente no tiene permiso para leer desde una ubicación de base de datos de Firebase. DatabaseError indicará por qué ocurrió la falla.

Posteriormente podrá cancelar la suscripción al evento utilizando cualquier DatabaseReference que tenga la misma ruta. Las instancias DatabaseReference son efímeras y pueden considerarse como una forma de acceder a cualquier ruta y consulta.

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

Eventos infantiles

Los eventos secundarios se activan en respuesta a operaciones específicas que les suceden a los elementos secundarios de un nodo a partir de una operación, como un nuevo elemento secundario agregado mediante el método Push() o un elemento secundario que se actualiza mediante el método UpdateChildrenAsync() . Cada uno de estos juntos puede ser útil para escuchar cambios en un nodo específico en una base de datos. Por ejemplo, un juego podría utilizar estos métodos juntos para monitorear la actividad en los comentarios de una sesión de juego, como se muestra a continuación:

      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
    }

El evento ChildAdded se usa normalmente para recuperar una lista de elementos en una base de datos de Firebase. El evento ChildAdded se genera una vez para cada elemento secundario existente y luego nuevamente cada vez que se agrega un elemento secundario nuevo a la ruta especificada. Al oyente se le pasa una instantánea que contiene los datos del nuevo niño.

El evento ChildChanged se genera cada vez que se modifica un nodo secundario. Esto incluye cualquier modificación a los descendientes del nodo hijo. Normalmente se utiliza junto con los eventos ChildAdded y ChildRemoved para responder a cambios en una lista de elementos. La instantánea pasada al detector de eventos contiene los datos actualizados del niño.

El evento ChildRemoved se activa cuando se elimina un niño inmediato. Normalmente se utiliza junto con las devoluciones de llamada ChildAdded y ChildChanged . La instantánea pasada a la devolución de llamada del evento contiene los datos del elemento secundario eliminado.

El evento ChildMoved se activa cada vez que el evento ChildChanged se genera mediante una actualización que provoca el reordenamiento del elemento secundario. Se utiliza con datos ordenados con OrderByChild o OrderByValue .

Ordenar y filtrar datos

Puede utilizar la clase Query de base de datos en tiempo real para recuperar datos ordenados por clave, por valor o por valor de un hijo. También puede filtrar el resultado ordenado según un número específico de resultados o un rango de claves o valores.

ordenar datos

Para recuperar datos ordenados, comience especificando uno de los métodos de ordenación para determinar cómo se ordenan los resultados:

Método Uso
OrderByChild() Ordene los resultados por el valor de una clave secundaria especificada.
OrderByKey() Ordene los resultados por claves secundarias.
OrderByValue() Ordene los resultados por valores secundarios.

Sólo puedes utilizar un método de orden por vez. Llamar a un método de orden por varias veces en la misma consulta genera un error.

El siguiente ejemplo demuestra cómo puedes suscribirte en una tabla de clasificación de puntuación ordenada por puntuación.

      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
    }

Esto define una consulta que, cuando se combina con un detector de eventos de cambio de valor, sincroniza al cliente con la tabla de clasificación en la base de datos, ordenada por la puntuación de cada entrada. Puede leer más sobre cómo estructurar sus datos de manera eficiente en Estructurar su base de datos .

La llamada al método OrderByChild() especifica la clave secundaria para ordenar los resultados. En este caso, los resultados se ordenan por el valor de la "score" de cada niño. Para obtener más información sobre cómo se ordenan otros tipos de datos, consulte Cómo se ordenan los datos de la consulta .

Filtrar datos

Para filtrar datos, puede combinar cualquiera de los métodos de límite o rango con un método de ordenar por al crear una consulta.

Método Uso
LimitToFirst() Establece el número máximo de elementos que se devolverán desde el principio de la lista ordenada de resultados.
LimitToLast() Establece el número máximo de elementos que se devolverán desde el final de la lista ordenada de resultados.
StartAt() Devuelve elementos mayores o iguales a la clave o valor especificado según el método de ordenamiento elegido.
EndAt() Devuelve elementos menores o iguales a la clave o valor especificado según el método de ordenamiento elegido.
EqualTo() Devuelve elementos iguales a la clave o valor especificado según el método de ordenamiento elegido.

A diferencia de los métodos de orden por, puede combinar múltiples funciones de límite o rango. Por ejemplo, puede combinar los métodos StartAt() y EndAt() para limitar los resultados a un rango de valores específico.

Incluso cuando solo hay una coincidencia para la consulta, la instantánea sigue siendo una lista; solo contiene un solo elemento.

Limitar el número de resultados.

Puede utilizar los métodos LimitToFirst() y LimitToLast() para establecer un número máximo de elementos secundarios que se sincronizarán para una devolución de llamada determinada. Por ejemplo, si usa LimitToFirst() para establecer un límite de 100, inicialmente solo recibirá hasta 100 devoluciones de llamada ChildAdded . Si tiene menos de 100 elementos almacenados en su base de datos de Firebase, se activa una devolución de llamada ChildAdded para cada elemento.

A medida que los elementos cambian, recibe devoluciones de llamada ChildAdded para los elementos que ingresan a la consulta y devoluciones de llamada ChildRemoved para los elementos que salen de ella, de modo que el número total permanezca en 100.

Por ejemplo, el siguiente código devuelve la puntuación más alta de una tabla de clasificación:

      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 clave o valor

Puede utilizar StartAt() , EndAt() y EqualTo() para elegir puntos de inicio, finalización y equivalencia arbitrarios para las consultas. Esto puede resultar útil para paginar datos o buscar elementos con elementos secundarios que tengan un valor específico.

Cómo se ordenan los datos de la consulta

Esta sección explica cómo se ordenan los datos mediante cada uno de los métodos de ordenación en la clase Query .

OrderByChild

Cuando se utiliza OrderByChild() , los datos que contienen la clave secundaria especificada se ordenan de la siguiente manera:

  1. Los niños con un valor null para la clave secundaria especificada son lo primero.
  2. Los niños con un valor false para la clave secundaria especificada son los siguientes. Si varios hijos tienen un valor false , se ordenan lexicográficamente por clave.
  3. Los niños con un valor true para la clave secundaria especificada son los siguientes. Si varios hijos tienen un valor true , se ordenan lexicográficamente por clave.
  4. Los niños con un valor numérico vienen a continuación, ordenados en orden ascendente. Si varios hijos tienen el mismo valor numérico para el nodo hijo especificado, se ordenan por clave.
  5. Las cadenas van después de los números y están ordenadas lexicográficamente en orden ascendente. Si varios hijos tienen el mismo valor para el nodo hijo especificado, se ordenan lexicográficamente por clave.
  6. Los objetos van al final y se ordenan lexicográficamente por clave en orden ascendente.

OrderByKey

Cuando utiliza OrderByKey() para ordenar sus datos, los datos se devuelven en orden ascendente por clave.

  1. Los niños con una clave que se puede analizar como un entero de 32 bits aparecen primero, ordenados en orden ascendente.
  2. Los niños con un valor de cadena como clave vienen a continuación, ordenados lexicográficamente en orden ascendente.

OrderByValue

Cuando se usa OrderByValue() , los niños se ordenan por su valor. Los criterios de orden son los mismos que en OrderByChild() , excepto que se utiliza el valor del nodo en lugar del valor de una clave secundaria especificada.