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

Recuperación de datos con Firebase Realtime Database para C++

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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

Asegúrese de haber configurado su aplicación y poder acceder a la base de datos como se describe en la guía de Get Started .

Recuperando datos

Los datos de Firebase se recuperan mediante una llamada única a GetValue() o adjuntando a un ValueListener en una referencia de FirebaseDatabase . El detector de valor 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 escribir datos en la base de datos, necesita una instancia de DatabaseReference :

    // Get the root reference location of the database.
    firebase::database::DatabaseReference dbref = database->GetReference();

Leer datos una vez

Puede usar el método GetValue() 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 .

  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("Leaders").GetValue();

En el momento en que se realizó la solicitud, pero tenemos que esperar a que Future se complete antes de que podamos leer el valor. Dado que los juegos generalmente se ejecutan en un bucle y están menos impulsados ​​por la devolución de llamadas que otras aplicaciones, generalmente sondeará para que se completen.

  // In the game loop that polls for the result...

  if (result.status() != firebase::kFutureStatusPending) {
    if (result.status() != firebase::kFutureStatusComplete) {
      LogMessage("ERROR: GetValue() returned an invalid result.");
      // Handle the error...
    } else if (result.error() != firebase::database::kErrorNone) {
      LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
                 result.error_message());
      // Handle the error...
    } else {
      firebase::database::DataSnapshot snapshot = result.result();
      // Do something with the snapshot...
    }
  }

Esto muestra algunas comprobaciones de errores básicas. Consulte firebase::Future reference para obtener más información sobre la comprobación de errores y las formas de determinar cuándo está listo el resultado.

Escuche los eventos

Puede agregar oyentes para suscribirse a los cambios en los datos:

Clase base ValueListener

Llamar de vuelta Uso típico
OnValueChanged Lea y escuche los cambios en todo el contenido de una ruta.

Clase base OnChildListener

OnChildAdded Recupere listas de elementos o escuche adiciones a una lista de elementos. Uso sugerido con OnChildChanged y OnChildRemoved para monitorear cambios en las listas.
OnChildChanged Escuche los cambios en los elementos de una lista. Úselo con OnChildAdded y OnChildRemoved para monitorear los cambios en las listas.
OnChildRemoved Escuche los elementos que se eliminan de una lista. Úselo con OnChildAdded y OnChildChanged para monitorear los cambios en las listas.
OnChildMoved Escuche los cambios en el orden de los elementos en una lista ordenada. Las devoluciones de llamada de OnChildMoved siempre siguen a las devoluciones de llamada de OnChildChanged debido al cambio de orden del artículo (según su método de pedido actual).

clase ValueListener

Puede usar las devoluciones de llamada OnValueChanged para suscribirse a los cambios en los contenidos en una ruta determinada. Esta devolución de llamada 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 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:

  class LeadersValueListener : public firebase::database::ValueListener {
   public:
    void OnValueChanged(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
                 error_message);
    }
  };

  // Elsewhere in the code...

  LeadersValueListener* listener = new LeadersValueListener();
  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

El resultado Future&ltDataSnaphot&gt 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 una Variant que representa los datos.

En este ejemplo, el método OnCancelled también se anula 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. La base de database::Error indicará por qué ocurrió la falla.

clase ChildListener

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 PushChild() o un elemento secundario que se actualiza a través del método UpdateChildren() . 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:

  class SessionCommentsChildListener : public firebase::database::ChildListener {
   public:
    void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
                        const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildRemoved(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot ...
    }
    void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
                 error_code, error_message);
    }
  };

  // elsewhere ....

  SessionCommentsChildListener* listener = new SessionCommentsChildListener();
  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

La devolución de llamada OnChildAdded generalmente se usa para recuperar una lista de elementos en una base de datos de Firebase. La devolución de llamada OnChildAdded se llama 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.

La devolución de llamada OnChildChanged se llama 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 las llamadas OnChildAdded y OnChildRemoved para responder a los cambios en una lista de elementos. La instantánea que se pasa al oyente contiene los datos actualizados del niño.

La devolución de llamada OnChildRemoved se activa cuando se elimina un elemento secundario inmediato. Por lo general, se usa junto con las devoluciones de llamada OnChildAdded y OnChildChanged . La instantánea pasada a la devolución de llamada contiene los datos del niño eliminado.

La devolución de llamada OnChildMoved se activa cada OnChildChanged que una actualización provoca la reordenación 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 a una tabla de clasificación de puntuación ordenada por puntuación.

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score");

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

Esto define una base de firebase::Query que, cuando se combina con un ValueListener, 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 llamada OnChildAdded . Si tiene menos de 100 elementos almacenados en su base de datos de Firebase, se activa una devolución de llamada OnChildAdded para cada elemento.

A medida que los elementos cambian, recibe devoluciones de llamada de OnChildAdded para los elementos que ingresan a la consulta y devoluciones de llamada de OnChildRemoved para los elementos que la abandonan para 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:

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

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 ordenan 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, clasificados 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.

Próximos pasos