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

Z tego dokumentu dowiesz się, jak pobierać dane oraz jak sortować i filtrować dane Firebase.

Zanim zaczniesz

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

Pobieram dane

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

Pobieranie DatabaseReference

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

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

Jednorazowe odczytywanie danych

Za pomocą metody GetValue() możesz jednorazowo odczytać statyczny zrzut zawartości w danej ścieżce. Wynik zadania będzie zawierać zrzut ze wszystkimi danymi w tej lokalizacji, w tym z danymi podrzędnymi. Jeśli nie ma danych, zwrócony zrzut to null.

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

W momencie wysłania żądania musimy poczekać na zakończenie przyszłości, zanim będziemy mogli odczytać wartość. Ponieważ gry zwykle działają w pętli i są mniej oparte na wywołaniach zwrotnych niż inne aplikacje, zwykle będziesz sprawdzać, czy zadanie zostało wykonane.

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

Pokazujemy tu 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 dodawać detektory, aby subskrybować zmiany danych:

Klasa bazowa ValueListener

Klasa bazowa OnChildListener

Klasa ValueListener

Za pomocą wywołań zwrotnych OnValueChanged możesz subskrybować zmiany zawartości w danej ścieżce. To wywołanie zwrotne jest wywoływane raz po dołączeniu detektora i ponownie za każdym razem, gdy zmienią się dane, w tym dane podrzędne. Do wywołania zwrotnego przekazywany jest zrzut zawierający wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwrócony zrzut to 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 zdarzenia. Wywołanie value() w zrzucie zwraca Variant reprezentujący dane.

W tym przykładzie zastąpiono też metodę OnCancelled, aby sprawdzić, czy odczyt został anulowany. Odczyt może zostać anulowany, jeśli klient nie ma uprawnień do odczytu z lokalizacji w bazie danych Firebase. Wartość database::Error wskazuje przyczynę niepowodzenia.

Klasa ChildListener

Zdarzenia podrzędne są wywoływane w odpowiedzi na określone operacje wykonywane na elementach podrzędnych węzła, takie jak 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 określonym węźle w bazie danych. Na przykład gra może używać tych metod razem do monitorowania aktywności w komentarzach do 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 modyfikacje elementów podrzędnych węzła podrzędnego. Jest zwykle używane w połączeniu z wywołaniami OnChildAdded i OnChildRemoved, aby reagować na zmiany na liście elementów. Zrzut przekazywany do detektora zawiera zaktualizowane dane elementu podrzędnego.

Wywołanie zwrotne OnChildRemoved jest wywoływane, gdy zostanie usunięty bezpośredni element podrzędny. Jest zwykle używane w połączeniu z wywołaniami zwrotnymi OnChildAdded i OnChildChanged. Zrzut przekazywany 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żywane z danymi, które są uporządkowane za pomocą OrderByChild lub OrderByValue.

Sortowanie i filtrowanie danych

Za pomocą klasy Realtime Database Query możesz pobierać dane posortowane według klucza, wartości lub wartości elementu podrzędnego. Możesz też filtrować posortowany wynik do określonej liczby wyników lub zakresu kluczy lub wartości.

Sortowanie danych

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

W danym momencie możesz używać tylko jednej metody sortowania. Wywołanie metody sortowania kilka razy w tym samym zapytaniu powoduje błąd.

Poniższy przykład pokazuje, jak możesz subskrybować tabelę wyników posortowaną 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óre w połączeniu z ValueListener synchronizuje klienta z tabelą wyników w bazie danych, posortowaną według wyniku każdego wpisu. Więcej informacji o efektywnym strukturyzowaniu danych znajdziesz w artykule Strukturyzowanie bazy danych.

Wywołanie metody OrderByChild() określa klucz podrzędny, według którego mają być sortowane wyniki. W tym przypadku wyniki są sortowane według wartości "score" w każdym elemencie podrzędnym. Więcej informacji o tym, jak są sortowane inne typy danych, zobacz Jak są sortowane dane zapytań.

Filtrowanie danych

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

W przeciwieństwie do metod sortowania możesz łączyć kilka 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 pasuje tylko do 1 elementu, zrzut nadal jest listą, tylko zawiera 1 element.

Ograniczanie liczby wyników

Za pomocą metod LimitToFirst() i LimitToLast() możesz ustawić maksymalną liczbę elementów podrzędnych, które mają być synchronizowane w przypadku danego wywołania zwrotnego. Jeśli na przykład użyjesz LimitToFirst() do ustawienia limitu 100, początkowo otrzymasz tylko do 100 wywołań zwrotnych OnChildAdded. Jeśli w bazie danych Firebase masz mniej niż 100 elementów, wywołanie zwrotne OnChildAdded jest wywoływane dla każdego elementu.

Gdy elementy się zmieniają, otrzymujesz wywołania zwrotne OnChildAdded dla elementów, które wchodzą w zakres zapytania, oraz 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.

Filtrowanie według klucza lub wartości

Za pomocą StartAt(), EndAt() i EqualTo() możesz wybrać dowolne punkty początkowe, końcowe i równoważne dla zapytań. Może to być przydatne do paginacji danych lub znajdowania elementów z elementami podrzędnymi o określonej wartości.

Jak są sortowane dane zapytań

W tej sekcji wyjaśniamy, jak dane są sortowane przez każdą z metod sortowania w klasie Query.

OrderByChild

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

1. Najpierw są wyświetlane elementy podrzędne z wartością null dla określonego klucza podrzędnego.
2. Następnie są wyświetlane elementy podrzędne z wartością false dla określonego klucza podrzędnego. Jeśli kilka elementów podrzędnych ma wartość false, są one sortowane leksykograficznie według klucza.
3. Następnie są wyświetlane elementy podrzędne z wartością true dla określonego klucza podrzędnego. Jeśli kilka elementów podrzędnych ma wartość true, są one sortowane leksykograficznie według klucza.
4. Następnie są wyświetlane 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. Po liczbach występują ciągi znaków, które są sortowane leksykograficznie w kolejności rosnącej. Jeśli kilka elementów podrzędnych ma tę samą wartość dla określonego węzła podrzędnego, są one sortowane leksykograficznie według klucza.
6. Obiekty są wyświetlane na końcu i sortowane leksykograficznie według klucza w kolejności rosnącej.

OrderByKey

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

1. Najpierw są wyświetlane 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 są wyświetlane elementy podrzędne z wartością ciągu znaków jako kluczem, posortowane leksykograficznie w kolejności rosnącej.

OrderByValue

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

Następne kroki

• Zapisywanie danych