Recupero dei dati in corso...

Questo documento illustra le nozioni di base sul recupero dei dati e su come ordinare e filtrare i dati di Firebase.

Prima di iniziare

Prima di poter utilizzare Realtime Database, devi:

  • Registrare il tuo progetto Unity e configurarlo 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.

  • Aggiungere Firebase Unity SDK (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, quindi sposti i file nel progetto Unity).

Recupero dei dati

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.

Recupero di un DatabaseReference

Per leggere i dati dal database, devi avere 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 GetValueAsync metodo per leggere una sola volta uno snapshot statico dei contenuti in un determinato percorso. Il risultato dell'attività conterrà uno snapshot contenente tutti i dati in quella posizione, inclusi i dati figlio. 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...
        }
      });

Ascolto degli eventi

Puoi aggiungere listener di eventi per ricevere notifiche sulle modifiche ai dati:

Evento Utilizzo tipico
ValueChanged Leggi e ascolta le modifiche all'intero contenuto di un percorso.
ChildAdded Recupera elenchi di elementi o ascolta le aggiunte a un elenco di elementi. Utilizzo consigliato con ChildChanged e ChildRemoved per monitorare le modifiche agli elenchi.
ChildChanged Ascolta le modifiche agli elementi in un elenco. Utilizza con ChildAdded e ChildRemoved per monitorare le modifiche agli elenchi.
ChildRemoved Ascolta gli elementi rimossi da un elenco. Utilizza con ChildAdded e ChildChanged per monitorare le modifiche agli elenchi.
ChildMoved Ascolta le modifiche all'ordine degli elementi in un elenco ordinato. ChildMoved eventi seguono sempre l'evento ChildChanged che ha causato la modifica dell'ordine dell'elemento (in base al metodo di ordinamento corrente).

Evento ValueChanged

Puoi utilizzare l'ValueChanged evento per ricevere notifiche sulle modifiche ai 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. Al callback dell'evento viene passato uno snapshot contenente tutti i dati in quella posizione, inclusi i dati figlio. Se non sono presenti dati, lo snapshot restituito è null.

L'esempio seguente 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 nel database al momento dell'evento. La chiamata a Value su uno snapshot restituisce un Dictionary<string, object> che rappresenta i dati. Se non sono presenti dati nella posizione, la chiamata a Value restituisce null.

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

Puoi annullare la sottoscrizione all'evento in un secondo momento utilizzando qualsiasi DatabaseReference con lo stesso percorso. Le istanze di DatabaseReference sono effimere e possono essere considerate un modo per accedere a qualsiasi percorso ed eseguire query.

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

Eventi figlio

Gli eventi figlio vengono attivati in risposta a operazioni specifiche eseguite sui figli di un nodo da un'operazione come l'aggiunta di un nuovo figlio tramite il Push() metodo o l'aggiornamento di un figlio tramite il UpdateChildrenAsync() metodo. Ognuno di questi può essere utile per ascoltare le modifiche a un nodo specifico in 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'ChildAdded evento viene in genere utilizzato per recuperare un elenco di elementi in un database Firebase. L'evento ChildAdded viene generato una volta per ogni figlio esistente e poi di nuovo ogni volta che viene aggiunto un nuovo figlio al percorso specificato. Al listener viene passato uno snapshot contenente i dati del nuovo figlio.

L'evento ChildChanged viene generato ogni volta che un nodo figlio viene modificato. Sono incluse tutte le modifiche ai discendenti del nodo figlio. Viene in genere utilizzato insieme agli eventi ChildAdded e ChildRemoved per rispondere alle modifiche a un elenco di elementi. Lo snapshot passato al listener di eventi contiene i dati aggiornati per il figlio.

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 figlio rimosso.

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

Ordinamento e filtro dei dati

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

Ordinamento dei dati

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

Metodo Utilizzo
OrderByChild() Ordina i risultati in base al valore di una chiave figlio specificata.
OrderByKey() Ordina i risultati in base alle chiavi figlio.
OrderByValue() Ordina i risultati in base ai valori figlio.

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

L'esempio seguente mostra come puoi sottoscrivere una classifica dei punteggi ordinata per 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
    }

Questa query, se combinata con un listener di eventi valuechanged sincronizza il client con la classifica nel database, ordinata in base al punteggio di ogni voce. Puoi scoprire di più sulla strutturazione efficiente dei dati in Strutturare il database.

La chiamata al metodo OrderByChild() specifica la chiave figlio in base alla quale ordinare i risultati. In questo caso, i risultati vengono ordinati in base al valore di "score" valore in ogni figlio. Per ulteriori informazioni su come vengono ordinati gli altri tipi di dati, consulta Come vengono ordinati i dati delle query.

Filtraggio dei dati

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

Metodo Utilizzo
LimitToFirst() Imposta il numero massimo di elementi da restituire dall'inizio dell' elenco ordinato dei risultati.
LimitToLast() Imposta il numero massimo di elementi da restituire dalla fine dell'elenco ordinato dei risultati.
StartAt() Restituisce gli elementi maggiori o uguali alla chiave o al valore specificato a seconda del metodo di ordinamento scelto.
EndAt() Restituisce gli elementi minori o uguali alla chiave o al valore specificato a seconda del metodo di ordinamento scelto.
EqualTo() Restituisce gli elementi uguali alla chiave o al valore specificato a seconda del metodo di ordinamento scelto.

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 se esiste una sola corrispondenza per la query, lo snapshot è comunque un elenco; contiene solo un elemento.

Limitazione del 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 ricevi solo fino a 100 callback ChildAdded. Se nel database Firebase sono memorizzati meno di 100 elementi, viene attivato un callback ChildAdded per ogni elemento.

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

Ad esempio, il codice seguente 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
    }

Filtraggio per chiave o valore

Puoi utilizzare StartAt(), EndAt() e EqualTo() per scegliere punti di partenza, di fine e di equivalenza arbitrari per le query. Questa opzione può essere utile per impaginare i dati o trovare elementi con figli che hanno un valore specifico.

Come vengono ordinati i dati delle query

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

OrderByChild

Quando utilizzi OrderByChild() , i dati che contengono la chiave figlio specificata vengono ordinati come segue:

  1. I figli con un valore null per la chiave figlio specificata vengono visualizzati per primi.
  2. I figli con un valore false per la chiave figlio specificata vengono visualizzati successivamente. Se più figli hanno un valore false, vengono ordinati lessicograficamente per chiave.
  3. I figli con un valore true per la chiave figlio specificata vengono visualizzati successivamente. Se più figli hanno un valore true, vengono ordinati lessicograficamente per chiave.
  4. I figli con un valore numerico vengono visualizzati successivamente, ordinati in ordine crescente. Se più figli hanno lo stesso valore numerico per il nodo figlio specificato, vengono ordinati per chiave.
  5. Le stringhe vengono visualizzate dopo i numeri e vengono ordinate lessicograficamente in ordine crescente. Se più figli hanno lo stesso valore per il nodo figlio specificato, vengono ordinati lessicograficamente per chiave.
  6. Gli oggetti vengono visualizzati per ultimi e vengono 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 figli con una chiave che può essere analizzata come un intero a 32 bit vengono visualizzati per primi, ordinati in ordine crescente.
  2. I figli con un valore stringa come chiave vengono visualizzati successivamente, ordinati lessicograficamente in ordine crescente.

OrderByValue

Quando utilizzi OrderByValue() , i figli vengono ordinati in base al loro valore. I criteri di ordinamento sono gli stessi di OrderByChild(), tranne per il fatto che viene utilizzato il valore del nodo anziché il valore di una chiave figlio specificata.