Способы сохранения данных | |
---|---|
ПОМЕЩАТЬ | Запишите или замените данные по определенному пути , например fireblog/users/user1/<data> |
ПЛАСТЫРЬ | Обновите некоторые ключи для определенного пути, не заменяя все данные. |
ПОЧТА | Добавьте в список данных в нашей базе данных Firebase. Каждый раз, когда мы отправляем запрос POST , клиент Firebase генерирует уникальный ключ, например fireblog/users/<unique-id>/<data> |
УДАЛИТЬ | Удалить данные из указанной ссылки на базу данных Firebase. |
Запись данных с помощью PUT
Основная операция записи через REST API — PUT
. Чтобы продемонстрировать сохранение данных, мы создадим приложение для ведения блога с сообщениями и пользователями. Все данные нашего приложения будут храниться по пути `fireblog` по URL-адресу базы данных Firebase `https://docs-examples.firebaseio.com/fireblog`.
Начнем с сохранения некоторых пользовательских данных в нашей базе данных Firebase. Мы будем хранить каждого пользователя под уникальным именем пользователя, а также его полное имя и дату рождения. Поскольку у каждого пользователя будет уникальное имя пользователя, здесь имеет смысл использовать PUT
вместо POST
, поскольку у нас уже есть ключ и нет необходимости его создавать.
Используя PUT
, мы можем записать строку, число, логическое значение, массив или любой объект JSON в нашу базу данных Firebase. В этом случае мы передадим ему объект:
curl -X PUT -d '{ "alanisawesome": { "name": "Alan Turing", "birthday": "June 23, 1912" } }' 'https://docs-examples.firebaseio.com/fireblog/users.json'
Когда объект JSON сохраняется в базе данных, свойства объекта автоматически сопоставляются с дочерними местоположениями вложенным образом. Если мы перейдем к вновь созданному узлу, мы увидим значение «Алан Тьюринг». Мы также можем сохранить данные непосредственно в дочернее местоположение:
curl -X PUT -d '"Alan Turing"' \ 'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/name.json'
curl -X PUT -d '"June 23, 1912"' \ 'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/birthday.json'
Два приведенных выше примера — запись значения одновременно с объектом и запись их отдельно в дочерние местоположения — приведут к сохранению одних и тех же данных в нашей базе данных Firebase:
{ "users": { "alanisawesome": { "date_of_birth": "June 23, 1912", "full_name": "Alan Turing" } } }
Успешный запрос будет обозначен кодом состояния HTTP 200 OK
, а ответ будет содержать данные, которые мы записали в базу данных. Первый пример вызовет только одно событие на клиентах, наблюдающих за данными, тогда как второй пример вызовет два. Важно отметить, что если данные уже существовали на пути пользователя, первый подход перезаписал бы их, но второй метод только изменил бы значение каждого отдельного дочернего узла, оставив другие дочерние узлы неизменными. PUT
эквивалентен set()
в нашем JavaScript SDK.
Обновление данных с помощью PATCH
Используя запрос PATCH
, мы можем обновить определенные дочерние элементы в определенном месте, не перезаписывая существующие данные. Добавим ник Тьюринга в его пользовательские данные с помощью PATCH
запроса:
curl -X PATCH -d '{ "nickname": "Alan The Machine" }' \ 'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'
Приведенный выше запрос напишет nickname
нашему объекту alanisawesome
не удаляя name
или birthday
детей. Обратите внимание: если бы вместо этого мы отправили здесь запрос PUT
, name
и birthday
были бы удалены, поскольку они не были включены в запрос. Данные в нашей базе данных Firebase теперь выглядят так:
{ "users": { "alanisawesome": { "date_of_birth": "June 23, 1912", "full_name": "Alan Turing", "nickname": "Alan The Machine" } } }
Успешный запрос будет обозначен кодом состояния HTTP 200 OK
, а ответ будет содержать обновленные данные, записанные в базу данных.
Firebase также поддерживает многопутевые обновления. Это означает, что PATCH
теперь может обновлять значения в нескольких местах вашей базы данных Firebase одновременно. Эта мощная функция позволяет вам денормализовать ваши данные . Используя многопутевые обновления, мы можем добавлять псевдонимы как Алану, так и Грейс одновременно:
curl -X PATCH -d '{ "alanisawesome/nickname": "Alan The Machine", "gracehopper/nickname": "Amazing Grace" }' \ 'https://docs-examples.firebaseio.com/fireblog/users.json'
После этого обновления к Алану и Грейс были добавлены прозвища:
{ "users": { "alanisawesome": { "date_of_birth": "June 23, 1912", "full_name": "Alan Turing", "nickname": "Alan The Machine" }, "gracehop": { "date_of_birth": "December 9, 1906", "full_name": "Grace Hopper", "nickname": "Amazing Grace" } } }
Обратите внимание, что попытка обновить объекты путем записи объектов с включенными путями приведет к другому поведению. Давайте посмотрим, что произойдет, если мы вместо этого попытаемся обновить Грейс и Алана следующим образом:
curl -X PATCH -d '{ "alanisawesome": {"nickname": "Alan The Machine"}, "gracehopper": {"nickname": "Amazing Grace"} }' \ 'https://docs-examples.firebaseio.com/fireblog/users.json'
Это приводит к другому поведению, а именно к перезаписи всего узла /fireblog/users
:
{ "users": { "alanisawesome": { "nickname": "Alan The Machine" }, "gracehop": { "nickname": "Amazing Grace" } } }
Обновление данных с помощью условных запросов
Вы можете использовать условные запросы, REST-эквивалент транзакций, для обновления данных в соответствии с их существующим состоянием. Например, если вы хотите увеличить счетчик голосов «за» и убедиться, что счетчик точно отражает несколько одновременных голосов «за», используйте условный запрос для записи нового значения в счетчик. Вместо двух операций записи, которые изменяют счетчик на одно и то же число, один из запросов на запись завершается неудачей, и вы можете затем повторить запрос с новым значением.- Чтобы выполнить условный запрос в определенном месте, получите уникальный идентификатор текущих данных в этом месте или ETag. Если данные изменяются в этом месте, ETag также меняется. Вы можете запросить ETag любым способом, кроме
PATCH
. В следующем примере используется запросGET
. В частности, вызов ETag в заголовке возвращает ETag указанного местоположения в ответе HTTP.curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
HTTP/1.1 200 OK Content-Length: 6 Content-Type: application/json; charset=utf-8 Access-Control-Allow-Origin: * ETag: [ETAG_VALUE] Cache-Control: no-cache 10 // Current value of the data at the specified location
- Включите возвращенный ETag в свой следующий запрос
PUT
илиDELETE
, чтобы обновить данные, которые конкретно соответствуют этому значению ETag. Следуя нашему примеру, чтобы обновить счетчик до 11 или на 1 больше, чем первоначально полученное значение, равное 10, и отклонить запрос, если значение больше не соответствует, используйте следующий код: Если значение данных в указанном местоположении по-прежнему равно 10, ETag в запросеcurl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match:[ETAG_VALUE]'
PUT
совпадает, и запрос завершается успешно, в базу данных записывается 11. Если местоположение больше не соответствует ETag, что может произойти, если другой пользователь записал новое значение в базу данных, запрос не будет выполнен без записи в местоположение. Возвращаемый ответ включает новое значение и ETag.HTTP/1.1 200 OK Content-Length: 6 Content-Type: application/json; charset=utf-8 Access-Control-Allow-Origin: * Cache-Control: no-cache 11 // New value of the data at the specified location, written by the conditional request
HTTP/1.1 412 Precondition Failed Content-Length: 6 Content-Type: application/json; charset=utf-8 Access-Control-Allow-Origin: * ETag: [ETAG_VALUE] Cache-Control: no-cache 12 // New value of the data at the specified location
- Используйте новую информацию, если решите повторить запрос. Realtime Database не повторяет автоматически неудачные условные запросы. Однако вы можете использовать новое значение и ETag для создания нового условного запроса с информацией, возвращаемой ответом на ошибку.
Условные запросы на основе REST реализуют стандарт HTTP if-match . Однако они отличаются от стандартных следующими моментами:
- Вы можете указать только одно значение ETag для каждого запроса на совпадение, а не несколько.
- Хотя стандарт предполагает, что ETags будет возвращаться со всеми запросами, база данных Realtime возвращает ETags только с запросами, включая заголовок
X-Firebase-ETag
. Это снижает затраты на выставление счетов за стандартные запросы.
Условные запросы также могут выполняться медленнее, чем типичные запросы REST.
Сохранение списков данных
Чтобы сгенерировать уникальный ключ на основе временной метки для каждого дочернего элемента, добавленного в ссылку на базу данных Firebase, мы можем отправить запрос POST
. Для нашего пути users
имело смысл определить наши собственные ключи, поскольку каждый пользователь имеет уникальное имя пользователя. Но когда пользователи добавляют сообщения блога в приложение, мы будем использовать запрос POST
для автоматического создания ключа для каждого сообщения блога:
curl -X POST -d '{ "author": "alanisawesome", "title": "The Turing Machine" }' 'https://docs-examples.firebaseio.com/fireblog/posts.json'
Наш путь posts
теперь содержит следующие данные:
{ "posts": { "-JSOpn9ZC54A4P4RoqVa": { "author": "alanisawesome", "title": "The Turing Machine" } } }
Обратите внимание, что ключ -JSOpn9ZC54A4P4RoqVa
был сгенерирован для нас автоматически, поскольку мы использовали запрос POST
. Успешный запрос будет обозначен кодом состояния HTTP 200 OK
, а ответ будет содержать ключ новых добавленных данных:
{"name":"-JSOpn9ZC54A4P4RoqVa"}
Удаление данных
Чтобы удалить данные из базы данных, мы можем отправить запрос DELETE
с URL-адресом пути, из которого мы хотим удалить данные. Следующее приведет к удалению Алана из пути нашего users
:
curl -X DELETE \ 'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'
Успешный запрос DELETE
будет обозначен кодом состояния HTTP 200 OK
с ответом, содержащим JSON null
.
Параметры URI
REST API принимает следующие параметры URI при записи данных в базу данных:
авторизация
Параметр запроса auth
обеспечивает доступ к данным, защищенным Firebase Realtime Database Security Rules , и поддерживается всеми типами запросов. Аргументом может быть либо секрет нашего приложения Firebase, либо токен аутентификации, который мы рассмотрим в разделе авторизации пользователя . В следующем примере мы отправляем запрос POST
с параметром auth
, где CREDENTIAL
— это либо секрет нашего приложения Firebase, либо токен аутентификации:
curl -X POST -d '{"Authenticated POST request"}' \ 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'
распечатать
Параметр print
позволяет нам указать формат нашего ответа из базы данных. Добавление print=pretty
к нашему запросу вернет данные в удобочитаемом формате. print=pretty
поддерживается запросами GET
, PUT
, POST
, PATCH
и DELETE
.
Чтобы подавить вывод сервера при записи данных, мы можем добавить к нашему запросу print=silent
. Результирующий ответ будет пустым и будет обозначен кодом состояния HTTP 204 No Content
если запрос успешен. print=silent
поддерживается запросами GET
, PUT
, POST
и PATCH
.
Запись значений сервера
Значения сервера можно записать в место с помощью значения-заполнителя, которое представляет собой объект с одним ключом ".sv"
. Значение этого ключа — это тип значения сервера, которое мы хотим установить. Например, чтобы установить временную метку при создании пользователя, мы могли бы сделать следующее:
curl -X PUT -d '{".sv": "timestamp"}' \ 'https://docs-examples.firebaseio.com/alanisawesome/createdAt.json'
"timestamp"
— единственное поддерживаемое значение сервера и представляет собой время, прошедшее с эпохи UNIX в миллисекундах.
Улучшение производительности записи
Если мы записываем в базу данных большие объемы данных, мы можем использовать параметр print=silent
чтобы улучшить производительность записи и уменьшить использование полосы пропускания. При обычном режиме записи сервер отвечает записанными данными JSON. Если указано значение print=silent
, сервер немедленно закрывает соединение после получения данных, сокращая использование полосы пропускания.
В тех случаях, когда мы делаем много запросов к базе данных, мы можем повторно использовать HTTPS-соединение, отправив запрос Keep-Alive
в HTTP-заголовке.
Условия ошибки
REST API вернет коды ошибок в следующих случаях:
Коды состояния HTTP | |
---|---|
400 неверный запрос | Одно из следующих состояний ошибки:
|
401 Несанкционированный | Одно из следующих состояний ошибки:
|
404 Не найден | Указанная база данных Firebase не найдена. |
500 Внутренняя ошибка сервера | Сервер вернул ошибку. Дополнительные сведения см. в сообщении об ошибке. |
503 Сервис недоступен | Указанная база данных Firebase Realtime временно недоступна, что означает, что запрос не был предпринят. |
Защита данных
В Firebase есть язык безопасности, который позволяет нам определять, какие пользователи имеют доступ для чтения и записи к различным узлам наших данных. Подробнее об этом можно прочитать в Realtime Database Security Rules .
Теперь, когда мы рассмотрели сохранение данных, в следующем разделе мы можем узнать, как получить наши данные из базы данных Firebase через REST API.