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 | Uso típico |
---|---|
ValueChanged | Lea y escuche los cambios en todo el contenido de una ruta. |
ChildAdded | Recupere listas de elementos o escuche adiciones a una lista de elementos. Uso sugerido con ChildChanged y ChildRemoved para monitorear los 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 hizo que cambiara el orden del artículo (según el método actual de ordenación). |
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:
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. |
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.
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 que la clave o el valor especificado según el método de ordenación elegido. |
EndAt() | Devuelve artículos menores o iguales a la clave o valor especificado según el método de orden elegido. |
EqualTo() | Devuelve elementos iguales a la clave o valor especificado según el método de orden elegido. |
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:
- Los elementos secundarios con un valor
null
para la clave secundaria especificada vienen primero. - Los elementos secundarios con un valor
false
para la clave secundaria especificada vienen a continuación. Si varios hijos tienen un valor defalse
, se ordenan lexicográficamente por clave. - Los elementos secundarios con un valor de
true
para la clave secundaria especificada vienen a continuación. Si varios hijos tienen un valor detrue
, se ordenan lexicográficamente por clave. - 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.
- 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.
- 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.
- Los elementos secundarios con una clave que se puede analizar como un entero de 32 bits aparecen primero, ordenados en orden ascendente.
- 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.