REST API базы данных Firebase

Использование API

Вы можете использовать любой URL-адрес базы данных Firebase Realtime в качестве конечной точки REST. Все, что вам нужно сделать, это добавить .json в конец URL-адреса и отправить запрос от вашего любимого HTTPS-клиента.

Требуется HTTPS. Firebase реагирует только на зашифрованный трафик, поэтому ваши данные остаются в безопасности.

GET — чтение данных

Данные из вашей Realtime Database можно прочитать, отправив HTTP-запрос GET к конечной точке. В следующем примере показано, как можно получить имя пользователя, которое вы ранее сохранили в Realtime Database .

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

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

{ "first": "Jack", "last": "Sparrow" }

PUT — запись данных

Вы можете записать данные с помощью запроса PUT .

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

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

{ "first": "Jack", "last": "Sparrow" }

POST — отправка данных

Чтобы выполнить эквивалент метода JavaScript push() (см. Списки данных ), вы можете выполнить запрос POST .

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

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

{ "name": "-INOQPH-aV_psbk3ZXEX" }

ПАТЧ - Обновление данных

Вы можете обновить определенные дочерние элементы в определенном месте, не перезаписывая существующие данные, используя запрос PATCH . Именованные дочерние элементы в данных, записываемых с помощью PATCH перезаписываются, но пропущенные дочерние элементы не удаляются. Это эквивалентно функции update() в JavaScript.

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

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

{ "last": "Jones" }

УДАЛИТЬ – Удаление данных

Вы можете удалить данные с помощью запроса DELETE :

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Успешный запрос DELETE обозначается кодом состояния HTTP 200 OK с ответом, содержащим значение JSON null .

Переопределение метода

Если вы выполняете вызовы REST из браузера, который не поддерживает предыдущие методы, вы можете переопределить метод запроса, выполнив запрос POST и установив свой метод с помощью заголовка запроса X-HTTP-Method-Override .

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Вы также можете использовать параметр запроса x-http-method-override . 

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

Условные запросы

Условные запросы, REST-эквивалент транзакционных операций SDK, обновляют данные в соответствии с определенным условием. Ознакомьтесь с обзором рабочего процесса и узнайте больше об условных запросах для REST в разделе Сохранение данных .

Firebase ETag

Firebase ETag — это уникальный идентификатор текущих данных в указанном месте. Если данные изменяются в этом месте, ETag также меняется. ETag Firebase должен быть указан в заголовке первоначального запроса REST (обычно GET , но может быть чем угодно, кроме PATCH ). 

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

если-соответствие

Условие if-match указывает значение ETag для данных, которые вы хотите обновить. Если вы используете это условие, Realtime Database выполняет только те запросы, в которых ETag, указанный в запросе на запись, соответствует ETag существующих данных в базе данных. Получите ETag в месте с помощью запроса ETag Firebase. Если вы хотите перезаписать любое местоположение, имеющее значение null, используйте null_etag . 

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

Ожидаемые ответы

В следующей таблице представлен обзор ожидаемых ответов для каждого типа запроса на основе соответствия ETag.

Тип запроса 'X-Firebase-ETag: правда' ETag совпадения
if_match: <matching etag>		 ETag не соответствует
if_match: <no matching etag>
ПОЛУЧАТЬ Статус/содержание ответа 200: "<data_at_path>" 400: «...не поддерживается.» 400: «...не поддерживается.»
Добавлены заголовки ETag: <ETag_data> Н/Д Н/Д
ПОМЕЩАТЬ Статус/содержание ответа 200: "<вводимые_данные>" 200: "<вводимые_данные>" 412: «...Несоответствие ETag.»
Добавлены заголовки ETag: <ETag_put_data> Н/Д ETag: <database_ETag>
ПОЧТА Статус/содержание ответа 200: "<post_data>" 400: «...не поддерживается.» 400: «...не поддерживается.»
Добавлены заголовки ETag: <ETag_post_data> Н/Д Н/Д
ПЛАСТЫРЬ Статус/содержание ответа 400: «...не поддерживается.» 400: «...не поддерживается.» 400: «...не поддерживается.»
Добавлены заголовки Н/Д Н/Д Н/Д
УДАЛИТЬ Статус/содержание ответа 200: ноль 200: "<data_after_put>" 412: «...Несоответствие ETag.»
Добавлены заголовки ETag: <ETag_of_null> Н/Д ETag: <database_ETag>

Параметры запроса

REST API базы данных Firebase принимает следующие параметры и значения запроса:

access_token

Поддерживается всеми типами запросов. Аутентифицирует этот запрос, чтобы разрешить доступ к данным, защищенным Firebase Realtime Database Security Rules . Подробности см. в документации по аутентификации REST . 

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

мелкий

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

Аргументы REST-методы Описание
мелкий ПОЛУЧАТЬ Ограничьте глубину ответа.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Обратите внимание, что shallow нельзя смешивать с другими параметрами запроса.

распечатать

Форматирует данные, возвращаемые в ответе от сервера.

Аргументы REST-методы Описание
симпатичный ПОЛУЧИТЬ, ПОСТАВИТЬ, ОТПРАВИТЬ, ИСПРАВИТЬ, УДАЛИТЬ Просматривайте данные в удобочитаемом формате.
тихий ПОЛУЧИТЬ, ПОСТАВИТЬ, ОТПРАВИТЬ, ПАТЧИТЬ Используется для подавления вывода сервера при записи данных. Результирующий ответ будет пустым и будет обозначен кодом состояния HTTP 204 No Content . 
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

перезвонить

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

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

формат

Если установлено значение export , сервер будет кодировать приоритеты в ответе.

Аргументы REST-методы Описание
экспорт ПОЛУЧАТЬ Включите в ответ приоритетную информацию. 
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

скачать

Поддерживается только GET . Если вы хотите инициировать загрузку файла ваших данных из веб-браузера, добавьте download= . Это заставляет службу REST добавлять соответствующие заголовки, чтобы браузеры знали, что данные нужно сохранять в файл.

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

тайм-аут

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

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

записьSizeLimit

Чтобы ограничить размер записи, вы можете указать параметр запроса writeSizeLimit как tiny (цель = 1 с), small (цель = 10 с), medium (цель = 30 с), large (цель = 60 с). База данных реального времени оценивает размер каждого запроса на запись и отменяет запросы, которые занимают больше времени, чем заданное.

Если вы укажете unlimited операций записи, разрешены исключительно большие записи (с полезной нагрузкой до 256 МБ), что может привести к блокировке последующих запросов, пока база данных обрабатывает текущую операцию. Записи не могут быть отменены после того, как они достигнут сервера.

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

Если объем записи слишком велик, вы увидите следующее сообщение об ошибке:

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

Кроме того, вы можете установить defaultWriteSizeLimit для всего экземпляра базы данных с помощью интерфейса командной строки Firebase. Это ограничение распространяется на все запросы, в том числе от SDK. Новые базы данных создаются со defaultWriteSizeLimit равным large . Вы не можете установить для defaultWriteSizeLimit значение tiny с помощью интерфейса командной строки Firebase.

firebase database:settings:set defaultWriteSizeLimit large

заказать по

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

limitToFirst, limitToLast, startAt, endAt, равныйTo

Дополнительную информацию см. в разделе руководства по фильтрации данных .

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

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

  • Установите для заголовка Accept клиента значение "text/event-stream"
  • Соблюдайте перенаправления HTTP, в частности код состояния HTTP 307.
  • Если для местоположения требуется разрешение на чтение, вы должны включить параметр auth

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

event: event name
data: JSON encoded data payload

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

помещать

Данные в формате JSON — это объект с двумя ключами: путь и данные . Ключ пути указывает на местоположение относительно URL-адреса запроса. Клиент должен заменить все данные в этом месте своего кэша данными .

пластырь

Данные в формате JSON — это объект с двумя ключами: путь и данные . Ключ пути указывает на местоположение относительно URL-адреса запроса. Для каждого ключа в data клиент должен заменить соответствующий ключ в своем кэше данными для этого ключа в сообщении.

поддерживать жизнь

Данные для этого события имеют null . Никаких действий не требуется.

отмена

Некоторые непредвиденные ошибки могут привести к отправке события отмены и разрыву соединения. Причина описана в данных, предоставленных для этого события. Некоторые потенциальные причины заключаются в следующем: 1. Firebase Realtime Database Security Rules больше не разрешают чтение в запрошенном месте. В `data` описании этой причины указано «Отказано в доступе». 2. При записи активировался стример событий, который отправил большое дерево JSON, размер которого превышает наш лимит в 512 МБ. `Данные` по этой причине: «Указанная полезная нагрузка слишком велика, запросите местоположение с меньшим количеством данных».

auth_revoked

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

Вот пример набора событий, которые может отправлять сервер: 

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

Приоритеты

На информацию о приоритете местоположения можно обращаться с помощью «виртуального дочернего объекта» с именем .priority . Вы можете читать приоритеты с помощью запросов GET и записывать их с помощью запросов PUT . Например, следующий запрос получает приоритет узла users/tom :

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

Чтобы записать приоритет и данные одновременно, вы можете добавить дочерний элемент .priority в полезные данные JSON:

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

Чтобы одновременно записать приоритет и примитивное значение (например, строку), вы можете добавить дочерний элемент .priority и поместить примитивное значение в дочерний элемент .value :

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

Это пишет "Tom" с приоритетом 1.0 . Приоритеты можно включать в полезные данные JSON на любой глубине.

Значения сервера

Вы можете записать значения сервера в определенном месте, используя значение заполнителя, которое представляет собой объект с одним ключом .sv . Значение этого ключа — это тип значения сервера, которое вы хотите установить. Например, следующий запрос устанавливает значение узла в соответствии с текущей меткой времени сервера Firebase:

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

Вы также можете записать приоритеты, используя значения сервера, используя указанный выше путь «виртуального дочернего элемента».

Поддерживаемые значения сервера включают:

Значение сервера
временная метка Время, прошедшее с эпохи UNIX, в миллисекундах.
приращение Укажите целое число или значение дельты с плавающей запятой в форме { ".sv": {"increment": <delta_value> }} , с помощью которого можно атомарно увеличить текущее значение базы данных. Если данные еще не существуют, обновление установит для данных значение дельты. Если значение дельты или существующие данные представляют собой числа с плавающей запятой, оба значения будут интерпретироваться как числа с плавающей запятой и применяться на серверной стороне как двойное значение. Двойная арифметика и представление двойных значений соответствуют семантике IEEE 754. Если имеется положительное/отрицательное целочисленное переполнение, сумма вычисляется как двойная.

Получение и обновление Firebase Realtime Database Security Rules

REST API также можно использовать для получения и обновления Firebase Realtime Database Security Rules для вашего проекта Firebase. Вам понадобится секрет вашего проекта Firebase, который вы можете найти на панели «Учетные записи служб» в настройках вашего проекта Firebase. 

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

Аутентификация запросов

По умолчанию запросы REST выполняются без аутентификации и будут успешными только в том случае, если правила Realtime Database разрешают общедоступный доступ для чтения или записи к данным. Для аутентификации вашего запроса используйте параметры запроса access_token= или auth= .

Дополнительные сведения об аутентификации через REST API см. в разделе Аутентификация запросов REST .

Условия ошибки

REST API базы данных Firebase может возвращать следующие коды ошибок.

Коды состояния HTTP
400 неверный запрос

Одно из следующих состояний ошибки:

  • Невозможно проанализировать данные PUT или POST .
  • Отсутствуют данные PUT или POST .
  • Запрос пытается передать слишком большие данные PUT или POST .
  • Вызов REST API содержит недопустимые дочерние имена как часть пути.
  • Путь вызова REST API слишком длинный.
  • Запрос содержит неизвестное значение сервера.
  • Индекс для запроса не определен в Firebase Realtime Database Security Rules .
  • Запрос не поддерживает один из указанных параметров запроса.
  • Запрос смешивает параметры запроса с поверхностным запросом GET .
401 Несанкционированный

Одно из следующих состояний ошибки:

  • Срок действия токена авторизации истек.
  • Токен аутентификации, используемый в запросе, недействителен.
  • Не удалось выполнить аутентификацию с помощью access_token.
  • Запрос нарушает ваши Firebase Realtime Database Security Rules .
404 Не найден Указанная Realtime Database не найдена.
500 Внутренняя ошибка сервера Сервер вернул ошибку. Дополнительные сведения см. в сообщении об ошибке.
503 Сервис недоступен Указанная база данных Firebase Realtime временно недоступна, что означает, что запрос не был предпринят.
412 Предварительное условие не выполнено Указанное значение ETag запроса в заголовке if-match не соответствует значению сервера.