Abrufen von Daten mit Firebase Realtime Database für C++

In diesem Dokument werden die Grundlagen zum Abrufen von Daten sowie zum Sortieren und Filtern von Firebase-Daten behandelt.

Bevor Sie beginnen

Stellen Sie sicher, dass Sie Ihre App eingerichtet haben und auf die Datenbank zugreifen können, wie im Leitfaden Get Started beschrieben.

Daten abrufen

Firebase-Daten werden entweder durch einen einmaligen Aufruf von GetValue() oder durch Anhängen an einen ValueListener in einer FirebaseDatabase Referenz abgerufen. Der Wert-Listener wird einmal für den Anfangszustand der Daten und jedes Mal, wenn sich die Daten ändern, aufgerufen.

Holen Sie sich eine Datenbankreferenz

Um Daten in die Datenbank zu schreiben, benötigen Sie eine Instanz von DatabaseReference :

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

Daten einmal lesen

Mit der GetValue() Methode können Sie einmalig einen statischen Snapshot des Inhalts in einem bestimmten Pfad lesen. Das Aufgabenergebnis enthält einen Snapshot mit allen Daten an diesem Speicherort, einschließlich untergeordneter Daten. Wenn keine Daten vorhanden sind, ist der zurückgegebene Snapshot null .

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

An dem Punkt, an dem die Anfrage gestellt wurde, müssen wir warten, bis die Zukunft abgeschlossen ist, bevor wir den Wert lesen können. Da Spiele normalerweise in einer Schleife ausgeführt werden und weniger auf Rückrufe angewiesen sind als andere Anwendungen, fragen Sie in der Regel den Abschluss ab.

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

Dies zeigt einige grundlegende Fehlerprüfungen. Weitere Informationen zur Fehlerprüfung und Möglichkeiten zur Bestimmung, wann das Ergebnis bereit ist, finden Sie in der Referenz zu firebase::Future .

Hören Sie auf Ereignisse

Sie können Listener hinzufügen, um Datenänderungen zu abonnieren:

ValueListener Basisklasse

Ruf zurück Typische Verwendung
OnValueChanged Lesen und achten Sie auf Änderungen am gesamten Inhalt eines Pfads.

OnChildListener Basisklasse

OnChildAdded Rufen Sie Artikellisten ab oder warten Sie auf Ergänzungen zu einer Artikelliste. Empfohlene Verwendung mit OnChildChanged und OnChildRemoved , um Änderungen an Listen zu überwachen.
OnChildChanged Achten Sie auf Änderungen an den Elementen in einer Liste. Verwenden Sie es mit OnChildAdded und OnChildRemoved , um Änderungen an Listen zu überwachen.
OnChildRemoved Achten Sie auf Elemente, die aus einer Liste entfernt werden. Verwenden Sie es mit OnChildAdded und OnChildChanged , um Änderungen an Listen zu überwachen.
OnChildMoved Achten Sie auf Änderungen in der Reihenfolge der Elemente in einer geordneten Liste. OnChildMoved Rückrufe folgen immer den OnChildChanged Rückrufen, da sich die Reihenfolge des Artikels ändert (basierend auf Ihrer aktuellen Order-By-Methode).

ValueListener-Klasse

Sie können die OnValueChanged Rückrufe verwenden, um Änderungen am Inhalt an einem bestimmten Pfad zu abonnieren. Dieser Rückruf wird einmal ausgelöst, wenn der Listener angehängt wird, und jedes Mal erneut, wenn sich die Daten, einschließlich untergeordneter Elemente, ändern. Dem Rückruf wird ein Snapshot übergeben, der alle Daten an diesem Speicherort enthält, einschließlich untergeordneter Daten. Wenn keine Daten vorhanden sind, ist der zurückgegebene Snapshot null .

Das folgende Beispiel zeigt ein Spiel, das die Ergebnisse einer Bestenliste aus der Datenbank abruft:

  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);

Das Future&ltDataSnapshot&gt Ergebnis enthält die Daten am angegebenen Ort in der Datenbank zum Zeitpunkt des Ereignisses. Der Aufruf von value() für einen Snapshot gibt einen Variant zurück, der die Daten darstellt.

In diesem Beispiel wird auch die OnCancelled Methode überschrieben, um zu sehen, ob der Lesevorgang abgebrochen wird. Beispielsweise kann ein Lesevorgang abgebrochen werden, wenn der Client keine Berechtigung zum Lesen aus einem Firebase-Datenbankspeicherort hat. Der database::Error gibt an, warum der Fehler aufgetreten ist.

ChildListener-Klasse

Untergeordnete Ereignisse werden als Reaktion auf bestimmte Vorgänge ausgelöst, die den untergeordneten Knoten eines Knotens durch einen Vorgang widerfahren, z. B. ein neues untergeordnetes Element, das über die PushChild() Methode hinzugefügt wird, oder ein untergeordnetes Element, das über die UpdateChildren() Methode aktualisiert wird. Beides zusammen kann nützlich sein, um Änderungen an einem bestimmten Knoten in einer Datenbank abzuhören. Beispielsweise könnte ein Spiel diese Methoden zusammen verwenden, um die Aktivität in den Kommentaren einer Spielsitzung zu überwachen, wie unten gezeigt:

  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);

Der OnChildAdded Rückruf wird normalerweise verwendet, um eine Liste von Elementen in einer Firebase-Datenbank abzurufen. Der OnChildAdded Rückruf wird einmal für jedes vorhandene untergeordnete Element und dann jedes Mal erneut aufgerufen, wenn dem angegebenen Pfad ein neues untergeordnetes Element hinzugefügt wird. Dem Listener wird ein Snapshot übergeben, der die Daten des neuen untergeordneten Elements enthält.

Der OnChildChanged Rückruf wird jedes Mal aufgerufen, wenn ein untergeordneter Knoten geändert wird. Dazu gehören alle Änderungen an Nachkommen des untergeordneten Knotens. Es wird normalerweise in Verbindung mit den Aufrufen OnChildAdded und OnChildRemoved verwendet, um auf Änderungen an einer Liste von Elementen zu reagieren. Der an den Listener übergebene Snapshot enthält die aktualisierten Daten für das untergeordnete Element.

Der OnChildRemoved Rückruf wird ausgelöst, wenn ein unmittelbar untergeordnetes Element entfernt wird. Es wird normalerweise in Verbindung mit den Rückrufen OnChildAdded und OnChildChanged verwendet. Der an den Rückruf übergebene Snapshot enthält die Daten für das entfernte untergeordnete Element.

Der OnChildMoved Rückruf wird immer dann ausgelöst, wenn der OnChildChanged Aufruf durch eine Aktualisierung ausgelöst wird, die eine Neuordnung des untergeordneten Elements verursacht. Es wird mit Daten verwendet, die mit OrderByChild oder OrderByValue geordnet sind.

Daten sortieren und filtern

Sie können die Klasse „Realtime Database Query verwenden, um nach Schlüssel, Wert oder Wert eines untergeordneten Elements sortierte Daten abzurufen. Sie können das sortierte Ergebnis auch nach einer bestimmten Anzahl von Ergebnissen oder einem Bereich von Schlüsseln oder Werten filtern.

Daten sortieren

Um sortierte Daten abzurufen, geben Sie zunächst eine der Order-by-Methoden an, um zu bestimmen, wie die Ergebnisse sortiert werden:

Methode Verwendung
OrderByChild() Ordnen Sie die Ergebnisse nach dem Wert eines angegebenen untergeordneten Schlüssels.
OrderByKey() Sortieren Sie die Ergebnisse nach untergeordneten Schlüsseln.
OrderByValue() Sortieren Sie die Ergebnisse nach untergeordneten Werten.

Sie können jeweils nur eine Order-By-Methode verwenden. Der mehrmalige Aufruf einer Order-By-Methode in derselben Abfrage führt zu einem Fehler.

Das folgende Beispiel zeigt, wie Sie eine nach Punktzahl geordnete Punkte-Bestenliste abonnieren können.

  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.

Dies definiert eine firebase::Query , die in Kombination mit einem ValueListener den Client mit der Bestenliste in der Datenbank synchronisiert, sortiert nach der Punktzahl jedes Eintrags. Weitere Informationen zur effizienten Strukturierung Ihrer Daten finden Sie in Strukturieren Sie Ihre Datenbank .

Der Aufruf der OrderByChild() Methode gibt den untergeordneten Schlüssel an, nach dem die Ergebnisse sortiert werden sollen. In diesem Fall werden die Ergebnisse nach dem Wert des "score" -Werts in jedem Kind sortiert. Weitere Informationen zur Reihenfolge anderer Datentypen finden Sie unter Reihenfolge der Abfragedaten .

Daten filtern

Um Daten zu filtern, können Sie beim Erstellen einer Abfrage jede der Limit- oder Range-Methoden mit einer Order-By-Methode kombinieren.

Methode Verwendung
LimitToFirst() Legt die maximale Anzahl von Elementen fest, die vom Anfang der geordneten Ergebnisliste zurückgegeben werden sollen.
LimitToLast() Legt die maximale Anzahl von Elementen fest, die vom Ende der geordneten Ergebnisliste zurückgegeben werden sollen.
StartAt() Gibt Elemente zurück, die größer oder gleich dem angegebenen Schlüssel oder Wert sind, abhängig von der gewählten Sortiermethode.
EndAt() Gibt Elemente zurück, die kleiner oder gleich dem angegebenen Schlüssel oder Wert sind, abhängig von der gewählten Sortiermethode.
EqualTo() Gibt abhängig von der gewählten Sortiermethode Elemente zurück, die dem angegebenen Schlüssel oder Wert entsprechen.

Im Gegensatz zu den Order-by-Methoden können Sie mehrere Grenzwert- oder Bereichsfunktionen kombinieren. Beispielsweise können Sie die Methoden StartAt() und EndAt() kombinieren, um die Ergebnisse auf einen angegebenen Wertebereich zu beschränken.

Selbst wenn es nur eine einzige Übereinstimmung für die Abfrage gibt, ist der Snapshot immer noch eine Liste; es enthält nur ein einzelnes Element.

Begrenzen Sie die Anzahl der Ergebnisse

Sie können die Methoden LimitToFirst() und LimitToLast() verwenden, um eine maximale Anzahl von untergeordneten Elementen festzulegen, die für einen bestimmten Rückruf synchronisiert werden sollen. Wenn Sie beispielsweise mit LimitToFirst() ein Limit von 100 festlegen, erhalten Sie zunächst nur bis zu 100 OnChildAdded Rückrufe. Wenn in Ihrer Firebase-Datenbank weniger als 100 Elemente gespeichert sind, wird für jedes Element ein OnChildAdded Rückruf ausgelöst.

Wenn sich Elemente ändern, erhalten Sie OnChildAdded Rückrufe für Elemente, die in die Abfrage aufgenommen werden, und OnChildRemoved Rückrufe für Elemente, die aus der Abfrage entfernt werden, sodass die Gesamtzahl bei 100 bleibt.

Der folgende Code gibt beispielsweise die höchste Punktzahl aus einer Bestenliste zurück:

  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.

Nach Schlüssel oder Wert filtern

Sie können StartAt() , EndAt() und EqualTo() verwenden, um beliebige Start-, End- und Äquivalenzpunkte für Abfragen auszuwählen. Dies kann nützlich sein, um Daten zu paginieren oder Elemente mit untergeordneten Elementen zu finden, die einen bestimmten Wert haben.

So werden Abfragedaten geordnet

In diesem Abschnitt wird erläutert, wie Daten durch die einzelnen Order-by-Methoden in der Query Klasse sortiert werden.

OrderByChild

Bei Verwendung von OrderByChild() werden Daten, die den angegebenen untergeordneten Schlüssel enthalten, wie folgt sortiert:

  1. Kinder mit einem null für den angegebenen untergeordneten Schlüssel stehen an erster Stelle.
  2. Als nächstes folgen Kinder mit dem Wert false für den angegebenen Kinderschlüssel. Wenn mehrere untergeordnete Elemente den Wert false haben, werden sie lexikografisch nach Schlüssel sortiert.
  3. Als nächstes folgen Kinder mit dem Wert true für den angegebenen Kinderschlüssel. Wenn mehrere untergeordnete Elemente den Wert true haben, werden sie lexikografisch nach Schlüssel sortiert.
  4. Als nächstes folgen Kinder mit einem numerischen Wert, sortiert in aufsteigender Reihenfolge. Wenn mehrere untergeordnete Knoten denselben numerischen Wert für den angegebenen untergeordneten Knoten haben, werden sie nach Schlüssel sortiert.
  5. Zeichenfolgen kommen nach Zahlen und werden lexikografisch in aufsteigender Reihenfolge sortiert. Wenn mehrere untergeordnete Knoten denselben Wert für den angegebenen untergeordneten Knoten haben, werden sie lexikografisch nach Schlüssel sortiert.
  6. Die Objekte stehen an letzter Stelle und werden lexikografisch nach Schlüssel in aufsteigender Reihenfolge sortiert.

OrderByKey

Wenn Sie OrderByKey() zum Sortieren Ihrer Daten verwenden, werden die Daten in aufsteigender Reihenfolge nach Schlüssel zurückgegeben.

  1. Kinder mit einem Schlüssel, der als 32-Bit-Ganzzahl geparst werden kann, stehen an erster Stelle und werden in aufsteigender Reihenfolge sortiert.
  2. Als nächstes folgen Kinder mit einem Zeichenfolgenwert als Schlüssel, lexikografisch in aufsteigender Reihenfolge sortiert.

OrderByValue

Bei Verwendung von OrderByValue() werden untergeordnete Elemente nach ihrem Wert sortiert. Die Sortierkriterien sind dieselben wie in OrderByChild() , außer dass der Wert des Knotens anstelle des Werts eines angegebenen untergeordneten Schlüssels verwendet wird.

Nächste Schritte