Pobieram dane

W tym dokumencie znajdziesz podstawowe informacje o pobieraniu danych oraz ich sortowaniu i filtrowaniu.

Zanim zaczniesz

Zanim zaczniesz korzystać z Realtime Database, musisz:

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

  • Jeśli Twój projekt w Unity korzysta już z Firebase, jest już zarejestrowany i skonfigurowany pod kątem tej usługi.

  • Jeśli nie masz projektu Unity, możesz pobrać próbną aplikację.

• Dodaj pakiet SDK Firebase Unity (szczególnie plik 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. pobieranie plików konfiguracji Firebase z konsoli i przenoszenie ich 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. Listener jest wywoływany raz w przypadku początkowego stanu danych i ponownie za każdym razem, gdy dane ulegną zmianie.

Pobieranie obiektu DatabaseReference

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

Aby odczytać statyczny zrzut treści w danym miejscu, możesz użyć metody GetValueAsync. Wynik zadania będzie zawierał zrzut zawierający wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma żadnych danych, zwrócony zostanie podany fragment kodu null.

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWithOnMainThread(task =&gt {
        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 ValueChanged

Zdarzenia ValueChanged możesz używać do subskrybowania zmian 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. Funkcja wywołania z zdarzenia otrzymuje zrzut zawierający wszystkie dane w danej lokalizacji, w tym dane podrzędne. Jeśli nie ma żadnych danych, zwracany jest obraz null.

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

      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 DataSnapshot, który zawiera dane w określonej lokalizacji w bazie danych w momencie zdarzenia. Wywołanie Value w zrzucie zwraca Dictionary<string, object> reprezentujący dane. Jeśli w danej lokalizacji nie ma żadnych danych, wywołanie funkcji Value zwraca wartość null.

W tym przykładzie sprawdzana jest również wartość args.DatabaseError, 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. DatabaseError wskazuje, dlaczego wystąpił błąd.

Później możesz anulować subskrypcję wydarzenia za pomocą dowolnego elementu DatabaseReference, który ma tę samą ścieżkę. 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 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 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 dotychczasowego elementu podrzędnego, a następnie 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.

Zdarzenie ChildChanged jest wywoływane za każdym razem, gdy modyfikowany jest węzeł podrzędny. Obejmuje to wszelkie modyfikacje potomków węzła podrzędnego. Jest ono zazwyczaj używane w połączeniu ze zdarzeniami ChildAdded i ChildRemoved, aby reagować na zmiany w liście elementów. Zrzut przekazany do odbiornika zdarzeń zawiera zaktualizowane dane dotyczące podrzędnego obiektu.

Zdarzenie ChildRemoved jest wywoływane, gdy usuwasz bezpośrednie dziecko. Jest ona zwykle używana w połączeniu z funkcjami zwrotnymi 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 zdarzenie ChildChanged jest wywoływane przez aktualizację, która powoduje zmianę kolejności elementów w podrzędnym. Jest on używany w przypadku danych uporządkowanych za pomocą funkcji OrderByChild lub OrderByValue.

Sortowanie i filtrowanie danych

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

Sortowanie danych

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

Możesz użyć tylko jednej metody sortowania naraz. Wywołanie metody sortowania kilka razy w tym samym zapytaniu powoduje błąd.

Ten przykład pokazuje, jak można subskrybować tablicę wyników z podziałem na punkty.

      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
    }

Określa ono zapytanie, które w połączeniu z obsługą zdarzenia valuechanged synchronizuje klienta z listą liderów w bazie danych, posortowaną według wyniku każdego wpisu. 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 atrybutu "score" w każdym podrzędnym. Więcej informacji o porządkowaniu innych typów danych znajdziesz w artykule Porządkowanie danych zapytań.

Filtrowanie danych

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

W przeciwieństwie do metod porządkowania według kolumny możesz łączyć wiele funkcji limit i zakres. Możesz np. 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.

Ogranicz liczbę wyników

Aby ustawić maksymalną liczbę elementów podrzędnych, które mają być synchronizowane w przypadku danego wywołania zwrotnego, możesz użyć metod LimitToFirst() i LimitToLast(). Jeśli na przykład użyjesz parametru LimitToFirst(), aby ustawić limit na 100, początkowo otrzymasz tylko do 100 wywołań funkcji ChildAdded. Jeśli w bazie danych Firebase masz mniej niż 100 elementów, dla każdego z nich zostanie wywołana funkcja ChildAdded.

Gdy elementy się zmieniają, 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 najlepszy 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
    }

Filtrowanie 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 sortowania danych zapytania

W tej sekcji wyjaśniamy, jak dane są sortowane według każdej z metod sortowania 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. Najpierw są wyświetlane elementy podrzędne, dla których wartość atrybutu podrzędnego null jest równa null.
2. Następnie podawane są elementy podrzędne, dla których wartość określonego klucza podrzędnego to false. Jeśli wiele elementów podrzędnych ma wartość false, są one sortowane alfabetycznie według klucza.
3. Następne są elementy podrzędne z wartością true określonego klucza podrzędnego. Jeśli wiele 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 tekstowe występują po liczbach i są sortowane alfabetycznie 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 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ępnym elementem są elementy podrzędne z wartością w postaci ciągu znaków, posortowane leksykograficznie w kolejności rosnącej.

OrderByValue

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