Прежде чем начать
Прежде чем использовать Realtime Database , вам необходимо:
Зарегистрируйте свой проект Unity и настройте его для использования Firebase.
Если ваш проект Unity уже использует Firebase, значит, он уже зарегистрирован и настроен для Firebase.
Если у вас нет проекта Unity, вы можете загрузить пример приложения .
Добавьте Firebase Unity SDK (в частности,
FirebaseDatabase.unitypackage
) в свой проект Unity.
Обратите внимание, что добавление Firebase в проект Unity включает в себя выполнение задач как в консоли Firebase , так и в открытом проекте Unity (например, вы загружаете файлы конфигурации Firebase из консоли, а затем перемещаете их в проект Unity).
Сохранение данных
Существует пять методов записи данных в Firebase Realtime Database :
Метод | Распространенное использование |
---|---|
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()
вы можете обновить дочерние значения нижнего уровня, указав путь для ключа. Если данные хранятся в нескольких местах для лучшего масштабирования, вы можете обновить все экземпляры этих данных с помощью data fan-out . Например, игра может иметь класс 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 Database , вы можете добавить продолжение. И 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 синхронизирует эти данные с удаленными серверами баз данных и с другими клиентами по принципу «наилучших усилий».
В результате все записи в базу данных немедленно запускают локальные события, до того, как какие-либо данные будут записаны на сервер. Это означает, что ваше приложение остается отзывчивым независимо от сетевой задержки или подключения.
После восстановления соединения ваше приложение получает соответствующий набор событий, чтобы клиент синхронизировался с текущим состоянием сервера, без необходимости написания какого-либо специального кода.