Pobieranie danych za pomocą Bazy danych czasu rzeczywistego Firebase dla C++

Ten dokument zawiera podstawowe informacje o pobieraniu danych oraz o porządkowaniu i filtrowaniu danych Firebase.

Zanim zaczniesz

Upewnij się, że aplikacja jest skonfigurowana i masz dostęp do bazy danych, jak opisano w przewodniku Get Started.

Pobieram dane

Dane Firebase są pobierane przez jednorazowe wywołanie GetValue() lub dołączenie do ValueListener w odwołaniu FirebaseDatabase. Detektor wartości jest wywoływany raz dla stanu początkowego danych i ponownie za każdym razem, gdy dane się zmieniają.

Pobieranie DatabaseReference

Aby zapisać dane w bazie danych, potrzebujesz instancji DatabaseReference:

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

Odczytywanie danych raz

Możesz użyć metody GetValue(), aby jednorazowo odczytać statyczny zrzut zawartości w danej ścieżce. Wynik zadania będzie zawierać zrzut zawierający wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwracany jest zrzut null.

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

W tym momencie żądanie zostało wysłane, ale musimy poczekać na zakończenie obiektu Future, zanim będziemy mogli odczytać wartość. Gry zwykle działają w pętli i są mniej zależne od wywołań zwrotnych niż inne aplikacje, dlatego zwykle trzeba sprawdzać, czy zadanie zostało ukończone.

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

Pokazuje to podstawowe sprawdzanie błędów. Więcej informacji o sprawdzaniu błędów i sposobach określania, kiedy wynik jest gotowy, znajdziesz w dokumentacji firebase::Future.

Nasłuchiwanie zdarzeń

Możesz dodać detektory, aby subskrybować zmiany danych:

Klasa bazowa ValueListener

Klasa bazowa OnChildListener

Klasa ValueListener

Możesz użyć wywołań zwrotnych OnValueChanged, aby subskrybować zmiany zawartości w danej ścieżce. To wywołanie zwrotne jest aktywowane raz, gdy detektor jest dołączony, i ponownie za każdym razem, gdy dane, w tym elementy podrzędne, ulegną zmianie. Do wywołania zwrotnego przekazywany jest zrzut zawierający wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwracany jest zrzut null.

Poniższy przykład pokazuje, jak gra pobiera wyniki z tabeli wyników z bazy danych:

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

Wynik Future&ltDataSnapshot&gt zawiera dane w określonej lokalizacji w bazie danych w momencie wystąpienia zdarzenia. Wywołanie metody value() na zrzucie zwraca obiekt Variant reprezentujący dane.

W tym przykładzie metoda OnCancelled jest również zastępowana, aby sprawdzić, czy odczyt został anulowany. Na przykład odczyt może zostać anulowany, jeśli klient nie ma uprawnień do odczytu z lokalizacji bazy danych Firebase. W database::Error znajdziesz informację o przyczynie błędu.

Klasa ChildListener

Zdarzenia podrzędne są wywoływane w odpowiedzi na określone operacje, które mają miejsce w przypadku elementów podrzędnych węzła, np. dodanie nowego elementu podrzędnego za pomocą metody PushChild() lub zaktualizowanie elementu podrzędnego za pomocą metody UpdateChildren(). Każda z tych metod może być przydatna do nasłuchiwania zmian w konkretnym węźle w bazie danych. Na przykład gra może używać tych metod razem do monitorowania aktywności w komentarzach sesji gry, jak pokazano poniżej:

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

Wywołanie zwrotne OnChildAdded jest zwykle używane do pobierania listy elementów w bazie danych Firebase. Wywołanie zwrotne OnChildAdded jest wywoływane raz dla każdego istniejącego elementu podrzędnego, a następnie za każdym razem, gdy do określonej ścieżki zostanie dodany nowy element podrzędny. Do detektora przekazywany jest zrzut zawierający dane nowego elementu podrzędnego.

Wywołanie zwrotne OnChildChanged jest wywoływane za każdym razem, gdy węzeł podrzędny zostanie zmodyfikowany. Obejmuje to wszelkie zmiany w elementach podrzędnych węzła podrzędnego. Zwykle jest używana w połączeniu z wywołaniami OnChildAdded i OnChildRemoved, aby reagować na zmiany na liście elementów. Zrzut przekazany do detektora zawiera zaktualizowane dane elementu podrzędnego.

Wywołanie zwrotne OnChildRemoved jest aktywowane, gdy usunięte zostanie bezpośrednie dziecko. Zwykle jest używana w połączeniu z wywołaniami zwrotnymi OnChildAdded i OnChildChanged. Zrzut przekazany do wywołania zwrotnego zawiera dane usuniętego elementu podrzędnego.

Wywołanie zwrotne OnChildMoved jest wywoływane za każdym razem, gdy wywołanie OnChildChanged jest wywoływane przez aktualizację, która powoduje zmianę kolejności elementu podrzędnego. Jest używana z danymi uporządkowanymi za pomocą OrderByChild lub OrderByValue.

Sortowanie i filtrowanie danych

Możesz użyć klasy Realtime Database Query, aby pobrać dane posortowane według klucza, wartości lub wartości elementu podrzędnego. Możesz też filtrować posortowane wyniki, aby uzyskać określoną liczbę wyników lub zakres kluczy bądź wartości.

Sortowanie danych

Aby pobrać posortowane dane, zacznij od określenia jednej z metod sortowania, która określi sposób porządkowania wyników:

Możesz używać tylko jednej metody sortowania naraz. Wielokrotne wywołanie metody sortowania w tym samym zapytaniu powoduje błąd.

Poniższy przykład pokazuje, jak możesz zasubskrybować tabelę wyników uporządkowaną według wyniku.

  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.

Definiuje to firebase::Query, który w połączeniu z ValueListener synchronizuje klienta z tabelą wyników w bazie danych, uporządkowaną według wyniku każdego wpisu. Więcej informacji o efektywnym porządkowaniu danych znajdziesz w artykule Struktura bazy danych.

Wywołanie metody OrderByChild() określa klucz podrzędny, według którego mają być porządkowane wyniki. W takim przypadku wyniki są sortowane według wartości "score" w każdym elemencie podrzędnym. Więcej informacji o porządkowaniu innych typów danych znajdziesz w artykule Jak są porządkowane dane zapytań.

Filtrowanie danych

Aby filtrować dane, podczas tworzenia zapytania możesz połączyć dowolną metodę limitu lub zakresu z metodą sortowania.

W przeciwieństwie do metod sortowania możesz łączyć wiele funkcji limitu lub zakresu. Możesz na przykład połączyć metody StartAt() i EndAt(), aby ograniczyć wyniki do określonego zakresu wartości.

Nawet jeśli zapytanie ma tylko jedno dopasowanie, podsumowanie nadal jest listą, ale zawiera tylko jeden element.

Ograniczanie liczby wyników

Możesz użyć metod LimitToFirst() i LimitToLast(), aby ustawić maksymalną liczbę elementów podrzędnych do zsynchronizowania w przypadku danego wywołania zwrotnego. Jeśli na przykład użyjesz LimitToFirst(), aby ustawić limit 100, początkowo otrzymasz tylko maksymalnie 100 wywołań zwrotnych OnChildAdded. Jeśli w bazie danych Firebase masz mniej niż 100 elementów, dla każdego z nich zostanie wywołane wywołanie zwrotne OnChildAdded.

W miarę zmian elementów otrzymujesz wywołania zwrotne OnChildAdded dla elementów, które pojawiają się w zapytaniu, i wywołania zwrotne OnChildRemoved dla elementów, które z niego wypadają, dzięki czemu łączna liczba pozostaje na poziomie 100.

Na przykład poniższy kod zwraca najlepszy wynik z tabeli wyników:

  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.

Filtruj według klucza lub wartości

Możesz używać funkcji StartAt(), EndAt() i EqualTo(), aby wybierać dowolne punkty początkowe, końcowe i równoważne dla zapytań. Może to być przydatne do dzielenia danych na strony lub znajdowania elementów z elementami podrzędnymi o określonej wartości.

Jak są uporządkowane dane z zapytań

W tej sekcji wyjaśniamy, jak dane są sortowane według poszczególnych metod sortowania w klasie Query.

OrderByChild

Gdy używasz metody OrderByChild(), dane zawierające określony klucz podrzędny są porządkowane w ten sposób:

1. Dzieci z wartością null dla określonego klucza podrzędnego są wyświetlane jako pierwsze.
2. Następnie wyświetlane są elementy podrzędne z wartością false dla określonego klucza podrzędnego. Jeśli wiele elementów podrzędnych ma wartość false, są one sortowane leksykograficznie według klucza.
3. Następnie wyświetlane są elementy podrzędne z wartością true dla określonego klucza podrzędnego. Jeśli wiele elementów podrzędnych ma wartość true, są one sortowane leksykograficznie według klucza.
4. Następnie wyświetlane są elementy podrzędne z wartością liczbową, posortowane w kolejności rosnącej. Jeśli kilka elementów podrzędnych ma tę samą wartość liczbową dla określonego węzła podrzędnego, są one sortowane według klucza.
5. Ciągi znaków występują po liczbach i są sortowane leksykograficznie w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość dla określonego węzła podrzędnego, są one uporządkowane leksykograficznie według klucza.
6. Obiekty są na końcu i są sortowane leksykograficznie według klucza w kolejności rosnącej.

OrderByKey

Gdy używasz OrderByKey() do sortowania danych, są one zwracane w kolejności rosnącej według klucza.

1. Najpierw wyświetlane są elementy podrzędne z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, posortowane w kolejności rosnącej.
2. Następnie wyświetlane są elementy podrzędne z wartością ciągu znaków jako kluczem, posortowane leksykograficznie w porządku rosnącym.

OrderByValue

Gdy używasz OrderByValue(), elementy podrzędne są uporządkowane według wartości. Kryteria sortowania są takie same jak w przypadku OrderByChild(), ale zamiast wartości określonego klucza podrzędnego używana jest wartość węzła.

Następne kroki

• Zapisywanie danych