Recupero dei dati in corso...

Questo documento tratta le nozioni di base sul recupero dei dati e su come ordinarli e filtrarli.

Prima di iniziare

Prima di poter utilizzare Realtime Database, devi:

• Registra il tuo progetto Unity e configuralo in modo che utilizzi Firebase.

  • Se il tuo progetto Unity utilizza già Firebase, è già registrato e configurato per Firebase.

  • Se non hai un progetto Unity, puoi scaricare un'app di esempio.

• Aggiungi l'SDK Firebase Unity (in particolare, FirebaseDatabase.unitypackage) al tuo progetto Unity.

Tieni presente che l'aggiunta di Firebase al tuo progetto Unity comporta attività sia nella Firebase console sia nel progetto Unity aperto (ad esempio, scarichi i file di configurazione Firebase dalla console, poi li sposti nel progetto Unity).

Recupero dei dati in corso…

I dati di Firebase vengono recuperati tramite una chiamata una tantum a GetValueAsync() o collegandosi a un evento su un riferimento FirebaseDatabase. Il listener di eventi viene chiamato una volta per lo stato iniziale dei dati e di nuovo ogni volta che i dati cambiano.

Recuperare un DatabaseReference

Per leggere i dati dal database, devi disporre di un'istanza di 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;
  }
}

Lettura dei dati una sola volta

Puoi utilizzare il metodo GetValueAsync per leggere una volta uno snapshot statico dei contenuti in un determinato percorso. Il risultato dell'attività conterrà uno snapshot con tutti i dati in quella posizione, inclusi i dati secondari. Se non sono presenti dati, lo snapshot restituito è 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...
        }
      });

Ascolta gli eventi

Puoi aggiungere listener di eventi per abbonarti alle modifiche ai dati:

Evento ValueChanged

Puoi utilizzare l'evento ValueChanged per abbonarti alle modifiche dei contenuti in un determinato percorso. Questo evento viene attivato una volta quando il listener è collegato e di nuovo ogni volta che i dati, inclusi i figli, cambiano. Il callback dell'evento riceve uno snapshot contenente tutti i dati in quella posizione, inclusi i dati secondari. Se non sono presenti dati, lo snapshot restituito è null.

Il seguente esempio mostra un gioco che recupera i punteggi di una classifica dal database:

      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 contiene un DataSnapshot che contiene i dati nella posizione specificata del database al momento dell'evento. La chiamata di Value su uno snapshot restituisce un Dictionary<string, object> che rappresenta i dati. Se non esistono dati nella posizione, la chiamata a Value restituisce null.

In questo esempio, viene esaminato anche args.DatabaseError per verificare se la lettura è annullata. Ad esempio, una lettura può essere annullata se il client non dispone dell'autorizzazione per leggere da una posizione del database Firebase. Il DatabaseError indicherà il motivo dell'errore.

Puoi annullare l'iscrizione all'evento in un secondo momento utilizzando qualsiasi DatabaseReference che abbia lo stesso percorso. DatabaseReference sono effimere e possono essere considerate un modo per accedere a qualsiasi percorso e query.

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

Eventi figlio

Gli eventi secondari vengono attivati in risposta a operazioni specifiche che interessano i nodi secondari di un'operazione, ad esempio un nuovo nodo secondario aggiunto tramite il metodo Push() o un nodo secondario aggiornato tramite il metodo UpdateChildrenAsync(). Ciascuno di questi elementi può essere utile per ascoltare le modifiche a un nodo specifico di un database. Ad esempio, un gioco potrebbe utilizzare questi metodi insieme per monitorare l'attività nei commenti di una sessione di gioco, come mostrato di seguito:

      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
    }

L'evento ChildAdded viene in genere utilizzato per recuperare un elenco di elementi in un database Firebase. L'evento ChildAdded viene generato una volta per ogni elemento secondario esistente e poi di nuovo ogni volta che viene aggiunto un nuovo elemento secondario al percorso specificato. Al listener viene passato uno snapshot contenente i dati del nuovo figlio.

L'evento ChildChanged viene generato ogni volta che viene modificato un nodo secondario. Sono incluse eventuali modifiche ai nodi secondari del nodo principale. Viene in genere utilizzato in combinazione con gli eventi ChildAdded e ChildRemoved per rispondere alle modifiche a un elenco di elementi. Lo snapshot passato al listener di eventi contiene i dati aggiornati del bambino.

L'evento ChildRemoved viene attivato quando viene rimosso un figlio immediato. Viene in genere utilizzato insieme ai callback ChildAdded e ChildChanged. Lo snapshot passato al callback dell'evento contiene i dati del bambino rimosso.

L'evento ChildMoved viene attivato ogni volta che l'evento ChildChanged viene generato da un aggiornamento che causa il riordino del figlio. Viene utilizzato con dati ordinati con OrderByChild o OrderByValue.

Ordinare e filtrare i dati

Puoi utilizzare la classe Realtime Database Query per recuperare i dati ordinati per chiave, per valore o per valore di un elemento secondario. Puoi anche filtrare il risultato ordinato in base a un numero specifico di risultati o a un intervallo di chiavi o valori.

Ordinare i dati

Per recuperare i dati ordinati, inizia specificando uno dei metodi di ordinamento per determinare l'ordine dei risultati:

Puoi utilizzare un solo metodo di ordinamento alla volta. La chiamata di un metodo order-by più volte nella stessa query genera un errore.

Il seguente esempio mostra come potresti abbonarti a una classifica dei punteggi ordinata in base al punteggio.

      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
    }

Definisce una query che, se combinata con un listener di eventi valuechanged, sincronizza il client con la classifica nel database, ordinata in base al punteggio di ogni voce. Per saperne di più su come strutturare i dati in modo efficiente, consulta la sezione Strutturare il database.

La chiamata al metodo OrderByChild() specifica la chiave secondaria in base alla quale ordinare i risultati. In questo caso, i risultati vengono ordinati in base al valore di "score" in ogni elemento secondario. Per saperne di più sull'ordine degli altri tipi di dati, vedi Come vengono ordinati i dati delle query.

Filtrare i dati

Per filtrare i dati, puoi combinare uno qualsiasi dei metodi di limite o intervallo con un metodo di ordinamento durante la creazione di una query.

A differenza dei metodi di ordinamento, puoi combinare più funzioni di limite o intervallo. Ad esempio, puoi combinare i metodi StartAt() e EndAt() per limitare i risultati a un intervallo di valori specificato.

Anche quando esiste una sola corrispondenza per la query, lo snapshot è comunque un elenco, ma contiene un solo elemento.

Limitare il numero di risultati

Puoi utilizzare i metodi LimitToFirst() e LimitToLast() per impostare un numero massimo di figli da sincronizzare per un determinato callback. Ad esempio, se utilizzi LimitToFirst() per impostare un limite di 100, inizialmente riceverai solo fino a 100 callback ChildAdded. Se hai meno di 100 elementi memorizzati nel database Firebase, viene attivata una richiamata ChildAdded per ogni elemento.

Man mano che gli elementi cambiano, ricevi ChildAdded callback per gli elementi che entrano nella query e ChildRemoved callback per gli elementi che escono dalla query, in modo che il numero totale rimanga a 100.

Ad esempio, il codice riportato di seguito restituisce il punteggio più alto di una classifica:

      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
    }

Filtrare per chiave o valore

Puoi utilizzare StartAt(), EndAt() e EqualTo() per scegliere punti di partenza, di arrivo e di equivalenza arbitrari per le query. Questo può essere utile per impaginare i dati o trovare elementi secondari con un valore specifico.

Come vengono ordinati i dati delle query

Questa sezione spiega come vengono ordinati i dati in base a ciascuno dei metodi di ordinamento nella classe Query.

OrderByChild

Quando utilizzi OrderByChild(), i dati che contengono la chiave secondaria specificata vengono ordinati nel seguente modo:

1. I bambini con un valore null per la chiave figlio specificata vengono visualizzati per primi.
2. I figli con un valore di false per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore di false, vengono ordinati lessicograficamente per chiave.
3. I figli con un valore di true per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore di true, vengono ordinati in ordine lessicografico in base alla chiave.
4. Seguono i bambini con un valore numerico, ordinati in ordine crescente. Se più elementi secondari hanno lo stesso valore numerico per il nodo secondario specificato, vengono ordinati per chiave.
5. Le stringhe vengono dopo i numeri e sono ordinate lessicograficamente in ordine crescente. Se più figli hanno lo stesso valore per il nodo figlio specificato, vengono ordinati in ordine lessicografico per chiave.
6. Gli oggetti vengono visualizzati per ultimi e sono ordinati lessicograficamente per chiave in ordine crescente.

OrderByKey

Quando utilizzi OrderByKey() per ordinare i dati, questi vengono restituiti in ordine crescente per chiave.

1. I bambini con una chiave che può essere analizzata come un numero intero a 32 bit vengono visualizzati per primi, in ordine crescente.
2. Seguono i figli con un valore stringa come chiave, ordinati in ordine lessicografico crescente.

OrderByValue

Quando si utilizza OrderByValue(), i bambini vengono ordinati in base al loro valore. I criteri di ordinamento sono gli stessi di OrderByChild(), tranne che viene utilizzato il valore del nodo anziché il valore di una chiave secondaria specificata.