Pobieram dane

W tym dokumencie znajdziesz podstawowe informacje o pobieraniu danych oraz sposobie ich porządkowania i filtrowania.

Zanim zaczniesz

Zanim użyjesz Bazy danych czasu rzeczywistego, musisz wykonać te czynności:

  • Zarejestruj projekt Unity i skonfiguruj go pod kątem korzystania z Firebase.

    • Jeśli Twój projekt w Unity korzysta już z Firebase, oznacza to, że został zarejestrowany i skonfigurowany pod kątem Firebase.

    • Jeśli nie masz projektu w Unity, możesz pobrać przykładową aplikację.

  • Dodaj pakiet SDK Firebase Unity (a konkretnie FirebaseDatabase.unitypackage) do projektu Unity.

Pamiętaj, że dodanie Firebase do projektu Unity wymaga wykonania zadań zarówno w konsoli Firebase, jak i w otwartym projekcie Unity (np. musisz pobrać z konsoli pliki konfiguracyjne Firebase, a następnie przenieść je do projektu Unity).

Pobieram dane

Dane Firebase są pobierane przez jednorazowe wywołanie metody GetValueAsync() lub przez załączenie do zdarzenia w odwołaniem FirebaseDatabase. Detektor zdarzeń jest wywoływany jeden raz dla początkowego stanu danych i ponownie przy każdej zmianie danych.

Pobieranie odniesienia do bazy danych

Aby odczytać dane z bazy danych, potrzebujesz instancji DatabaseReference:

using Firebase;
using Firebase.Database;
using Firebase.Extensions.TaskExtension; // for ContinueWithOnMainThread

public class MyScript: MonoBehaviour {
  void Start() {
    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

Odczytaj dane raz

Metoda GetValueAsync pozwala 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, zwrócony zrzut ma wartość null.

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWithOnMainThread(task => {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

Nasłuchiwanie zdarzeń

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

Zdarzenie Typowe zastosowanie
ValueChanged Odczyt i nasłuchiwanie zmian w całej zawartości ścieżki.
ChildAdded Pobieranie list elementów lub słuchanie, czy dodano elementy do listy. Sugerowane użycie z funkcjami ChildChanged i ChildRemoved do monitorowania zmian na listach.
ChildChanged Wykrywaj zmiany wprowadzone w elementach na liście. Używaj z ChildAdded i ChildRemoved do monitorowania zmian na listach.
ChildRemoved Nasłuchuj elementów usuwanych z listy. Używaj z ChildAdded i ChildChanged do monitorowania zmian na listach.
ChildMoved Wykrywaj zmiany kolejności elementów na liście uporządkowanej. Zdarzenia ChildMoved zawsze występują po zdarzeniu ChildChanged, które spowodowało zmianę kolejności produktów (na podstawie bieżącej metody sortowania).

Zdarzenie ValueChanged

Za pomocą zdarzenia ValueChanged możesz subskrybować zmiany treści na danej ścieżce. To zdarzenie jest wywoływane raz po podłączeniu detektora i ponownie za każdym razem, gdy dane, w tym elementy podrzędne, zostaną zmienione. Wywołanie zwrotne zdarzenia jest przekazywane do zrzutu zawierającego wszystkie dane w danej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwrócony zrzut ma wartość null.

Ten przykład przedstawia grę, która pobiera wyniki tabeli wyników z bazy danych:

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

ValueChangedEventArgs zawiera obiekt DataSnapshot, który zawiera dane z określonej lokalizacji w bazie danych w momencie wystąpienia zdarzenia. Wywołanie Value w zrzucie zwraca Dictionary<string, object> reprezentujący dane. Jeśli w danej lokalizacji nie ma danych, wywołanie funkcji Value zwróci wartość null.

W tym przykładzie funkcja args.DatabaseError jest również sprawdzana w celu sprawdzenia, czy odczyt został anulowany. Na przykład odczyt można anulować, jeśli klient nie ma uprawnień do odczytu lokalizacji bazy danych Firebase. DatabaseError poinformuje o przyczynie wystąpienia błędu.

Później możesz anulować subskrypcję tego zdarzenia za pomocą dowolnego elementu DatabaseReference o tej samej ścieżce. Instancje DatabaseReference są efemeryczne i można je traktować jako dostęp do dowolnej ścieżki i zapytania.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged.
    }

Zdarzenia podrzędne

Zdarzenia podrzędne są wywoływane w odpowiedzi na określone operacje wykonywane na elementach podrzędnych węzła w wyniku operacji, np. dodania nowego elementu podrzędnego za pomocą metody Push() lub aktualizacji elementu podrzędnego za pomocą metody UpdateChildrenAsync(). Każdy z tych elementów może być przydatny do nasłuchiwania zmian w konkretnym węźle w bazie danych. Na przykład gra może używać tych metod do monitorowania aktywności w komentarzach do sesji gry, jak pokazano poniżej:

      var ref = FirebaseDatabase.DefaultInstance
      .GetReference("GameSessionComments");

      ref.ChildAdded += HandleChildAdded;
      ref.ChildChanged += HandleChildChanged;
      ref.ChildRemoved += HandleChildRemoved;
      ref.ChildMoved += HandleChildMoved;
    }

    void HandleChildAdded(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildChanged(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildRemoved(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildMoved(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

Zdarzenie ChildAdded jest zwykle używane do pobierania listy elementów z bazy danych Firebase. Zdarzenie ChildAdded jest wywoływane raz dla każdego istniejącego elementu podrzędnego, a potem za każdym razem, gdy do wskazanej ścieżki zostanie dodany nowy element podrzędny. Detektor przekazuje zrzut zawierający dane nowego elementu podrzędnego.

Zdarzenie ChildChanged jest wywoływane po każdej modyfikacji węzła podrzędnego. Obejmuje to wszelkie modyfikacje elementów podrzędnych węzła podrzędnego. Zwykle używa się go w połączeniu ze zdarzeniami ChildAdded i ChildRemoved w odpowiedzi na zmiany na liście elementów. Zrzut przekazany do detektora zdarzeń zawiera zaktualizowane dane dotyczące elementu podrzędnego.

Zdarzenie ChildRemoved jest wyzwalane po usunięciu natychmiastowego elementu podrzędnego. Zwykle jest używany w połączeniu z wywołaniami ChildAdded i ChildChanged. Zrzut przekazany do wywołania zwrotnego zdarzenia zawiera dane usuniętego elementu podrzędnego.

Zdarzenie ChildMoved jest wywoływane za każdym razem, gdy aktualizacja powoduje zmianę kolejności elementów podrzędnych, które wywołały zdarzenie ChildChanged. Jest używany z danymi uporządkowanych według: OrderByChild lub OrderByValue.

Sortowanie i filtrowanie danych

Za pomocą klasy Query Bazy danych czasu rzeczywistego możesz pobrać dane posortowane według klucza, wartości lub wartości elementu podrzędnego. Możesz też filtrować posortowany wynik według określonej liczby wyników lub zakresu kluczy bądź wartości.

Sortowanie danych

Aby pobrać posortowane dane, zacznij od określenia jednej z metod ustalania kolejności 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. Wielokrotne wywołanie metody „order by by” w tym samym zapytaniu powoduje błąd.

Ten przykład pokazuje, jak zasubskrybować tabelę wyników uporządkowanych według wyniku.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders").OrderByChild("score")
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

Definiuje zapytanie, które w połączeniu z detektorem zdarzeń valuechanged powoduje synchronizację klienta z tabelą wyników w bazie danych w kolejności zgodnej z wynikami poszczególnych wpisów. Więcej informacji o efektywnym strukturze danych znajdziesz w artykule Struktura 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 wartości "score" w każdym elemencie podrzędnym. Więcej informacji o kolejności innych typów danych znajdziesz w sekcji Informacje o kolejności danych w zapytaniach.

Filtrowanie danych

Aby filtrować dane, podczas tworzenia zapytania możesz połączyć dowolne metody limitów lub zakresów z metodą porządkowania.

Metoda Wykorzystanie
LimitToFirst() Określa maksymalną liczbę elementów do zwrócenia od początku uporządkowanej listy wyników.
LimitToLast() Określa maksymalną liczbę elementów do zwrócenia na końcu uporządkowanej listy wyników.
StartAt() Zwraca elementy większe lub równe określonemu kluczowi lub wartości w zależności od wybranej metody sortowania.
EndAt() Zwraca elementy mniejsze lub równe określonemu kluczowi bądź wartości w zależności od wybranej metody sortowania.
EqualTo() Zwraca elementy równe określonemu kluczowi lub 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 np. łączyć metody StartAt() i EndAt(), aby ograniczyć wyniki do określonego zakresu wartości.

Nawet wtedy, gdy dla zapytania występuje tylko jedno dopasowanie, zrzut nadal jest listą, zawiera tylko 1 element.

Ogranicz liczbę 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(), aby ustawić limit 100, początkowo otrzymasz maksymalnie 100 wywołań zwrotnych ChildAdded. Jeśli w bazie danych Firebase masz mniej niż 100 elementów, dla każdego z nich uruchamia się wywołanie zwrotne ChildAdded.

Wraz ze zmianą elementów otrzymujesz wywołania zwrotne ChildAdded dla tych, które wpiszą zapytanie, oraz ChildRemoved wywołań zwrotnych dla elementów, które z nich nie korzystają. Dzięki temu łączna liczba pozostaje na 100.

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

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders").OrderByChild("score").LimitToLast(1)
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

Filtruj według klucza lub wartości

Za pomocą parametrów StartAt(), EndAt() i EqualTo() możesz wybierać dla zapytań dowolny punkt początkowy, końcowy i równoważny. Przydaje się to przy dzieleniu danych na strony lub wyszukiwaniu elementów z elementami podrzędnymi, które mają określoną wartość.

Sposób porządkowania danych zapytań

W tej sekcji wyjaśniamy, jak dane są sortowane według metody w klasie Query.

OrderByChild

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

  1. Jako pierwsze wyświetlają się elementy podrzędne z wartością null określonego klucza podrzędnego.
  2. Następne są elementy podrzędne z wartością false określonego klucza podrzędnego. Jeśli kilka elementów podrzędnych ma wartość false, są one sortowane leksykograficznie według klucza.
  3. Następne są elementy podrzędne z wartością true określonego klucza podrzędnego. Jeśli kilka elementów podrzędnych ma wartość true, są one sortowane leksykograficznie 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ść liczbową 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. Jeśli wiele elementów podrzędnych ma tę samą wartość w określonym węźle podrzędnym, 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 do sortowania danych używasz funkcji OrderByKey(), są one zwracane w kolejności rosnącej według klucza.

  1. Elementy podrzędne z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, są na pierwszym miejscu, posortowane w kolejności rosnącej.
  2. Następnym elementem są elementy podrzędne z wartością w postaci ciągu znaków, posortowane leksykograficznie w kolejności rosnącej.

OrderByValue

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