API 用法
您可以将任何 Firebase Realtime Database 网址用作 REST 端点。您需要的一切
方法是将.json附加到网址末尾并发送请求
从您喜爱的 HTTPS 客户端提取。
必须提供 HTTPS。Firebase 仅响应加密流量，确保您的数据始终安全无虞。
GET - 读取数据
您可以通过发出 HTTP 请求来读取 Realtime Database 中的数据，
向端点发出 GET 请求。以下示例
展示了如何检索用户的
之前存储在 Realtime Database 中的名称。
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'
200 OK HTTP 状态代码表示请求成功。响应中包含与
GET 请求中的路径。
{ "first": "Jack", "last": "Sparrow" }
PUT - 写入数据
您可以通过 PUT 请求写入数据。
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'
200 OK HTTP 状态代码表示请求成功。响应包含
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'
成功的请求会显示 200 OK HTTP 状态
代码。响应包含新数据的子项名称
（在 POST 请求中指定）。
{ "name": "-INOQPH-aV_psbk3ZXEX" }
补丁 - 更新数据
您可以更新某个位置的特定子节点，而不覆盖
使用 PATCH 请求来提取现有数据。已命名的子项
使用 PATCH 写入的数据将被覆盖，但会被省略
子节点不会被删除。这相当于 JavaScript
update() 函数。
curl -X PATCH -d '{"last":"Jones"}' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'
成功的请求会显示 200 OK HTTP 状态
代码。响应包含
PATCH 请求。
{ "last": "Jones" }
DELETE - 删除数据
您可以使用 DELETE 请求删除数据：
curl -X DELETE \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'
成功的 DELETE 请求由
200 OK HTTP 状态代码，其响应中包含 JSON
null。
方法替换
如果从不支持
您可以替换请求方法，方法是使用
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 事务操作）会根据 满足特定条件查看工作流程概览并详细了解条件请求 请参阅保存数据中的说明。
Firebase ETag
Firebase ETag 是当前数据在指定位置的唯一标识符。如果
该位置的数据发生更改，则 ETag 也会更改。必须在
标头（通常是
GET，但可以是 PATCH 以外的任何值）。
curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
if-match
if-match 条件指定要更新的数据的 ETag 值。
如果使用该条件，则 Realtime Database 将仅完成符合以下条件的请求：
写入请求与数据库中现有数据的 ETag 匹配。提取
通过 Firebase ETag 请求在某个位置进行 ETag。如果您想覆盖
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: true” | ETag 与 if_match: <matching etag> 匹配 |
ETag 与 if_match: <no matching etag> 不匹配 |
|
|---|---|---|---|---|
| 获取 | 回复状态/内容 | 200：“<data_at_path>” | 400：“...不支持...” | 400：“...不支持...” |
| 添加的标头 | ETag：<ETag_of_data> | 不适用 | 不适用 | |
| PUT | 回复状态/内容 | 200：“<put_data>” | 200：“<put_data>” | 412：“...ETag 不匹配...” |
| 添加的标头 | ETag：<ETag_of_put_data> | 不适用 | ETag：<database_ETag> | |
| 投放后 | 回复状态/内容 | 200：“<post_data>” | 400：“...不支持...” | 400：“...不支持...” |
| 添加的标头 | ETag：<ETag_of_post_data> | 不适用 | 不适用 | |
| 补丁 | 回复状态/内容 | 400：“...不支持...” | 400：“...不支持...” | 400：“...不支持...” |
| 添加的标头 | 不适用 | 不适用 | 不适用 | |
| 删除 | 回复状态/内容 | 200：null | 200：“<data_after_put>” | 412：“...ETag 不匹配...” |
| 添加的标头 | ETag：<ETag_of_null> | 不适用 | ETag：<database_ETag> | |
查询参数
Firebase Database REST API 接受以下查询参数和 值：
access_token
适用于所有请求类型。对此请求进行身份验证，以允许 对受Firebase Realtime Database Security Rules保护的数据的访问权限。 请参阅 如需了解详情，请参阅 REST 身份验证文档。
curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'
shallow
这是一项高级功能
而不必下载所有数据。将此项设为
true，用于限制返回数据的深度
特定地理位置相应位置的数据是否为 JSON 原语
（字符串、数字或布尔值），则只会返回其值。如果
该位置的数据快照是一个 JSON 对象，
每个键的值都将被截断为 true。
| 参数 | REST 方法 | 说明 |
|---|---|---|
| 浅层 | GET | 限制响应的深度。 |
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'
请注意，shallow 不能与任何其他查询混用
参数。
设置服务器响应中返回的数据的格式。
| 参数 | REST 方法 | 说明 |
|---|---|---|
| 漂亮 | GET、PUT、POST、PATCH、DELETE | 以人类可读的格式查看数据。 |
| 静音 | GET、PUT、POST、PATCH |
用于在写入数据时禁止服务器输出。
由此产生的响应将是空的，并以
204 No Content HTTP 状态代码。
|
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'
callback
仅受 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 方法 | 说明 |
|---|---|---|
| 导出 | GET | 在响应中包含优先级信息。 |
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'
下载
仅受 GET 支持。如果您想触发文件
从网络浏览器下载您的数据，请添加 download=。
这会使 REST 服务添加适当的标头，
浏览器知道将数据保存到文件。
curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'
timeout
使用此参数可限制在服务器端执行读取操作的时间。如果读取 请求未在分配的时间内完成，则会终止并显示 HTTP 400 错误。此方法特别适合需要少量数据传输 也不想等待太长时间来获取可能庞大的子树。实际值 读取时间可能会因数据大小和缓存而异。
按以下格式指定 timeouts：3ms，
3s 或 3min，带有数字和单位。如果不是
指定的最大 timeout 为 15min
。如果timeout不是正数或超过上限，
该请求将被拒绝，并显示 HTTP 400 错误。
writeSizeLimit
要限制写入内容的大小 可将
writeSizeLimit 查询参数指定为
tiny（目标=1 秒）、small（目标=10 秒）、
medium（目标=30 秒）、large（目标=60 秒）。
Realtime Database 会估算每个写入请求的大小和取消请求
用时超过目标时间的请求。
如果您指定 unlimited，将进行超大写入操作（最多 256MB 载荷）
因此在数据库处理
当前操作。写入操作一旦到达服务器，便无法取消。
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
实例。此限制适用于所有请求，包括来自 SDK 的请求。
将创建新数据库，并将 defaultWriteSizeLimit 设置为 large。
您无法使用 Firebase CLI 将 defaultWriteSizeLimit 设置为 tiny。
firebase database:settings:set defaultWriteSizeLimit large
orderBy
请参阅本指南中的 有序数据 。
limitToFirst、limitToLast、startAt、endAt、equalTo
请参阅本指南中的 过滤数据 。
通过 REST API 流式传输
Firebase REST 端点支持 EventSource / 服务器发送事件 协议。如需将更改流式传输到 Realtime Database 中的单个营业地点，请执行以下操作： 您需要完成以下操作：
- 将客户端的 Accept 标头设置为
"text/event-stream" - 重视 HTTP 重定向，特别是 HTTP 状态代码 307
-
如果该位置需要读取权限，则您必须添加
auth参数
反过来，服务器会将指定事件作为
请求的网址更改。这些邮件的结构符合
EventSource 协议。
event: event name data: JSON encoded data payload
服务器可能会发送以下事件：
put
采用 JSON 编码的数据是包含两个键的对象：path 和数据。path 键指向 相对于请求网址的位置客户端应将所有 使用 data 缓存该位置的数据。
patch
采用 JSON 编码的数据是包含两个键的对象：path 和数据。path 键指向 相对于请求网址的位置对于 data，客户端应将 缓存中相应的键与消息中该键的数据。
keep-alive
此事件的数据为 null。您无需执行任何操作。
取消
某些意外错误可能会发送“cancel”事件并终止连接。 具体说明，请查看针对此事件提供的数据。一些可能的原因包括 如下： 1.Firebase Realtime Database Security Rules 不再允许在请求的位置执行读取操作。通过 对此原因的 `data` 说明为“权限遭拒”。 2. 某次写入操作触发了一个事件流式传输器，该事件流式传输器发送了一个超出限制的大型 JSON 树， 512 MB。此原因的 `data` 为“指定的载荷过大，请 数据量更少。”
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'
这将写入优先级为 1.0 的 "Tom"。
优先级可以包含在 JSON 载荷中的任何深度。
服务器值
您可以使用占位值写入某个位置的服务器值，
是具有单个 .sv 键的对象。该键的值是
希望设置的服务器值的类型。例如，以下
请求将节点的值设置为 Firebase 服务器当前的
timestamp：
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 项目的密钥， 您可在 <ph type="x-smartling-placeholder"></ph> 设置。
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 请求进行身份验证。
错误条件
Firebase Database REST API 可以返回以下错误代码。
| HTTP 状态代码 | |
|---|---|
| 400 请求错误 |
以下错误情况之一：
|
| 401 未经授权 |
以下错误情况之一：
|
| 404 找不到 | 找不到指定的 Realtime Database。 |
| 500 内部服务器错误 | 服务器返回一个错误。如需了解详情，请参阅错误消息 。 |
| 503 服务不可用 | 指定的 Firebase Realtime Database 暂时不可用， 表示未尝试过相应请求。 |
| 412 不满足前提条件 | 请求在 if-match 标头中指定的 ETag 值与服务器的值不匹配。 |