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

Salvare i dati

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).

Salvataggio dei dati

Esistono cinque metodi per scrivere i dati nel database in tempo reale di Firebase:

Metodo Usi comuni
SetValueAsync() Scrivi o sostituisci i dati in un percorso definito, ad esempio users/<user-id>/<username> .
SetRawJsonValueAsync() Scrivi o sostituisci i dati con Json non elaborato, ad esempio users/<user-id>/<username> .
Push() Aggiungi a un elenco di dati. Ogni volta che chiami Push() , Firebase genera una chiave univoca che può anche essere utilizzata come identificatore univoco, come user-scores/<user-id>/<unique-score-id> .
UpdateChildrenAsync() Aggiorna alcune delle chiavi per un percorso definito senza sostituire tutti i dati.
RunTransaction() Aggiorna dati complessi che potrebbero essere danneggiati da aggiornamenti simultanei.

Ottieni un riferimento al database

Per scrivere i dati nel 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;
  }
}

Scrivi, aggiorna o elimina i dati a un riferimento

Operazioni di scrittura di base

Per le operazioni di scrittura di base, è possibile utilizzare SetValueAsync() per salvare i dati in un riferimento specificato, sostituendo tutti i dati esistenti in quel percorso. È possibile utilizzare questo metodo per passare tipi che corrispondono ai tipi JSON disponibili come segue:

  • string
  • long
  • double
  • bool
  • Dictionary<string, Object>
  • List<Object>

Se si utilizza un oggetto C # digitato, è possibile utilizzare JsonUtility.ToJson() per convertire l'oggetto in Json non elaborato e chiamare SetRawJsonValueAsync() . Ad esempio, potresti avere una classe Utente che ha il seguente aspetto:

public class User {
    public string username;
    public string email;

    public User() {
    }

    public User(string username, string email) {
        this.username = username;
        this.email = email;
    }
}

È possibile aggiungere un utente con SetRawJsonValueAsync() come segue:

private void writeNewUser(string userId, string name, string email) {
    User user = new User(name, email);
    string json = JsonUtility.ToJson(user);

    mDatabaseRef.Child("users").Child(userId).SetRawJsonValueAsync(json);
}

L'uso di SetValueAsync() o SetRawJsonValueAsync() in questo modo sovrascrive i dati nella posizione specificata, inclusi eventuali nodi figlio. Tuttavia, è ancora possibile aggiornare un figlio senza riscrivere l'intero oggetto. Se si desidera consentire agli utenti di aggiornare i propri profili, è possibile aggiornare il nome utente come segue:

 mDatabaseRef.Child("users").Child(userId).Child("username").SetValueAsync(name);
 

Aggiungi a un elenco di dati

Utilizzare il metodo Push() per aggiungere dati a un elenco in applicazioni multiutente. Il metodo Push() genera una chiave univoca ogni volta che un nuovo figlio viene aggiunto al riferimento Firebase specificato. Utilizzando queste chiavi generate automaticamente per ogni nuovo elemento nell'elenco, diversi client possono aggiungere bambini nella stessa posizione contemporaneamente senza conflitti di scrittura. La chiave univoca generata da Push() si basa su un timestamp, quindi gli elementi dell'elenco vengono ordinati automaticamente in ordine cronologico.

È possibile utilizzare il riferimento ai nuovi dati restituiti dal metodo Push() per ottenere il valore della chiave generata automaticamente del figlio o impostare i dati per il figlio. La chiamata a Key su un riferimento Push() restituisce il valore della chiave generata automaticamente.

Aggiorna campi specifici

Per scrivere simultaneamente su figli specifici di un nodo senza sovrascrivere altri nodi figlio, utilizzare il metodo UpdateChildrenAsync() .

Quando si chiama UpdateChildrenAsync() , è possibile aggiornare i valori figlio di livello inferiore specificando un percorso per la chiave. Se i dati vengono archiviati in più posizioni per adattarsi meglio, è possibile aggiornare tutte le istanze di tali dati utilizzando il fan-out dei dati . Ad esempio, un gioco potrebbe avere una classe LeaderboardEntry come questa:

public class LeaderboardEntry {
    public string uid;
    public int score = 0;

    public LeaderboardEntry() {
    }

    public LeaderboardEntry(string uid, int score) {
        this.uid = uid;
        this.score = score;
    }

    public Dictionary<string, Object> ToDictionary() {
        Dictionary<string, Object> result = new Dictionary<string, Object>();
        result["uid"] = uid;
        result["score"] = score;

        return result;
    }
}

Per creare un LeaderboardEntry e aggiornarlo contemporaneamente al feed dei punteggi recenti e all'elenco dei punteggi dell'utente, il gioco utilizza un codice simile al seguente:

private void WriteNewScore(string userId, int score) {
    // Create new entry at /user-scores/$userid/$scoreid and at
    // /leaderboard/$scoreid simultaneously
    string key = mDatabase.Child("scores").Push().Key;
    LeaderBoardEntry entry = new LeaderBoardEntry(userId, score);
    Dictionary<string, Object> entryValues = entry.ToDictionary();

    Dictionary<string, Object> childUpdates = new Dictionary<string, Object>();
    childUpdates["/scores/" + key] = entryValues;
    childUpdates["/user-scores/" + userId + "/" + key] = entryValues;

    mDatabase.UpdateChildrenAsync(childUpdates);
}

In questo esempio viene utilizzato Push() per creare una voce nel nodo contenente voci per tutti gli utenti in /scores/$key e contemporaneamente recuperare la chiave con Key . La chiave può quindi essere utilizzata per creare una seconda voce nei punteggi /user-scores/$userid/$key in /user-scores/$userid/$key .

Utilizzando questi percorsi, è possibile eseguire aggiornamenti simultanei su più posizioni nella struttura JSON con una singola chiamata a UpdateChildrenAsync() , ad esempio come questo esempio crea la nuova voce in entrambe le posizioni. Gli aggiornamenti simultanei fatti in questo modo sono atomici: tutti gli aggiornamenti hanno esito positivo o tutti gli aggiornamenti falliscono.

Elimina dati

Il modo più semplice per eliminare i dati è chiamare RemoveValue() su un riferimento alla posizione di tali dati.

È inoltre possibile eliminare specificando null come valore per un'altra operazione di scrittura come SetValueAsync() o UpdateChildrenAsync() . È possibile utilizzare questa tecnica con UpdateChildrenAsync() per eliminare più elementi figlio in una singola chiamata API.

Scopri quando vengono impegnati i tuoi dati.

Per sapere quando i tuoi dati sono vincolati al server di database in tempo reale di Firebase, puoi aggiungere una continuazione. Entrambi SetValueAsync() e UpdateChildrenAsync() restituisce un Task che consente di sapere quando l'operazione è completata. Se la chiamata non ha esito positivo per qualsiasi motivo, l'attività IsFaulted sarà vera con la proprietà Exception indica il motivo dell'errore.

Salva i dati come transazioni

Quando si lavora con dati che potrebbero essere danneggiati da modifiche simultanee, come contatori incrementali, è possibile utilizzare un'operazione di transazione . Dai questa operazione a Func . Questo aggiornamento Func prende lo stato corrente dei dati come argomento e restituisce il nuovo stato desiderato che si desidera scrivere. Se un altro client scrive nella posizione prima che il nuovo valore venga scritto correttamente, la funzione di aggiornamento viene richiamata nuovamente con il nuovo valore corrente e la scrittura viene ritentata.

Ad esempio, in un gioco potresti consentire agli utenti di aggiornare una classifica con i cinque punteggi più alti:

private void AddScoreToLeaders(string email, 
                               long score,
                               DatabaseReference leaderBoardRef) {

    leaderBoardRef.RunTransaction(mutableData => {
      List<object> leaders = mutableData.Value as List<object>

      if (leaders == null) {
        leaders = new List<object>();
      } else if (mutableData.ChildrenCount >= MaxScores) {
        long minScore = long.MaxValue;
        object minVal = null;
        foreach (var child in leaders) {
          if (!(child is Dictionary<string, object>)) continue;
          long childScore = (long)
                      ((Dictionary<string, object>)child)["score"];
          if (childScore < minScore) {
            minScore = childScore;
            minVal = child;
          }
        }
        if (minScore > score) {
          // The new score is lower than the existing 5 scores, abort.
          return TransactionResult.Abort();
        }

        // Remove the lowest score.
        leaders.Remove(minVal);
      }

      // Add the new high score.
      Dictionary<string, object> newScoreMap =
                       new Dictionary<string, object>();
      newScoreMap["score"] = score;
      newScoreMap["email"] = email;
      leaders.Add(newScoreMap);
      mutableData.Value = leaders;
      return TransactionResult.Success(mutableData);
    });
}

L'uso di una transazione impedisce che la classifica sia errata se più utenti registrano i punteggi contemporaneamente o se il client aveva dati non aggiornati. Se la transazione viene rifiutata, il server restituisce il valore corrente al client, che esegue nuovamente la transazione con il valore aggiornato. Ciò si ripete fino a quando la transazione viene accettata o non sono stati fatti troppi tentativi.

Scrivi dati offline

Se un client perde la connessione di rete, l'app continuerà a funzionare correttamente.

Ogni client connesso a un database Firebase mantiene la propria versione interna di tutti i dati attivi. Quando i dati vengono scritti, vengono prima scritti in questa versione locale. Il client Firebase quindi sincronizza tali dati con i server di database remoti e con altri client su base "best-effort".

Di conseguenza, tutte le scritture nel database attivano immediatamente gli eventi locali, prima che i dati vengano scritti sul server. Ciò significa che la tua app rimane reattiva indipendentemente dalla latenza della rete o dalla connettività.

Una volta ristabilita la connettività, l'app riceve il set di eventi appropriato in modo che il client si sincronizzi con lo stato del server corrente, senza dover scrivere alcun codice personalizzato.

Prossimi passi