Получение данных с помощью базы данных Firebase Realtime для C++

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

В этом документе рассматриваются основы извлечения данных, а также порядок упорядочивания и фильтрации данных Firebase.

Прежде чем начать

Убедитесь, что вы настроили свое приложение и можете получить доступ к базе данных, как описано в руководстве Get Started .

Извлечение данных

Данные Firebase извлекаются либо однократным вызовом GetValue() , либо присоединением к ValueListener по ссылке FirebaseDatabase . Прослушиватель значений вызывается один раз для начального состояния данных и снова каждый раз при изменении данных.

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

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

    // Get the root reference location of the database.
    firebase::database::DatabaseReference dbref = database->GetReference();

Прочитать данные один раз

Вы можете использовать метод GetValue() для однократного чтения статического снимка содержимого по указанному пути. Результат задачи будет содержать снимок, содержащий все данные в этом месте, включая дочерние данные. Если данных нет, возвращаемый снимок равен null .

  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").GetValue();

В момент запроса, но нам нужно дождаться завершения Future, прежде чем мы сможем прочитать значение. Поскольку игры обычно работают в цикле и меньше управляются обратными вызовами, чем другие приложения, вы обычно будете опрашивать для завершения.

  // In the game loop that polls for the result...

  if (result.status() != firebase::kFutureStatusPending) {
    if (result.status() != firebase::kFutureStatusComplete) {
      LogMessage("ERROR: GetValue() returned an invalid result.");
      // Handle the error...
    } else if (result.error() != firebase::database::kErrorNone) {
      LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
                 result.error_message());
      // Handle the error...
    } else {
      firebase::database::DataSnapshot snapshot = result.result();
      // Do something with the snapshot...
    }
  }

Здесь показаны некоторые базовые проверки ошибок. Более подробную информацию о проверке ошибок и способах определения готовности результата см. в справочнике firebase::Future.

Следите за событиями

Вы можете добавить слушателей, чтобы подписаться на изменения данных:

Базовый класс ValueListener

Базовый класс OnChildListener

Класс ValueListener

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

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

  class LeadersValueListener : public firebase::database::ValueListener {
   public:
    void OnValueChanged(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
                 error_message);
    }
  };

  // Elsewhere in the code...

  LeadersValueListener* listener = new LeadersValueListener();
  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

Результат Future&ltDataSnapshot&gt содержит данные в указанном месте в базе данных на момент события. Вызов value() для снимка возвращает Variant представляющий данные.

В этом примере метод OnCancelled также переопределяется, чтобы увидеть, отменено ли чтение. Например, чтение может быть отменено, если у клиента нет разрешения на чтение из расположения базы данных Firebase. database::Error укажет причину сбоя.

Класс ChildListener

Дочерние события запускаются в ответ на определенные операции, которые происходят с дочерними элементами узла из такой операции, как добавление нового дочернего элемента с помощью метода PushChild() или обновление дочернего элемента с помощью метода UpdateChildren() . Каждое из них вместе может быть полезно для прослушивания изменений определенного узла в базе данных. Например, игра может использовать эти методы вместе для мониторинга активности в комментариях игрового сеанса, как показано ниже:

  class SessionCommentsChildListener : public firebase::database::ChildListener {
   public:
    void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
                        const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildRemoved(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot ...
    }
    void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
                 error_code, error_message);
    }
  };

  // elsewhere ....

  SessionCommentsChildListener* listener = new SessionCommentsChildListener();
  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

Обратный вызов OnChildAdded обычно используется для получения списка элементов в базе данных Firebase. Обратный вызов OnChildAdded вызывается один раз для каждого существующего дочернего элемента, а затем снова каждый раз, когда новый дочерний элемент добавляется к указанному пути. Слушателю передается снимок, содержащий данные нового дочернего элемента.

Обратный вызов OnChildChanged вызывается каждый раз при изменении дочернего узла. Это включает любые изменения потомков дочернего узла. Обычно он используется вместе с вызовами OnChildAdded и OnChildRemoved для реагирования на изменения в списке элементов. Снимок, переданный слушателю, содержит обновленные данные для дочернего узла.

Обратный вызов OnChildRemoved срабатывает при удалении непосредственного потомка. Обычно он используется в сочетании с обратными вызовами OnChildAdded и OnChildChanged . Снимок, переданный обратному вызову, содержит данные для удаленного потомка.

Обратный вызов OnChildMoved срабатывает всякий раз, когда вызов OnChildChanged вызывается обновлением, которое вызывает переупорядочивание потомка. Он используется с данными, которые упорядочены с помощью OrderByChild или OrderByValue .

Сортировка и фильтрация данных

Вы можете использовать класс Realtime Database Query для извлечения данных, отсортированных по ключу, по значению или по значению дочернего элемента. Вы также можете отфильтровать отсортированный результат по определенному количеству результатов или диапазону ключей или значений.

Сортировать данные

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

Вы можете использовать только один метод order-by за раз. Вызов метода order-by несколько раз в одном запросе приводит к ошибке.

В следующем примере показано, как можно подписаться на таблицу лидеров, упорядоченную по количеству очков.

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score");

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

Это определяет firebase::Query , который в сочетании с ValueListener синхронизирует клиента с таблицей лидеров в базе данных, упорядоченной по баллам каждой записи. Вы можете прочитать больше об эффективном структурировании данных в разделе Structure Your Database .

Вызов метода OrderByChild() указывает дочерний ключ для упорядочивания результатов. В этом случае результаты сортируются по значению "score" в каждом дочернем элементе. Для получения дополнительной информации о том, как упорядочиваются другие типы данных, см . Как упорядочиваются данные запроса .

Фильтрация данных

Для фильтрации данных при построении запроса можно комбинировать любой из методов ограничения или диапазона с методом сортировки.

В отличие от методов order-by, вы можете комбинировать несколько функций limit или range. Например, вы можете комбинировать методы StartAt() и EndAt() чтобы ограничить результаты указанным диапазоном значений.

Даже если для запроса имеется только одно совпадение, снимок все равно представляет собой список; он содержит только один элемент.

Ограничить количество результатов

Вы можете использовать методы LimitToFirst() и LimitToLast() , чтобы задать максимальное количество потомков, которые будут синхронизированы для данного обратного вызова. Например, если вы используете LimitToFirst() чтобы задать ограничение в 100, вы изначально получите только до 100 обратных вызовов OnChildAdded . Если в вашей базе данных Firebase хранится менее 100 элементов, обратный вызов OnChildAdded срабатывает для каждого элемента.

При изменении элементов вы получаете обратные вызовы OnChildAdded для элементов, которые входят в запрос, и обратные вызовы OnChildRemoved для элементов, которые из него выпадают, так что общее число остается равным 100.

Например, приведенный ниже код возвращает наивысший балл из таблицы лидеров:

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

Фильтр по ключу или значению

Вы можете использовать StartAt() , EndAt() и EqualTo() для выбора произвольных начальных, конечных и эквивалентных точек для запросов. Это может быть полезно для разбиения данных на страницы или поиска элементов с потомками, имеющими определенное значение.

Как упорядочиваются данные запроса

В этом разделе объясняется, как данные сортируются каждым из методов сортировки в классе Query .

OrderByChild

При использовании OrderByChild() данные, содержащие указанный дочерний ключ, упорядочиваются следующим образом:

1. Сначала идут потомки с null значением для указанного дочернего ключа.
2. Далее идут дети со значением false для указанного дочернего ключа. Если несколько детей имеют значение false , они сортируются лексикографически по ключу.
3. Далее идут дети со значением true для указанного дочернего ключа. Если несколько детей имеют значение true , они сортируются лексикографически по ключу.
4. Далее следуют дети с числовым значением, отсортированные по возрастанию. Если несколько детей имеют одинаковое числовое значение для указанного дочернего узла, они сортируются по ключу.
5. Строки идут после чисел и сортируются лексикографически в порядке возрастания. Если несколько дочерних элементов имеют одинаковое значение для указанного дочернего узла, они упорядочиваются лексикографически по ключу.
6. Объекты располагаются последними и сортируются лексикографически по ключу в порядке возрастания.

OrderByKey

При использовании OrderByKey() для сортировки данных данные возвращаются в порядке возрастания ключа.

1. Сначала идут потомки с ключом, который можно проанализировать как 32-битное целое число, отсортированные в порядке возрастания.
2. Далее следуют дочерние элементы со строковым значением в качестве ключа, отсортированные лексикографически в порядке возрастания.

OrderByValue

При использовании OrderByValue() дети сортируются по их значению. Критерии упорядочивания такие же, как в OrderByChild() , за исключением того, что вместо значения указанного дочернего ключа используется значение узла.

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

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