Recupero dati

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 , è necessario:

• Registra il tuo progetto Unity e configuralo per utilizzare Firebase.

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

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

• Aggiungi Firebase Unity SDK (in particolare, 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 progetto Unity comporta attività sia nella console Firebase che nel progetto Unity aperto (ad esempio, scarichi i file di configurazione di Firebase dalla console, quindi li sposti nel progetto Unity).

Recupero dati

I dati di Firebase vengono recuperati da una singola chiamata a GetValueAsync() o dal collegamento 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 in modo che solo gli utenti autenticati possano leggere o scrivere dati. Per iniziare senza configurare l'autenticazione , puoi configurare le tue regole per l'accesso pubblico . Ciò rende il tuo database aperto a chiunque, anche alle persone che non utilizzano la tua app, quindi assicurati di limitare nuovamente il tuo database quando imposti l'autenticazione.

Ottieni un riferimento al database

Per leggere i dati dal database, è necessaria 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;
  }
}

Leggere i dati una volta

È possibile utilizzare il metodo GetValueAsync per leggere uno snapshot statico dei contenuti in un determinato percorso una volta. 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 => {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

Ascolta gli eventi

Puoi aggiungere ascoltatori di eventi per sottoscrivere le modifiche ai dati:

Evento	Uso tipico
ValueChanged	Leggere e ascoltare 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. Utilizzare con ChildAdded e ChildRemoved per monitorare le modifiche agli elenchi.
ChildRemoved	Ascolta gli elementi che vengono rimossi da un elenco. Utilizzare 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 order-by corrente).

Evento ValueChanged

È possibile utilizzare l'evento ValueChanged per iscriversi 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. 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 .

Importante: l'evento ValueChanged viene generato ogni volta che i dati vengono modificati nel riferimento al database specificato, incluse le modifiche agli elementi figlio. Per limitare la dimensione delle tue istantanee, allega solo al livello più alto necessario per guardare 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 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 dispone dell'autorizzazione per leggere da una posizione del database Firebase. DatabaseError indicherà perché si è verificato l'errore.

Successivamente puoi annullare l'iscrizione all'evento utilizzando qualsiasi DatabaseReference con lo stesso percorso. Le istanze DatabaseReference sono temporanee e possono essere pensate come un modo per accedere a qualsiasi percorso e query.

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

Eventi per bambini

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 insieme 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'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 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 viene modificato un nodo figlio. Ciò include qualsiasi modifica 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 in combinazione con i callback ChildAdded e ChildChanged . Lo snapshot passato al callback dell'evento contiene i dati per il figlio rimosso.

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

Ordinamento e filtraggio dei dati

È possibile 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.

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

Ordina i dati

Per recuperare i dati ordinati, iniziare specificando uno dei metodi order-by per determinare come vengono ordinati i risultati:

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

Puoi utilizzare un solo metodo order-by alla volta. La chiamata di un metodo order-by 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
    }

Questo 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 ciascuna voce. Puoi leggere ulteriori informazioni su come strutturare i tuoi dati in modo efficiente in Struttura il tuo 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 del valore "score" in ciascun figlio. Per ulteriori informazioni su come vengono ordinati altri tipi di dati, vedere Come vengono ordinati i dati delle query .

Filtraggio dei dati

Per filtrare i dati, puoi combinare qualsiasi metodo limit o range con un metodo order-by durante la creazione di una query.

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

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

Anche quando c'è solo una singola corrispondenza per la query, lo snapshot è ancora un elenco; contiene solo un singolo elemento.

Limita il numero di risultati

È possibile 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 hai meno di 100 elementi archiviati nel database Firebase, viene attivata una richiamata ChildAdded per ciascun 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 a 100.

Ad esempio, il codice seguente restituisce il punteggio più alto da 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

È possibile utilizzare StartAt() , EndAt() e EqualTo() per scegliere punti iniziali, finali e di equivalenza arbitrari per le query. Questo 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 in base a ciascuno dei metodi order-by nella classe Query .

OrderByChild

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

1. Gli elementi figlio con un valore null per la chiave figlio specificata vengono per primi.
2. I bambini con un valore false per la chiave figlio specificata vengono dopo. Se più figli hanno un valore false , vengono ordinati lessicograficamente per chiave.
3. I bambini con un valore true per la chiave figlio specificata vengono dopo. Se più figli hanno un valore true , vengono ordinati lessicograficamente per chiave.
4. Seguono i bambini con un valore numerico, 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 dopo i numeri e sono 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 per ultimi e sono ordinati lessicograficamente per chiave in ordine crescente.

OrderByKey

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

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

OrderByValue

Quando si utilizza 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 invece del valore di una chiave figlio specificata.