Recuperando datos

Este documento cubre los aspectos 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:

• Registra tu proyecto de Unity y configúralo para usar Firebase.

  • Si su 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 la consola de Firebase 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 adjuntando un evento en una referencia de FirebaseDatabase . El detector de eventos se llama una vez para el estado inicial de los datos y nuevamente cada vez que los datos cambian.

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 usar el método GetValueAsync para leer una instantánea estática de los contenidos en una ruta determinada una vez. El resultado de la tarea contendrá una instantánea con todos los datos en esa ubicación, incluidos los datos secundarios. 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 los eventos

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

Evento ValueChanged

Puede usar el evento ValueChanged para suscribirse a los cambios de los contenidos 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 elementos secundarios. La devolución de llamada del evento recibe 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 los puntajes 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 un DataSnapshot que contiene los datos en la ubicación especificada en la base de datos en el momento del evento. Llamar a Value en una instantánea devuelve un Dictionary<string, object> representa los datos. Si no existen datos en la ubicación, llamar a Value devuelve null .

En este ejemplo, args.DatabaseError también se examina para ver si se cancela la lectura. Por ejemplo, se puede cancelar una lectura 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, puede darse de baja del evento utilizando cualquier DatabaseReference que tenga la misma ruta. Las instancias de DatabaseReference son efímeras y se pueden considerar 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 a través del método Push() o un elemento secundario que se actualiza a través del 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 usar 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 generalmente se usa 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 secundario. Por lo general, se usa junto con los eventos ChildAdded y ChildRemoved para responder a los cambios en una lista de elementos. La instantánea que se pasa al detector de eventos contiene los datos actualizados del niño.

El evento ChildRemoved se desencadena cuando se elimina un elemento secundario inmediato. Por lo general, se usa 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 desencadena cada ChildChanged que una actualización provoca el reordenamiento del elemento secundario. Se utiliza con datos que se ordenan con OrderByChild o OrderByValue .

Ordenar y filtrar datos

Puede usar la clase de Query de base de datos en tiempo real para recuperar datos ordenados por clave, por valor o por valor de un elemento secundario. También puede filtrar el resultado ordenado a 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:

Solo puede usar un método de ordenar a la vez. Llamar a un método order-by varias veces en la misma consulta genera un error.

El siguiente ejemplo demuestra cómo podría suscribirse 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 el 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 por la que ordenar los resultados. En este caso, los resultados se ordenan por el valor de la "score" en 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 consulta .

Filtrado de datos

Para filtrar datos, puede combinar cualquiera de los métodos de límite o rango con un método de ordenación al construir una consulta.

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

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

Limitar el número de resultados

Puede usar los LimitToFirst() y LimitToLast() para establecer una cantidad máxima 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 llamadas de 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 la abandonan, de modo que el número total permanece 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 equivalencia, finalización y comienzo arbitrarios para las consultas. Esto puede ser útil para paginar datos o encontrar elementos con elementos secundarios que tengan un valor específico.

Cómo se ordenan los datos de consulta

Esta sección explica cómo se ordenan los datos por cada uno de los métodos order-by en la clase Query .

OrderByChild

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

1. Los elementos secundarios con un valor null para la clave secundaria especificada vienen primero.
2. Los elementos secundarios con un valor false para la clave secundaria especificada vienen a continuación. Si varios hijos tienen un valor de false , se ordenan lexicográficamente por clave.
3. Los elementos secundarios con un valor de true para la clave secundaria especificada vienen a continuación. Si varios hijos tienen un valor de 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 elementos secundarios tienen el mismo valor numérico para el nodo secundario especificado, se ordenan por clave.
5. Las cadenas vienen después de los números y se clasifican 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 en último lugar y se ordenan lexicográficamente por clave en orden ascendente.

OrderByKey

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

1. Los elementos secundarios 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 elementos secundarios se ordenan por su valor. Los criterios de ordenación son los mismos que en OrderByChild() , excepto que se usa el valor del nodo en lugar del valor de una clave secundaria especificada.