Recupero dei dati in corso...

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

Prima di iniziare

Per poter usare Realtime Database, devi:

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

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

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

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

Trova istruzioni dettagliate per queste attività di configurazione iniziale in Aggiungi Firebase al tuo progetto Unity.

Tieni presente che l'aggiunta di Firebase al tuo progetto Unity prevede attività sia nella console Firebase sia nel progetto Unity aperto (ad esempio, scarichi i file di configurazione di Firebase dalla console e 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.

Nota: per impostazione predefinita, l'accesso in lettura e scrittura al database è limitato, pertanto solo gli utenti autenticati possono leggere o scrivere dati. Per iniziare senza configurare Authentication, puoi configurare le regole per l'accesso pubblico. In questo modo, il tuo database sarà aperto a chiunque, anche a chi non utilizza la tua app, quindi assicurati di limitare nuovamente il database quando configuri l'autenticazione.

Ottieni 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 metodo GetValueAsync per leggere una 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 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 iscriverti alle modifiche ai dati:

Evento	Utilizzo tipico
ValueChanged	Leggere e rilevare le modifiche all'intero contenuto di un percorso.
ChildAdded	Recuperare elenchi di elementi o ascoltare le aggiunte a un elenco di elementi. Utilizzo suggerito con ChildChanged e ChildRemoved per monitorare le modifiche agli elenchi.
ChildChanged	Ascolta le modifiche agli elementi di un elenco. Utilizzalo con ChildAdded e ChildRemoved per monitorare le modifiche agli elenchi.
ChildRemoved	Ascolta quando gli elementi vengono rimossi da un elenco. Utilizzalo con ChildAdded e ChildChanged per monitorare le modifiche agli elenchi.
ChildMoved	Ascolta le modifiche all'ordine degli elementi in un elenco ordinato. Gli eventi ChildMoved 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'evento ValueChanged per iscriverti alle modifiche dei contenuti in un determinato percorso. Questo evento viene attivato una volta quando il listener viene collegato e di nuovo ogni volta che i dati, inclusi i nodi secondari, cambiano. Al callback dell'evento viene passato uno snapshot contenente tutti i dati in quella posizione, inclusi i dati secondari. Se non sono presenti dati, lo snapshot restituito è null.

Importante: l'evento ValueChanged viene attivato ogni volta che i dati vengono modificati nel riferimento al database specificato, incluse le modifiche ai nodi secondari. Per limitare le dimensioni degli snapshot, collegali solo al livello più alto necessario per monitorare le modifiche. Ad esempio, non è consigliabile collegare un listener di eventi alla radice del database.

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 di Value su uno snapshot restituisce un Dictionary<string, object> che rappresenta i dati. Se non esistono dati nella località, 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 dispone dell'autorizzazione per leggere da una posizione del database Firebase. Il campo DatabaseError indicherà il motivo dell'errore.

In un secondo momento, puoi annullare l'iscrizione all'evento utilizzando qualsiasi DatabaseReference con lo stesso percorso. Le istanze DatabaseReference sono temporanee 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 figlio vengono attivati in risposta a operazioni specifiche che si verificano sugli elementi figlio di un nodo da un'operazione, ad esempio un nuovo elemento figlio aggiunto tramite il metodo Push() o un elemento figlio aggiornato tramite il metodo UpdateChildrenAsync(). Ognuno 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 attivato 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 elemento secondario.

L'evento ChildChanged viene attivato ogni volta che un nodo secondario viene modificato. Sono incluse eventuali modifiche ai discendenti del nodo secondario. In genere viene utilizzato insieme agli eventi ChildAdded e ChildRemoved per rispondere alle modifiche apportate a un elenco di elementi. Lo snapshot passato al listener di eventi contiene i dati aggiornati per l'elemento secondario.

L'evento ChildRemoved viene attivato quando viene rimosso un elemento secondario immediato. In genere viene utilizzato insieme ai callback ChildAdded e ChildChanged. Lo snapshot passato al callback dell'evento contiene i dati dell'elemento secondario rimosso.

L'evento ChildMoved viene attivato ogni volta che l'evento ChildChanged viene generato da un aggiornamento che causa il riordinamento dell'elemento secondario. Viene utilizzata 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 elemento secondario. Puoi anche filtrare il risultato ordinato in base a un numero specifico di risultati o a un intervallo di chiavi o valori.

Nota: l'applicazione di filtri e l'ordinamento possono essere costosi, soprattutto se eseguiti sul client. Se la tua app utilizza query, definisci la regola .indexOn per indicizzare queste chiavi sul server e migliorare le prestazioni delle query, come descritto in Indicizzazione dei dati.

Ordina i 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 secondaria specificata.
OrderByKey()	Ordina i risultati in base alle chiavi secondarie.
OrderByValue()	Ordina i risultati in base ai valori secondari.

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

L'esempio seguente mostra come puoi iscriverti a 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
    }

In questo modo viene definita 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. Puoi scoprire di più su come strutturare i dati in modo efficiente in Struttura il tuo 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ù su come vengono ordinati gli altri tipi di dati, consulta 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.

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 specificati, a seconda del metodo di ordinamento scelto.
EndAt()	Restituisce gli elementi minori o uguali alla chiave o al valore specificati, a seconda del metodo di ordinamento scelto.
EqualTo()	Restituisce gli elementi uguali alla chiave o al valore specificati, 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, ma contiene un solo elemento.

Limita il numero di risultati

Puoi utilizzare i metodi LimitToFirst() e LimitToLast() per impostare un numero massimo di elementi secondari 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 nel tuo database Firebase sono archiviati 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
    }

Filtra 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 con elementi secondari che hanno un valore specifico.

Come vengono ordinati i dati delle query

Questa sezione spiega come i dati vengono ordinati 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 come segue:

1. I nodi secondari con un valore null per la chiave secondaria specificata vengono visualizzati per primi.
2. Seguono i nodi secondari con un valore di false per la chiave secondaria specificata. Se più elementi secondari hanno un valore false, vengono ordinati lessicograficamente in base alla chiave.
3. Seguono i nodi secondari con un valore di true per la chiave secondaria specificata. Se più elementi secondari hanno un valore true, vengono ordinati in ordine lessicografico per chiave.
4. Seguono gli elementi secondari 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ù elementi secondari hanno lo stesso valore per il nodo secondario 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 in base alla chiave.

1. I nodi secondari con una chiave che può essere analizzata come un numero intero a 32 bit vengono visualizzati per primi, ordinati in ordine crescente.
2. Seguono gli elementi secondari con un valore di stringa come chiave, ordinati lessicograficamente in ordine crescente.

OrderByValue

Quando utilizzi OrderByValue(), gli elementi secondari vengono ordinati in base al loro valore. I criteri di ordinamento sono gli stessi di OrderByChild(), ad eccezione del fatto che viene utilizzato il valore del nodo anziché il valore di una chiave secondaria specificata.