Сохранять данные

Прежде чем вы начнете

Прежде чем вы сможете использовать базу данных в реальном времени , вам необходимо:

  • Зарегистрируйте свой проект Unity и настройте его для использования Firebase.

    • Если ваш проект Unity уже использует Firebase, значит, он уже зарегистрирован и настроен для Firebase.

    • Если у вас нет проекта Unity, вы можете скачать образец приложения .

  • Добавьте SDK Firebase Unity (в частности, FirebaseDatabase.unitypackage ) в свой проект Unity.

Обратите внимание, что добавление Firebase в ваш проект Unity включает задачи как в консоли Firebase , так и в вашем открытом проекте Unity (например, вы загружаете файлы конфигурации Firebase из консоли, а затем перемещаете их в свой проект Unity).

Сохранение данных

Существует пять способов записи данных в базу данных Firebase Realtime:

Метод Общее использование
SetValueAsync() Запишите или замените данные по определенному пути, например, users/<user-id>/<username> .
SetRawJsonValueAsync() Запишите или замените данные необработанным Json, например, users/<user-id>/<username> .
Push() Добавить в список данных. Каждый раз, когда вы вызываете Push() , Firebase генерирует уникальный ключ, который также можно использовать в качестве уникального идентификатора, например user-scores/<user-id>/<unique-score-id> .
UpdateChildrenAsync() Обновите некоторые ключи для определенного пути без замены всех данных.
RunTransaction() Обновляйте сложные данные, которые могут быть повреждены одновременными обновлениями.

Получить ссылку на базу данных

Чтобы записать данные в базу данных, вам нужен экземпляр DatabaseReference :

using Firebase;
using Firebase.Database;

public class MyScript: MonoBehaviour {
  void Start() {
    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

Запись, обновление или удаление данных по ссылке

Основные операции записи

Для основных операций записи вы можете использовать SetValueAsync() для сохранения данных по указанной ссылке, заменяя любые существующие данные по этому пути. Вы можете использовать этот метод для передачи типов, соответствующих доступным типам JSON, следующим образом:

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

Если вы используете типизированный объект C#, вы можете использовать встроенный JsonUtility.ToJson() для преобразования объекта в необработанный Json и вызвать SetRawJsonValueAsync() . Например, у вас может быть класс User, который выглядит следующим образом:

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

    public User() {
    }

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

Вы можете добавить пользователя с помощью SetRawJsonValueAsync() следующим образом:

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);
}

Использование SetValueAsync() или SetRawJsonValueAsync() таким образом перезаписывает данные в указанном месте, включая все дочерние узлы. Однако вы все равно можете обновить дочерний объект, не перезаписывая весь объект. Если вы хотите разрешить пользователям обновлять свои профили, вы можете обновить имя пользователя следующим образом:

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

Добавить к списку данных

Используйте метод Push() для добавления данных в список в многопользовательских приложениях. Метод Push() генерирует уникальный ключ каждый раз, когда к указанной ссылке Firebase добавляется новый дочерний элемент. Используя эти автоматически сгенерированные ключи для каждого нового элемента в списке, несколько клиентов могут одновременно добавлять дочерние элементы в одно и то же место без конфликтов записи. Уникальный ключ, сгенерированный функцией Push() , основан на метке времени, поэтому элементы списка автоматически упорядочиваются в хронологическом порядке.

Вы можете использовать ссылку на новые данные, возвращаемые методом Push() , чтобы получить значение автоматически сгенерированного ключа дочернего элемента или установить данные для дочернего элемента. Вызов Key для ссылки Push() возвращает значение автоматически сгенерированного ключа.

Обновить определенные поля

Для одновременной записи в определенные дочерние узлы узла без перезаписи других дочерних узлов используйте метод UpdateChildrenAsync() .

При вызове UpdateChildrenAsync() можно обновить дочерние значения нижнего уровня, указав путь для ключа. Если данные хранятся в нескольких местах для лучшего масштабирования, вы можете обновить все экземпляры этих данных с помощью разветвления данных . Например, в игре может быть такой класс LeaderboardEntry :

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;
    }
}

Чтобы создать LeaderboardEntry и одновременно обновить его до последней ленты результатов и собственного списка результатов пользователя, игра использует следующий код:

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);
}

В этом примере Push() используется для создания записи в узле, содержащей записи для всех пользователей в /scores/$key , и одновременного получения ключа с помощью Key . Затем ключ можно использовать для создания второй записи в баллах пользователя в /user-scores/$userid/$key .

Используя эти пути, вы можете выполнять одновременные обновления в нескольких местах в дереве JSON с помощью одного вызова UpdateChildrenAsync() , например, как в этом примере создается новая запись в обоих местах. Одновременные обновления, сделанные таким образом, являются атомарными: либо все обновления выполняются успешно, либо все обновления завершаются неудачно.

Удалить данные

Самый простой способ удалить данные — вызвать RemoveValue() для ссылки на расположение этих данных.

Вы также можете удалить, указав null в качестве значения для другой операции записи, такой как SetValueAsync() или UpdateChildrenAsync() . Вы можете использовать этот метод с UpdateChildrenAsync() для удаления нескольких дочерних элементов в одном вызове API.

Знайте, когда ваши данные зафиксированы.

Чтобы узнать, когда ваши данные будут зафиксированы на сервере базы данных Firebase Realtime, вы можете добавить продолжение. И SetValueAsync() и UpdateChildrenAsync() возвращают Task , которая позволяет узнать, когда операция завершена. Если вызов по какой-либо причине не удался, Tasks IsFaulted будет иметь значение true, а свойство Exception указывает, почему произошел сбой.

Сохранить данные как транзакции

При работе с данными, которые могут быть повреждены одновременными модификациями, такими как инкрементные счетчики, можно использовать транзакционную операцию . Вы даете этой операции Func . Это обновление Func принимает текущее состояние данных в качестве аргумента и возвращает новое желаемое состояние, которое вы хотели бы записать. Если другой клиент записывает в расположение до того, как ваше новое значение будет успешно записано, ваша функция обновления вызывается снова с новым текущим значением, и попытка записи повторяется.

Например, в игре вы можете разрешить пользователям обновлять таблицу лидеров с пятью наивысшими результатами:

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);
    });
}

Использование транзакции предотвращает неверную таблицу лидеров, если несколько пользователей одновременно записывают результаты или у клиента есть устаревшие данные. Если транзакция отклонена, сервер возвращает текущее значение клиенту, который снова запускает транзакцию с обновленным значением. Это повторяется до тех пор, пока транзакция не будет принята или не будет сделано слишком много попыток.

Запись данных в автономном режиме

Если клиент потеряет подключение к сети, ваше приложение продолжит работать правильно.

Каждый клиент, подключенный к базе данных Firebase, поддерживает собственную внутреннюю версию любых активных данных. Когда данные записываются, они сначала записываются в эту локальную версию. Затем клиент Firebase синхронизирует эти данные с удаленными серверами баз данных и с другими клиентами на основе «максимальных усилий».

В результате все записи в базу данных немедленно вызывают локальные события, прежде чем какие-либо данные будут записаны на сервер. Это означает, что ваше приложение остается отзывчивым независимо от сетевой задержки или подключения.

После восстановления подключения ваше приложение получает соответствующий набор событий, чтобы клиент синхронизировался с текущим состоянием сервера без необходимости писать какой-либо пользовательский код.

Следующие шаги