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

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

We can read data from our Firebase database by issuing a GET request to its URL endpoint. Let's continue with our blog example from the previous section and read all of our blog post data:

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

A successful request will be indicated by a 200 OK HTTP status code, and the response will contain the data we're retrieving.

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

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

аутентификация

Параметр запроса auth обеспечивает доступ к данным, защищенным Firebase Realtime Database Security Rules , и поддерживается всеми типами запросов. Аргументом может быть либо секрет вашего приложения 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'

Specifying print=silent returns a 204 No Content on success.

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 .

Since all of us at Firebase think dinosaurs are pretty cool, we'll use a snippet from a sample database of dinosaur facts to demonstrate how you can filter data:

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

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

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

We can filter nodes by a common child key by passing that key to the orderBy parameter. For example, to retrieve all dinosaurs with a height greater than 3, we can do the following:

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

Any node that does not have the child key we're filtering on will be sorted with a value of null . For details on how data is ordered, see How Data is Ordered .

Firebase also supports queries ordered by deeply nested children, rather than only children one level down. This is useful if you have deeply nested data like this:

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

To query the height now, we use the full path to the object rather than a single key:

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

Queries can only filter by one key at a time. Using the orderBy parameter multiple times on the same request throws an error.

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

We can also filter nodes by their keys using the orderBy="$key" parameter. The following example retrieves all dinosaurs with a name starting with the letter a through 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'

See How Data is Ordered for an explanation on how null , boolean, string, and object values are sorted when using orderBy="$value" .

Сложная фильтрация

We can combine multiple parameters to construct more complex queries.

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

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

Using our dinosaur facts database and orderBy , we can find the two heaviest dinosaurs:

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'

We can also conduct limit queries with orderBy="$value" . If we want to create a leaderboard with the top three highest scoring dino sports competitors, we could do the following:

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'

We can use endAt to find all dinosaurs whose names come before Pterodactyl lexicographically:

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

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

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

Range queries are also useful when you need to paginate your data.

Собираем всё воедино

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

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

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

1. В первую очередь идут дочерние элементы, у которых указанный ключ дочернего элемента имеет null значение.
2. Children with a value of false for the specified child key come next. If multiple children have a value of false , they are sorted lexicographically by key.
3. Далее следуют дочерние элементы, у которых для указанного ключа дочернего элемента значение равно true . Если несколько дочерних элементов имеют значение true , они сортируются лексикографически по ключу.
4. Далее следуют дочерние узлы с числовым значением, отсортированные в порядке возрастания. Если несколько дочерних узлов имеют одинаковое числовое значение для указанного дочернего узла, они сортируются по ключу.
5. Строки следуют за числами и сортируются лексикографически в порядке возрастания. Если несколько дочерних узлов имеют одинаковое значение для указанного дочернего узла, они упорядочиваются лексикографически по ключу.
6. Объекты располагаются в самом конце и сортируются лексикографически по ключу в порядке возрастания.

orderBy="$key"

When using the orderBy="$key" parameter to sort your data, data will be returned in ascending order by key as follows. Keep in mind that keys can only be strings.

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

orderBy="$value"

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

orderBy="$priority"

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

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

Для получения более подробной информации о приоритетах см. справочник API .

Потоковая передача данных через REST API

REST-конечные точки Firebase поддерживают протокол 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 — стороннюю обертку над REST и Streaming API Firebase.