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

Чтение данных с помощью GET

Мы можем прочитать данные из нашей базы данных Firebase, отправив запрос GET к конечной точке URL. Давайте продолжим с нашим примером блога из предыдущего раздела и прочитаем все данные нашего блога:

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

Успешный запрос будет отмечен кодом состояния HTTP 200 OK , а ответ будет содержать данные, которые мы извлекаем.

Добавление параметров URI

REST API принимает несколько параметров запроса при чтении данных из нашей базы данных Firebase. Ниже перечислены наиболее часто используемые параметры. Полный список см. в Справочнике REST API .

авторизация

Параметр запроса auth разрешает доступ к данным, защищенным правилами безопасности базы данных Firebase Realtime , и поддерживается всеми типами запросов. Аргументом может быть либо секрет вашего приложения Firebase, либо токен аутентификации, как описано в разделе Пользователи в проектах Firebase . В следующем примере мы отправляем запрос GET с параметром auth , где CREDENTIAL — это либо секрет вашего приложения Firebase, либо токен аутентификации:

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

Распечатать

Указание print=pretty возвращает данные в удобочитаемом формате.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

Указание print=silent возвращает 204 No Content в случае успеха.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'

перезвонить

Чтобы выполнять вызовы REST из веб-браузера между доменами, вы можете использовать JSONP для переноса ответа в функцию обратного вызова JavaScript. Добавьте callback= , чтобы REST API обернул возвращенные данные в указанную вами функцию обратного вызова. Например:

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">

мелкий

Это расширенная функция, предназначенная для того, чтобы помочь вам работать с большими наборами данных, не загружая все подряд. Чтобы использовать его, добавьте в качестве параметра shallow=true . Это ограничит глубину возвращаемых данных. Если данные в расположении являются примитивом JSON (строка, число или логическое значение), его значение будет просто возвращено. Если моментальный снимок данных в расположении является объектом JSON, значения для каждого ключа будут усечены до true . Например, используя данные ниже:

{
  "message": {
    "user": {
      "name": "Chris"
    },
    "body": "Hello!"
  }
}

// A request to /message.json?shallow=true
// would return the following:
{
  "user": true,
  "body": true
}

// A request to /message/body.json?shallow=true
// would simply return:
"Hello!"

Попробуйте это с этим запросом curl :

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'

тайм-аут

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

Укажите timeouts в следующем формате: 3ms , 3s или 3min , с числом и единицей измерения. Если не указано, будет применено максимальное timeout 15min . Если timeout не является положительным или превышает максимальное значение, запрос будет отклонен с ошибкой HTTP 400. В следующем примере запрос GET включает timeout в 10 секунд.

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

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

Мы можем создавать запросы для фильтрации данных на основе различных факторов. Для начала вы указываете, как вы хотите фильтровать данные, используя параметр orderBy . Затем вы комбинируете orderBy с любым из пяти других параметров: limitToFirst , limitToLast , startAt , endAt и equalTo .

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

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

Мы можем фильтровать данные одним из трех способов: по дочернему ключу , по ключу или по значению . Запрос начинается с одного из этих параметров, а затем должен быть объединен с одним или несколькими из следующих параметров: startAt , endAt , limitToFirst , limitToLast или equalTo .

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

Мы можем фильтровать узлы по общему дочернему ключу, передав этот ключ параметру orderBy . Например, чтобы получить всех динозавров с высотой больше 3, мы можем сделать следующее:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

Любой узел, у которого нет дочернего ключа, по которому мы фильтруем, будет отсортирован со значением null . Подробнее о порядке упорядочения данных см. в разделе Как упорядочены данные .

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

{
  "lambeosaurus": {
    "dimensions": {
      "height" : 2.1,
      "length" : 12.5,
      "weight": 5000
    }
  },
  "stegosaurus": {
    "dimensions": {
      "height" : 4,
      "length" : 9,
      "weight" : 2500
    }
  }
}

Теперь, чтобы запросить высоту, мы используем полный путь к объекту, а не один ключ:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'

Запросы могут фильтроваться только по одному ключу за раз. Использование параметра orderBy несколько раз в одном и том же запросе приводит к ошибке.

Фильтрация по ключу

Мы также можем фильтровать узлы по их ключам, используя параметр orderBy="$key" . В следующем примере извлекаются все динозавры с именами, начинающимися с букв от a до m :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'

Фильтрация по значению

Мы можем фильтровать узлы по значению их дочерних ключей, используя параметр orderBy="$value" . Допустим, динозавры участвуют в спортивных соревнованиях, и мы отслеживаем их результаты в следующем формате:

{
  "scores": {
    "bruhathkayosaurus": 55,
    "lambeosaurus": 21,
    "linhenykus": 80,
    "pterodactyl": 93,
    "stegosaurus": 5,
    "triceratops": 22
  }
}

Чтобы получить всех динозавров с оценкой выше 50, мы могли бы сделать следующий запрос:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'

См . Как упорядочиваются данные , чтобы узнать, как сортируются null , логические, строковые и объектные значения при использовании orderBy="$value" .

Комплексная фильтрация

Мы можем комбинировать несколько параметров для создания более сложных запросов.

Ограничение запросов

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

Используя нашу базу данных фактов о динозаврах и orderBy , мы можем найти двух самых тяжелых динозавров:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'

Точно так же мы можем найти двух самых коротких динозавров, используя limitToFirst :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'

Мы также можем выполнять лимитные запросы с помощью orderBy="$value" . Если мы хотим создать таблицу лидеров с тремя самыми результативными спортсменами-динозаврами, мы можем сделать следующее:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'

Запросы диапазона

Использование startAt , endAt и equalTo позволяет нам выбирать произвольные начальные и конечные точки для наших запросов. Например, если мы хотим найти всех динозавров ростом не менее трех метров, мы можем объединить orderBy и startAt :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

Мы можем использовать endAt , чтобы найти всех динозавров, имена которых лексикографически предшествуют птеродактилю:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

Мы можем комбинировать startAt и endAt , чтобы ограничить оба конца нашего запроса. Следующий пример находит всех динозавров, чье имя начинается с буквы «b»:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

Запросы диапазона также полезны, когда вам нужно разбить данные на страницы.

Собираем все вместе

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

MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"`
curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"

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

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

Сортировать по

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

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

заказ по = "$ ключ"

При использовании параметра orderBy="$key" для сортировки данных данные будут возвращены в порядке возрастания по ключу следующим образом. Имейте в виду, что ключи могут быть только строками.

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

заказ по = "$ значение"

При использовании параметра orderBy="$value" для сортировки данных дочерние элементы будут упорядочены по их значению. Критерии упорядочения такие же, как данные, упорядоченные по дочернему ключу, за исключением того, что вместо значения указанного дочернего ключа используется значение узла.

заказ по = "$ приоритет"

При использовании параметра orderBy="$priority" для сортировки данных порядок дочерних элементов определяется их приоритетом и ключом следующим образом. Имейте в виду, что значения приоритета могут быть только числами или строками.

1. Дети без приоритета (по умолчанию) идут первыми.
2. Следующими идут дети, у которых в приоритете число. Они отсортированы по приоритету, от меньшего к большему.
3. Дети со строкой в ​​качестве приоритета идут последними. Они отсортированы лексикографически по приоритету.
4. Всякий раз, когда два потомка имеют одинаковый приоритет (включая отсутствие приоритета), они сортируются по ключу. Первыми идут числовые клавиши (отсортированные по цифрам), за ними следуют остальные клавиши (отсортированные по лексикографической схеме).

Дополнительные сведения о приоритетах см. в справочнике по API .

Потоковая передача из REST API

Конечные точки Firebase REST поддерживают протокол EventSource / Server-Sent Events , что упрощает потоковую передачу изменений в одно место в нашей базе данных Firebase.

Чтобы начать работу с потоковой передачей, нам нужно сделать следующее:

1. Установите для заголовка Accept клиента значение text/event-stream
2. Уважайте перенаправления HTTP, в частности код состояния HTTP 307.
3. Включите параметр запроса auth , если расположение базы данных Firebase требует разрешения на чтение.

В ответ сервер будет отправлять именованные события по мере изменения состояния данных по запрошенному URL-адресу. Структура этих сообщений соответствует протоколу EventSource:

event: event name
data: JSON encoded data payload

Сервер может отправлять следующие события:

Ниже приведен пример набора событий, которые может отправить сервер:

// Set your entire cache to {"a": 1, "b": 2}
event: put
data: {"path": "/", "data": {"a": 1, "b": 2}}


// Put the new data in your cache under the key 'c', so that the complete cache now looks like:
// {"a": 1, "b": 2, "c": {"foo": true, "bar": false}}
event: put
data: {"path": "/c", "data": {"foo": true, "bar": false}}


// For each key in the data, update (or add) the corresponding key in your cache at path /c,
// for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}}
event: patch
data: {"path": "/c", "data": {"foo": 3, "baz": 4}}

Если вы используете Go, ознакомьтесь с Firego , сторонней оболочкой Firebase REST и Streaming API.