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

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

Zanim zaczniesz

Upewnij się, że skonfigurowałaś/skonfigurowałeś aplikację i masz dostęp do bazy danych zgodnie z instrukcjami podanymi w przewodniku Get Started.

Pobieranie danych

Dane Firebase są pobierane przez jednorazowe wywołanie funkcji GetValue() lub przez dołączenie do funkcji ValueListener odwołania FirebaseDatabase. Wartość detektor jest wywoływany raz w przypadku początkowego stanu danych i ponownie w dowolnym momencie zmian danych.

Pobieranie obiektu DatabaseReference

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

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

Odczytaj dane raz

Aby odczytać statyczny zrzut treści w danym miejscu, możesz użyć metody GetValue(). Wynik zadania będzie zawierał zrzut który zawiera wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwrócony zrzut to null.

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

Otrzymaliśmy już wprawdzie wniosek, ale musimy poczekać na przed odczytaniem wartości. Gry zwykle działają w pętli i nie są tak zależne od wywołań zwrotnych jak inne aplikacje, dlatego zwykle sprawdzasz, czy proces został ukończony.

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

Tutaj znajdziesz podstawowe informacje o sprawdzaniu błędów. Zobacz Więcej informacji o firebase::Future o sprawdzaniu błędów i sposobach ustalenia, kiedy wynik jest gotowy.

Nasłuchiwanie zdarzeń

Możesz dodać detektorów, aby subskrybować zmiany w danych:

ValueListener klasa bazowa

Oddzwanianie	Typowe zastosowanie
OnValueChanged	Odczyt i nasłuchiwanie zmian w całej zawartości ścieżki.

OnChildListener klasa bazowa

OnChildAdded	Pobieranie list elementów lub słuchanie, czy dodano elementy do listy. Sugerowane użycie z elementami OnChildChanged i OnChildRemoved do monitorowania zmian w listach.
OnChildChanged	Wykrywaj zmiany wprowadzone w elementach na liście. Używaj elementów OnChildAdded i OnChildRemoved, aby monitorować zmiany w listach.
OnChildRemoved	Nasłuchuj elementów usuwanych z listy. Używaj elementów OnChildAdded i OnChildChanged, aby monitorować zmiany w listach.
OnChildMoved	Wykrywaj zmiany kolejności elementów na liście uporządkowanej. Wywołania zwrotne OnChildMoved zawsze następują po wywołaniach zwrotnych OnChildChanged, ponieważ kolejność produktów może się zmieniać (zgodnie z bieżącą metodą sortowania).

Klasa ValueListener

Za pomocą wywołań zwrotnych OnValueChanged można zasubskrybować zmiany w treści na danej ścieżce. To wywołanie zwrotne jest wywoływane raz, gdy detektor za każdym razem, gdy dane, w tym elementy podrzędne, zostaną zmienione. wywołanie zwrotne jest przekazywane do zrzutu zawierającego wszystkie dane w danej lokalizacji, w tym danych dziecka. Jeśli nie ma żadnych danych, zwracany jest obraz null.

Ważne: zdarzenie OnValueChanged jest wywoływane za każdym razem, gdy dane w określonej bazie danych ulegają zmianie, w tym zmiany w podrzędnych elementach. Aby ograniczyć rozmiar zrzutów ekranu, załącz tylko te na najwyższym poziomie, który jest potrzebny do obserwowania zmian. Nie zalecamy na przykład dołączania listenera do katalogu głównego bazy danych.

Ten przykład pokazuje grę, która pobiera z bazy danych wyniki z tablicy liderów:

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

Wynik Future&ltDataSnapshot&gt zawiera dane w określonej lokalizacji w bazie danych w momencie zdarzenia. Wywołuję value() podczas zrzutu zwraca Variant reprezentujący dane.

W tym przykładzie metoda OnCancelled również została zastąpiona, 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. database::Error wskazuje, dlaczego wystąpił błąd.

Klasa ChildListener

Zdarzenia podrzędne są wywoływane w reakcji na określone operacje elementu podrzędnego węzła pochodzącego z operacji, takiej jak nowy element podrzędny dodany za pomocą funkcji Metoda PushChild() lub element podrzędny aktualizowany za pomocą interfejsu UpdateChildren() . Każdy z nich może być przydatny do monitorowania zmian w konkretnym węźle w bazie danych. Na przykład gra może używać tych metod monitorują aktywność w komentarzach do sesji gry, jak widać 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<firebase::database::DataSnapshot> result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

Zwykle funkcja zwracana przez wywołanie zwrotne OnChildAdded służy do pobierania listy elementów z bazy danych Firebase. Funkcja OnChildAdded jest wywoływana raz dla każdego istniejącego elementu podrzędnego, a potem za każdym razem, gdy do określonej ścieżki zostanie dodany nowy element podrzędny. Listenerowi przekazywany jest migawkowy obraz zawierający dane nowego elementu podrzędnego.

Funkcja OnChildChanged jest wywoływana za każdym razem, gdy nastąpi zmiana węzła podrzędnego. Obejmuje to wszelkie modyfikacje elementów podrzędnych węzła podrzędnego. Jest zwykle używane w połączeniu z OnChildAdded i OnChildRemoved w odpowiedzi na zmiany na liście elementów. Zrzut przekazany do detektor zawiera zaktualizowane dane elementu podrzędnego.

Funkcja OnChildRemoved jest wywoływana, gdy usuwasz bezpośredni podelement. Jest ona zwykle używana w połączeniu z funkcjami zwrotnymi OnChildAdded i OnChildChanged. Zrzut podany do funkcji zwracającej dane zawiera dane dotyczące usuniętego elementu podrzędnego.

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

Sortowanie i filtrowanie danych

Możesz użyć klasy Realtime Database Query, aby pobrać dane posortowane według według klucza, wartości lub wartości elementu podrzędnego. Możesz też ograniczyć liczbę wyników do określonej liczby lub do zakresu kluczy bądź wartości.

Uwaga: filtrowanie i sortowanie mogą być kosztowne, zwłaszcza gdy są wykonywane na kliencie. Jeśli Twoja aplikacja korzysta z zapytań, zdefiniuj regułę .indexOn, aby indeksować te klucze na serwerze i poprawić wydajność zapytań zgodnie z opisem w artykule Indeksowanie danych.

Sortowanie danych

Aby pobrać posortowane dane, najpierw określ jedną z metod sortowania, która określi sposób sortowania wyników:

Metoda	Wykorzystanie
OrderByChild()	Uporządkuj wyniki według wartości określonego klucza podrzędnego.
OrderByKey()	Uporządkuj wyniki według kluczy podrzędnych.
OrderByValue()	Uporządkuj wyniki według wartości podrzędnych.

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

Ten przykład pokazuje, jak można subskrybować tabelę wyników z rankingiem 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.

Określa ona obiekt firebase::Query, który w połączeniu z ValueListener synchronizuje klienta z listą liderów w bazie danych, posortowaną według wyniku każdego wpisu. Więcej informacji o skutecznym uporządkowaniu danych znajdziesz w artykule Uporządkuj bazę danych.

Wywołanie metody OrderByChild() określa klucz podrzędny, według którego mają być posortowane wyniki. W tym przypadku wyniki są sortowane według wartości atrybutu "score" w każdym podrzędnym. Aby dowiedzieć się więcej o kolejności innych typów danych, przeczytaj artykuł o porządkowaniu danych w zapytaniach.

Filtrowanie danych

Aby filtrować dane, możesz połączyć dowolne metody limitów lub zakresów za pomocą funkcji kolejność według metody podczas tworzenia zapytania.

Metoda	Wykorzystanie
LimitToFirst()	Określa maksymalną liczbę elementów do zwrócenia z początku uporządkowanej listy wyników.
LimitToLast()	Określa maksymalną liczbę produktów do zwrócenia od końca zamówionego produktu z listą wyników.
StartAt()	Zwraca elementy większe lub równe określonemu kluczowi lub wartościowi w zależności od wybranej metody sortowania.
EndAt()	Zwraca elementy, których klucz lub wartość jest mniejszy lub równy określonemu kluczowi lub wartości, w zależności od wybranej metody sortowania.
EqualTo()	Zwraca elementy równe określonemu kluczowi lub określonej wartości w zależności od wybranej metody sortowania.

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

Nawet wtedy, gdy zapytanie ma tylko 1 pasujący element, snapshot jest nadal listą, ale zawiera tylko 1 element.

Ograniczanie liczby wyników

Możesz użyć metod LimitToFirst() i LimitToLast(), aby ustawić maksymalna liczba dzieci do zsynchronizowania w przypadku danego wywołania zwrotnego. Na przykład, jeśli używasz aplikacji LimitToFirst(), aby ustawić limit wynoszący 100, początkowo otrzymasz tylko do 100 wywołań zwrotnych OnChildAdded. Jeśli na bazy danych Firebase, dla każdego elementu uruchamia się wywołanie zwrotne OnChildAdded.

W miarę zmiany elementów otrzymujesz OnChildAdded wywołań zwrotnych dla elementów, które zostały wprowadzone oraz wywołania zwrotne OnChildRemoved dla elementów, które z niego opuszczają, tak aby łączna liczba pozostaje na poziomie 100.

Na przykład poniższy kod zwraca najwyższy 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żyć dowolnych danych StartAt(), EndAt() i EqualTo() początkowym, końcowym i równoważnym dla zapytań. Może to być przydatne dla: dzielenie danych na strony lub znajdowanie elementów z dziećmi, które mają określoną wartość.

Sposób porządkowania danych zapytań

W tej sekcji omówiono sposób sortowania danych według poszczególnych metod Query zajęcia.

OrderByChild

Gdy używasz OrderByChild(), dane zawierające określony klucz podrzędny są w następującej kolejności:

1. Najpierw są wyświetlane elementy podrzędne, dla których wartość atrybutu podrzędnego null jest równa null.
2. Elementy podrzędne z wartością false określonego klucza podrzędnego co dalej. Jeśli wiele elementów podrzędnych ma wartość false, są one sortowane alfabetycznie według klucza.
3. Następnie podawane są elementy podrzędne, dla których wartość określonego klucza podrzędnego to true. Jeśli kilka elementów podrzędnych ma wartość true, są one sortowane alfabetycznie według klucza.
4. Następne są elementy podrzędne z wartością liczbową, posortowane w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość numeryczną w przypadku określonego węzła podrzędnego, są one sortowane według klucza.
5. Ciągi znaków znajdują się po liczbach i są sortowane leksykograficznie w kolejności rosnącej zamówienie. Jeśli wiele elementów podrzędnych ma tę samą wartość w wybranym węźle podrzędnym, są one uporządkowane alfabetycznie 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 opcji OrderByKey() do sortowania danych, dane są zwracane w kolejności rosnącej według klucza.

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

OrderByValue

Gdy używasz metody OrderByValue(), elementy podrzędne są uporządkowane według wartości. Kolejność kryteria są takie same jak w OrderByChild(), z wyjątkiem wartości węzła zamiast wartości określonego klucza podrzędnego.

Następne kroki

• Zapisywanie danych