Pobieram dane

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

Zanim zaczniesz

Zanim zaczniesz korzystać z Realtime Database, musisz:

• Zarejestruj projekt Unity i skonfiguruj go tak, aby korzystał z Firebase.

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

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

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

Pamiętaj, że dodanie Firebase do projektu w Unity wymaga wykonania czynności zarówno w Firebasekonsoli, jak i w otwartym projekcie w Unity (np. pobierasz z konsoli pliki konfiguracyjne Firebase, a następnie przenosisz je do projektu w Unity).

Pobieranie danych

Dane Firebase są pobierane przez jednorazowe wywołanie funkcji GetValueAsync() lub przez dołączenie do zdarzenia w odniesieniu FirebaseDatabase. Funkcja nasłuchująca zdarzeń jest wywoływana raz w przypadku początkowego stanu danych i ponownie za każdym razem, gdy dane ulegną zmianie.

Pobieranie 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;
  }
}

Odczytywanie danych tylko raz

Możesz użyć metody GetValueAsync, aby jednorazowo odczytać statyczny zrzut zawartości w danej ścieżce. Wynik zadania będzie zawierać migawkę zawierającą wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwrócony snapshot to 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ć odbiorniki zdarzeń, aby subskrybować zmiany danych:

Zdarzenie ValueChanged

Możesz użyć zdarzenia ValueChanged, aby zasubskrybować zmiany treści w danej ścieżce. To zdarzenie jest wywoływane raz po dołączeniu odbiornika i ponownie za każdym razem, gdy zmienią się dane, w tym dane podrzędne. Funkcja zwrotna zdarzenia otrzymuje 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:

      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óre zawiera dane z określonej lokalizacji w bazie danych w momencie wystąpienia zdarzenia. Wywołanie Value na zrzucie zwraca Dictionary<string, object> reprezentujący dane. Jeśli w lokalizacji nie ma danych, wywołanie funkcji Value zwraca wartość null.

W tym przykładzie sprawdzana jest też wartość args.DatabaseError, aby zobaczyć, czy odczyt został anulowany. Odczyt może na przykład zostać anulowany, jeśli klient nie ma uprawnień do odczytu z lokalizacji bazy danych Firebase. DatabaseError wskaże przyczynę niepowodzenia.

Później możesz zrezygnować z subskrypcji wydarzenia, używając dowolnego DatabaseReference, który ma tę samą ścieżkę. DatabaseReference instancji są tymczasowe i można je traktować jako sposób uzyskiwania dostępu do dowolnej ścieżki i zapytania.

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

Zdarzenia podrzędne

Zdarzenia dotyczące dzieci są wywoływane w odpowiedzi na określone operacje wykonywane na dzieciach węzła, np. dodanie nowego dziecka za pomocą metody Push() lub zaktualizowanie dziecka za pomocą metody UpdateChildrenAsync(). Każda z tych funkcji może być przydatna do śledzenia zmian w określonym węźle w bazie danych. Na przykład gra może używać tych metod razem, aby monitorować aktywność 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 w bazie danych Firebase. Zdarzenie ChildAdded jest wywoływane 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. Słuchacz otrzymuje migawkę zawierającą dane nowego elementu podrzędnego.

Zdarzenie ChildChanged 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 on zwykle używany w połączeniu ze zdarzeniami ChildAdded i ChildRemoved w celu reagowania na zmiany na liście produktów. Zrzut przekazywany do odbiornika zdarzeń zawiera zaktualizowane dane dziecka.

Zdarzenie ChildRemoved jest wywoływane, gdy zostanie usunięte bezpośrednie dziecko. Zwykle jest używana w połączeniu z wywołaniami zwrotnymi ChildAdded i ChildChanged. Migawka przekazywana 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 podrzędnych. Jest on używany w przypadku danych uporządkowanych za pomocą funkcji 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 lub wartości.

Sortowanie danych

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

Możesz używać tylko jednej metody zamawiania naraz. Wywołanie metody order-by kilka razy w tym samym zapytaniu powoduje błąd.

Poniższy przykład pokazuje, jak zasubskrybować tablicę wyników uporządkowaną 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 to zapytanie, które w połączeniu z detektorem zdarzeń valuechanged synchronizuje klienta z tablicą wyników w bazie danych, uporządkowaną według wyniku każdego wpisu. Więcej informacji o skutecznym strukturyzowaniu danych znajdziesz w artykule Strukturyzowanie bazy danych.

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

Filtrowanie danych

Aby filtrować dane, możesz łączyć dowolne metody ograniczania lub zakresu z metodą sortowania podczas tworzenia zapytania.

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

Nawet jeśli zapytanie zwraca tylko 1 wynik, migawka jest listą, tylko że zawiera 1 element.

Ograniczanie liczby wyników

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

W miarę zmian w produktach otrzymujesz wywołania zwrotne ChildAdded dla produktów, które pojawiają się w zapytaniu, i wywołania zwrotne ChildRemoved dla produktów, które z niego znikają, dzięki czemu łączna liczba pozostaje na poziomie 100.

Na przykład poniższy kod zwraca najwyższy wynik z tablicy 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

Możesz używać symboli StartAt(), EndAt() i EqualTo(), aby wybierać dowolne punkty początkowe, końcowe i równoważne w zapytaniach. Może to być przydatne w przypadku stronicowania danych lub wyszukiwania elementów z elementami podrzędnymi, które mają określoną wartość.

Sposób uporządkowania danych zapytania

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

OrderByChild

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

1. Najpierw pojawiają się dzieci z wartością null dla określonego klucza dziecka.
2. Następnie wyświetlane są dzieci 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 wyświetlane są dzieci 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 pojawiają się 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ą w przypadku 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 kilka węzłów podrzędnych ma tę samą wartość, są one uporządkowane leksykograficznie według klucza.
6. Obiekty są umieszczane na końcu i sortowane leksykograficznie według klucza w kolejności rosnącej.

OrderByKey

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

1. Najpierw pojawiają się dzieci z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, posortowane w kolejności rosnącej.
2. Następnie pojawiają się dzieci z wartością tekstową jako kluczem, posortowane leksykograficznie w kolejności rosnącej.

OrderByValue

W przypadku korzystania z OrderByValue() dzieci są uporządkowane według 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.