API使用
您可以使用任何 Firebase 实时数据库 URL 作为 REST 端点。您所需要做的就是将.json
附加到 URL 末尾,并从您最喜欢的 HTTPS 客户端发送请求。
需要 HTTPS。 Firebase 仅响应加密流量,以便您的数据保持安全。
GET——读取数据
可以通过向端点发出 HTTP GET
请求来读取实时数据库中的数据。以下示例演示了如何检索先前存储在实时数据库中的用户名。
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
请求更新某个位置的特定子项,而无需覆盖现有数据。使用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
请求删除数据:
curl -X DELETE \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'
成功的DELETE
请求由200 OK
HTTP 状态代码和包含 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 也会发生变化。必须在初始 REST 请求的标头中指定 Firebase ETag(通常是GET
,但可以是PATCH
以外的任何内容)。
curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
如果匹配
if-match
条件指定要更新的数据的 ETag 值。如果您使用该条件,实时数据库仅完成写入请求中指定的 ETag 与数据库中现有数据的 ETag 匹配的请求。通过 Firebase ETag 请求在某个位置获取 ETag。如果您想覆盖任何空位置,请使用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:“<数据路径>” | 400:“……不支持……” | 400:“……不支持……” |
添加标题 | ETag:<数据的ETag> | 不适用 | 不适用 | |
放 | 响应状态/内容 | 200:“<放置数据>” | 200:“<放置数据>” | 412:“……ETag 不匹配……” |
添加标题 | ETag:<放置数据的ETag> | 不适用 | ETag:<database_ETag> | |
邮政 | 响应状态/内容 | 200:“<帖子数据>” | 400:“……不支持……” | 400:“……不支持……” |
添加标题 | ETag:<帖子数据的ETag> | 不适用 | 不适用 | |
修补 | 响应状态/内容 | 400:“……不支持……” | 400:“……不支持……” | 400:“……不支持……” |
添加标题 | 不适用 | 不适用 | 不适用 | |
删除 | 响应状态/内容 | 200:空 | 200:“<放置后的数据>” | 412:“……ETag 不匹配……” |
添加标题 | ETag:<ETag_of_null> | 不适用 | ETag:<database_ETag> |
查询参数
Firebase 数据库 REST API 接受以下查询参数和值:
访问令牌
所有请求类型都支持。验证此请求以允许访问受 Firebase 实时数据库安全规则保护的数据。有关详细信息,请参阅REST 身份验证文档。
curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'
浅的
这是一项高级功能,旨在帮助您处理大型数据集,而无需下载所有内容。将其设置为true
可限制某个位置返回的数据的深度。如果该位置的数据是 JSON 原语(字符串、数字或布尔值),则将简单地返回其值。如果该位置的数据快照是 JSON 对象,则每个键的值将被截断为true
。
论点 | 休息方法 | 描述 |
---|---|---|
浅的 | 得到 | 限制响应的深度。 |
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'
请注意, shallow
不能与任何其他查询参数混合。
打印
格式化服务器响应中返回的数据。
论点 | 休息方法 | 描述 |
---|---|---|
漂亮的 | 获取、放置、发布、修补、删除 | 以人类可读的格式查看数据。 |
沉默的 | 获取、放置、发布、修补 | 用于在写入数据时抑制服务器的输出。生成的响应将为空,并由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'
打回来
仅受GET
支持。要从 Web 浏览器跨域进行 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
,服务器将在响应中对优先级进行编码。
论点 | 休息方法 | 描述 |
---|---|---|
出口 | 得到 | 在响应中包含优先级信息。 |
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 错误。
写入大小限制
要限制写入的大小,可以将writeSizeLimit
查询参数指定为tiny
(target=1s)、 small
(target=10s)、 medium
(target=30s)、 large
(target=60s)。实时数据库会估计每个写入请求的大小,并中止需要比目标时间更长的请求。
如果您指定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.
此外,您可以使用 Firebase CLI 设置整个数据库实例的defaultWriteSizeLimit
。此限制适用于所有请求,包括来自 SDK 的请求。创建新数据库时将defaultWriteSizeLimit
设置为large
。您无法使用 Firebase CLI 将defaultWriteSizeLimit
设置为tiny
。
firebase database:settings:set defaultWriteSizeLimit large
排序依据
有关详细信息,请参阅指南中有关有序数据的部分。
limitToFirst、limitToLast、startAt、endAt、equalTo
有关详细信息,请参阅指南中有关过滤数据的部分。
从 REST API 进行流式传输
Firebase REST 端点支持EventSource / 服务器发送事件协议。要将更改流式传输到实时数据库中的单个位置,您需要执行以下操作:
- 将客户端的 Accept 标头设置为
"text/event-stream"
- 尊重 HTTP 重定向,特别是 HTTP 状态代码 307
- 如果位置需要读取权限,则必须包含
auth
参数
作为回报,服务器将在请求的 URL 处的数据状态发生变化时发送命名事件。这些消息的结构符合EventSource
协议。
event: event name data: JSON encoded data payload
服务器可能会发送以下事件:
放
JSON 编码的数据是一个具有两个键的对象: path和data 。路径键指向相对于请求 URL 的位置。客户端应该用data替换其缓存中该位置的所有数据。
修补
JSON 编码的数据是一个具有两个键的对象: path和data 。路径键指向相对于请求 URL 的位置。对于data中的每个键,客户端应将其缓存中的相应键替换为消息中该键的数据。
活着
此事件的数据为null
。无需采取任何行动。
取消
一些意外错误可能会发送“取消”事件并终止连接。为该事件提供的数据描述了原因。一些潜在的原因如下: 1. Firebase 实时数据库安全规则不再允许在请求的位置进行读取。此原因的“数据”描述是“权限被拒绝”。 2. 写入触发了一个事件流处理程序,该事件流处理程序发送了一个超过我们限制 512MB 的大型 JSON 树。此原因的“数据”是“指定的有效负载太大,请请求数据较少的位置。”
授权撤销
此事件的数据是一个字符串,指示凭证已过期。当提供的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 服务器的当前时间戳:
curl -X PUT -d '{".sv": "timestamp"}' \ 'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'
您还可以使用服务器值写入优先级,使用上面提到的“虚拟子”路径。
支持的服务器值包括:
服务器价值 | |
---|---|
时间戳 | 自 UNIX 纪元以来的时间,以毫秒为单位。 |
增量 | 提供一个整数或浮点增量值,格式为{ ".sv": {"increment": <delta_value> }} ,用于自动递增当前数据库值。如果数据尚不存在,则更新会将数据设置为增量值。如果增量值或现有数据中有一个是浮点数,则这两个值都将被解释为浮点数并作为双精度值应用于后端。双精度算术和双精度值的表示遵循 IEEE 754 语义。如果存在正/负整数溢出,则总和将计算为双精度。 |
检索和更新 Firebase 实时数据库安全规则
REST API 还可用于检索和更新 Firebase 项目的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 请求在不进行身份验证的情况下执行,并且只有在实时数据库规则允许对数据进行公共读取或写入访问时才会成功。要验证您的请求,请使用access_token=
或auth=
查询参数。
在验证 REST 请求中了解有关通过 REST API 进行身份验证的更多信息。
错误情况
Firebase 数据库 REST API 可能会返回以下错误代码。
HTTP 状态代码 | |
---|---|
400错误请求 | 以下错误情况之一:
|
401未经授权 | 以下错误情况之一:
|
404未找到 | 未找到指定的实时数据库。 |
500内部服务器错误 | 服务器返回错误。请参阅错误消息以获取更多详细信息。 |
503服务不可用 | 指定的 Firebase 实时数据库暂时不可用,这意味着未尝试请求。 |
412前提条件失败 | 请求在 if-match 标头中指定的 ETag 值与服务器的值不匹配。 |
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2024-03-20。