Google si impegna a promuovere l'equità razziale per le comunità nere. Vedi come.
Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

Recupero dati

Questo documento illustra le basi del recupero dei dati e come ordinare e filtrare i dati di Firebase.

Prima di iniziare

Prima di poter utilizzare il database in tempo reale , è necessario:

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

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

    • Se non si dispone di un progetto Unity, è possibile scaricare un'app di esempio .

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

Si noti che l'aggiunta di Firebase al progetto Unity implica attività sia nella console Firebase che nel progetto Unity aperto (ad esempio, scaricare i file di configurazione di Firebase dalla console, quindi spostarli nel progetto Unity).

Recupero dati

I dati di Firebase vengono recuperati mediante una chiamata singola a GetValueAsync () o mediante il 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.

Ottieni un riferimento al database

Per leggere i dati dal database, è necessaria un'istanza di DatabaseReference :

using Firebase;
using Firebase.Database;
using Firebase.Unity.Editor;

public class MyScript: MonoBehaviour {
  void Start() {
    // Set up the Editor before calling into the realtime database.
    FirebaseApp.DefaultInstance.SetEditorDatabaseUrl("https://YOUR-FIREBASE-APP.firebaseio.com/");

    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

Leggi i dati una volta

È possibile utilizzare il metodo GetValueAsync per leggere un'istantanea statica dei contenuti in un determinato percorso una volta. Il risultato dell'attività conterrà un'istantanea contenente tutti i dati in quella posizione, inclusi i dati figlio. Se non ci sono dati, lo snapshot restituito è null .

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWith(task => {
        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 Leggi e ascolta le modifiche all'intero contenuto di un percorso.
ChildAdded Recupera gli elenchi di elementi o ascolta 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 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 articoli in un elenco ordinato. ChildMoved eventi ChildMoved seguono sempre l'evento ChildChanged che ha causato la modifica dell'ordine dell'articolo (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 l'ascoltatore è collegato e di nuovo ogni volta che i dati, inclusi i bambini, cambiano. Al callback dell'evento viene passata un'istantanea contenente tutti i dati in quella posizione, inclusi i dati figlio. Se non ci sono 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 di Value su un'istantanea restituisce un Dictionary<string, object> rappresenta i dati. Se nella posizione non sono presenti dati, la chiamata a Value restituisce null .

In questo esempio, args.DatabaseError viene anche esaminato per vedere se la lettura viene annullata. Ad esempio, una lettura può essere annullata se il client non dispone dell'autorizzazione per leggere da un percorso del database Firebase. DatabaseError indicherà il motivo per cui si è verificato l'errore.

Successivamente puoi annullare l'iscrizione all'evento utilizzando qualsiasi DatabaseReference con lo stesso percorso. DatabaseReference istanze di DatabaseReference sono effimere 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 ai figli di un nodo da un'operazione come un nuovo figlio aggiunto tramite il metodo Push() o un figlio in fase di aggiornamento 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 un nuovo figlio viene aggiunto al percorso specificato. All'ascoltatore viene trasmessa un'istantanea contenente i dati del nuovo figlio.

L'evento ChildChanged viene generato ogni volta che viene modificato un nodo figlio. Ciò include eventuali modifiche ai discendenti del nodo figlio. In genere viene 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 bambino.

L'evento ChildRemoved viene attivato quando viene rimosso un figlio immediato. In genere viene utilizzato insieme ai callback ChildAdded e ChildChanged . L'istantanea passata 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 provoca il riordino del figlio. Viene utilizzato con i dati ordinati con OrderByChild o OrderByValue .

Ordinamento e filtro dei dati

È possibile utilizzare la classe Query database in tempo reale per recuperare i dati ordinati per chiave, valore o 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.

Ordina i dati

Per recuperare i dati ordinati, iniziare specificando uno dei metodi di ordinamento per determinare come ordinare i risultati:

Metodo uso
OrderByChild() Ordina i risultati in base al valore di una chiave figlio specificata.
OrderByKey() Ordina i risultati con le chiavi figlio.
OrderByValue() Ordina i risultati in base a valori figlio.

È possibile utilizzare solo un metodo di ordinamento alla volta. Chiamare un metodo di ordine più volte nella stessa query genera un errore.

L'esempio seguente mostra come è possibile iscriversi 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
    }

Ciò definisce una query che, se combinata con un listener di eventi a valore aggiunto, sincronizza il client con la classifica nel database, ordinata in base al punteggio di ciascuna voce. Puoi leggere di più sulla strutturazione efficiente dei tuoi dati in Struttura del tuo database .

La chiamata al metodo OrderByChild() specifica la chiave figlio per cui ordinare i risultati. In questo caso, i risultati vengono ordinati in base al valore del "score" in ciascun figlio. Per ulteriori informazioni sull'ordinamento di altri tipi di dati, vedere Come ordinare i dati della query .

Filtraggio dei dati

Per filtrare i dati, è possibile combinare uno qualsiasi dei metodi limite o intervallo con un metodo di ordine quando si costruisce una query.

Metodo uso
LimitToFirst() Imposta il numero massimo di articoli da restituire dall'inizio dell'elenco ordinato dei risultati.
LimitToLast() Imposta il numero massimo di articoli da restituire dalla fine dell'elenco ordinato dei risultati.
StartAt() Restituisci articoli maggiori o uguali alla chiave o al valore specificati a seconda del metodo di ordinamento scelto.
EndAt() Restituisci gli articoli inferiori o uguali alla chiave o al valore specificati a seconda del metodo di ordinamento scelto.
EqualTo() Restituisci articoli uguali alla chiave o al valore specificati in base al metodo di ordinamento scelto.

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

Anche quando esiste una sola corrispondenza per la query, lo snapshot è ancora un elenco; contiene solo un singolo oggetto.

Limitare il numero di risultati

È possibile utilizzare i LimitToFirst() e LimitToLast() per impostare un numero massimo di figli da sincronizzare per un determinato callback. Ad esempio, se si utilizza LimitToFirst() per impostare un limite di 100, inizialmente si ricevono solo fino a 100 callback ChildAdded . Se nel database Firebase sono memorizzati meno di 100 articoli, viene ChildAdded un callback ChildAdded per ciascun elemento.

Man mano che gli articoli cambiano, si ricevono i callback ChildAdded per gli elementi che entrano nella query e i 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 di inizio, fine ed equivalenza arbitrari per le query. Ciò può essere utile per impaginare i dati o trovare elementi con elementi secondari con un valore specifico.

Come vengono ordinati i dati della query

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

OrderByChild

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

  1. I bambini 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ù bambini 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ù bambini hanno un valore true , vengono ordinati lessicograficamente per chiave.
  4. I bambini con un valore numerico vengono dopo, ordinati in ordine crescente. Se più figlie hanno lo stesso valore numerico per il nodo figlio specificato, vengono ordinate per chiave.
  5. Le stringhe seguono 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 arrivano 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 dalla chiave.

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

OrderByValue

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