Recupera datos con Firebase Realtime Database para C++

En este documento, se tratan los aspectos básicos de la recuperación de datos y cómo ordenar y filtrar datos en Firebase.

Antes de comenzar

Asegúrate de que la app esté configurada y de que puedas acceder a la base de datos, como se indica en la guía Get Started.

Recupera datos

Para recuperar datos en Firebase, debes hacer una llamada única a GetValue() o adjuntar un evento ValueListener en una referencia FirebaseDatabase. El objeto de escucha se llama una vez para el estado inicial de los datos y de nuevo cada vez que cambien los datos.

Obtén una DatabaseReference

Para escribir en la base de datos, necesitas una instancia de DatabaseReference:

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

Lee los datos una sola vez

Puedes usar el método GetValue() para leer una instantánea estática del contenido de una ruta específica una vez. El resultado de la tarea contendrá una instantánea con todos los datos de esa ubicación, incluidos los de nivel secundario. Si no hay datos, la instantánea tiene el valor null.

  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").GetValue();

En este momento, la solicitud ya se hizo, pero tenemos que esperar a que se complete la interfaz Future antes de leer el valor. Dado que los juegos tienden a ejecutarse en bucle y usan menos devoluciones de llamadas que otras aplicaciones, lo normal es hacer un sondeo para determinar si se completó la operación.

  // 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...
    }
  }

En este ejemplo, vemos una técnica básica de verificación de errores. Consulta la referencia firebase::Future para obtener más información sobre la verificación de errores y las maneras de determinar cuando el resultado está listo.

Detecta eventos

Puedes agregar objetos de escucha para suscribirte a los cambios en los datos:

Clase básica ValueListener

Clase básica OnChildListener

Clase ValueListener

Puedes usar las devoluciones de llamada OnValueChanged para suscribirte a los cambios del contenido de una ruta de acceso determinada. Esta devolución de llamada se activa cuando se adjunta el objeto de escucha y nuevamente cada vez que cambian los datos (incluidos los del nivel secundario). La devolución de llamada recibe una instantánea que contiene todos los datos de esa ubicación, incluidos los datos de nivel secundario. Si no hay datos, la instantánea tiene el valor null.

El siguiente ejemplo demuestra un juego que recupera las puntuaciones de una tabla de clasificación en 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&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

El resultado Future&ltDataSnapshot&gt contiene los datos en la ubicación especificada de la base de datos en el momento del evento. Si llamas a value() sobre una instantánea, se muestra un Variant que representa los datos.

En este ejemplo, el método OnCancelled también se anula para ver si la lectura se cancela. Por ejemplo, una lectura puede cancelarse si el cliente no tiene permiso para leer datos de una ubicación en la base de datos de Firebase. El database::Error indicará por qué se produjo el error.

Clase ChildListener

Los eventos secundarios se activan en respuesta a operaciones específicas que se ejecutan en los elementos secundarios de un nodo a partir de una operación, como un elemento secundario nuevo que se agrega 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, en combinación, puede ser útil para detectar cambios en un nodo específico de una base de datos. Por ejemplo, un juego podría usar estos métodos en combinación para supervisar la actividad en los comentarios de una sesión del 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&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

La devolución de llamada OnChildAdded se usa normalmente para recuperar una lista de elementos en una base de datos de Firebase. Se llama a la devolución de llamada OnChildAdded una vez por cada elemento secundario existente y de nuevo cada vez que se agrega un elemento secundario nuevo a la ruta de acceso especificada. El objeto de escucha recibe una instantánea que contiene los datos del nuevo elemento secundario.

La devolución de llamada OnChildChanged se invoca cada vez que se modifica un nodo secundario. Esto incluye cualquier modificación en descendientes del nodo secundario. Por lo general, se usa en combinación con las llamadas OnChildAdded y OnChildRemoved para responder a cambios en una lista de elementos. La instantánea que se pasa al objeto de escucha contiene los datos actualizados del elemento secundario.

La devolución de llamada OnChildRemoved se activa cuando se quita un campo secundario inmediato. Por lo general, se usa en combinación con OnChildAdded y OnChildChanged. La instantánea que se pasa a la devolución de llamada contiene los datos del elemento secundario que se quitó.

La devolución de llamada OnChildMoved se activa siempre que se genera una llamada OnChildChanged debido a una actualización que hace que se cambie el orden de ese elemento secundario. Se usa con datos que se ordenan con OrderByChild o OrderByValue.

Cómo ordenar y filtrar datos

Puedes usar la clase Query de Realtime Database para recuperar los datos organizados por clave, por valor o por valor del elemento secundario. También puedes filtrar el resultado ordenado de acuerdo con una cantidad específica de resultados o un rango de claves o valores.

Ordena los datos

Para recuperar datos ordenados, comienza por especificar uno de los métodos de ordenamiento, a fin de determinar cómo se presentarán los resultados:

Puedes usar solo un método de ordenamiento a la vez. Si invocas un método de ordenamiento varias veces en la misma consulta, se genera un error.

El siguiente ejemplo demuestra cómo podrías suscribirte a una tabla de clasificación de puntuaciones ordenada por puntaje.

  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 firebase::Query que, cuando se combina con un ValueListener, sincroniza el cliente con la tabla de clasificación en la base de datos, ordenada según la puntuación de cada entrada. Para obtener más información sobre cómo estructurar tus datos en forma eficiente, consulta Estructura tu base de datos.

La llamada al método OrderByChild() especifica la clave secundaria según la que se deben ordenar los resultados. En este caso, los resultados se ordenan según el valor de "score" en cada elemento secundario. Para obtener más información sobre cómo se ordenan otros tipos de datos, consulta la sección Cómo se ordenan los datos de las consultas.

Cómo filtrar datos

Para filtrar datos, puedes combinar cualquiera de los métodos de límite o rango con un método de ordenamiento cuando generes una consulta.

A diferencia de los métodos de ordenamiento, se puede combinar varias funciones de límite y rango. Por ejemplo, puedes combinar los métodos StartAt() y EndAt() para limitar los resultados a un rango de valores específico.

Incluso cuando hay una sola coincidencia para la consulta, la instantánea es una lista, aunque contenga un solo elemento.

Limita la cantidad de resultados

Puedes usar los métodos LimitToFirst() y LimitToLast() a fin de establecer una cantidad máxima de elementos secundarios que se sincronicen para una devolución de llamada determinada. Por ejemplo, si usas LimitToFirst() para establecer un límite de 100, inicialmente solo recibes hasta 100 devoluciones de llamada de tipo OnChildAdded. Si hay menos de 100 elementos almacenados en la base de datos de Firebase, se activa una devolución de llamada OnChildAdded por cada elemento.

A medida que los elementos cambien, recibirás devoluciones de llamadas de tipo OnChildAdded por los elementos que ingresen en la consulta y devoluciones de llamadas de tipo OnChildRemoved por los elementos que queden fuera para que la cantidad total continúe siendo 100.

Por ejemplo, el siguiente fragmento de código muestra la primera puntuación de la 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.

Filtra por clave o valor

Puedes usar StartAt(), EndAt() y EqualTo() a fin de elegir puntos de inicio, finalización y equivalencia arbitrarios para las consultas. Esto puede ser útil para paginar datos o encontrar elementos con campos secundarios que tengan un valor específico.

Cómo se ordenan los datos de las consultas

En esta sección, se explica cómo se ordenan los datos en cada uno de los métodos de ordenamiento de la clase Query.

OrderByChild

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

1. Los elementos secundarios cuyas claves secundarias especificadas posean el valor null irán en primer lugar.
2. A continuación, aparecerán los elementos secundarios que tengan el valor false en la clave secundaria especificada. Si hay varios elementos secundarios con el valor false, se ordenan lexicográficamente por clave.
3. A continuación, aparecerán los elementos secundarios que tengan el valor true en la clave secundaria especificada. Si hay varios elementos secundarios con el valor true, se ordenan lexicográficamente por clave.
4. Luego vienen los elementos secundarios con valor numérico, que se ordenan en sentido ascendente. Si varios elementos secundarios tienen el mismo valor numérico en el nodo secundario especificado, se ordenan según la clave.
5. Las strings van después de los números y se ordenan de manera lexicográfica, en sentido ascendente. Si varios elementos secundarios tienen el mismo valor en el nodo secundario especificado, se ordenan de manera lexicográfica según la clave.
6. Los objetos quedan en último lugar y se ordenan de manera lexicográfica según su clave, en orden ascendente.

OrderByKey

Cuando ordenas los datos con OrderByKey(), estos se muestran en orden ascendente, según la clave.

1. Los elementos secundarios con una clave que puede analizarse como un número entero de 32 bits van primero, ordenados en sentido ascendente.
2. Los elementos secundarios con un valor de string como clave van después y ordenados de manera lexicográfica, en sentido ascendente.

OrderByValue

Cuando usas OrderByValue(), los elementos secundarios se ordenan según el valor. Se utiliza el mismo criterio de orden que para OrderByChild(), excepto que se usa el valor del nodo en lugar del valor de una clave secundaria especificada.

Próximos pasos

• Guarda datos