Firebase 数据库 REST API

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 错误。当您期望传输少量数据并且不想等待太长时间来获取可能巨大的子树时,这特别有用。实际读取时间可能会因数据大小和缓存而异。

使用以下格式指定timeouts3ms3s3min ,并带有数字和单位。如果未指定,则将应用最大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 编码的数据是一个具有两个键的对象: pathdata路径键指向相对于请求 URL 的位置。客户端应该用data替换其缓存中该位置的所有数据。

修补

JSON 编码的数据是一个具有两个键的对象: pathdata路径键指向相对于请求 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错误请求

以下错误情况之一:

  • 无法解析PUTPOST数据。
  • 缺少PUTPOST数据。
  • 该请求尝试PUTPOST太大的数据。
  • REST API 调用包含无效的子名称作为路径的一部分。
  • REST API 调用路径太长。
  • 该请求包含无法识别的服务器值。
  • 您的Firebase 实时数据库安全规则中未定义查询的索引。
  • 该请求不支持指定的查询参数之一。
  • 该请求将查询参数与浅层GET请求混合在一起。
401未经授权

以下错误情况之一:

404未找到未找到指定的实时数据库。
500内部服务器错误服务器返回错误。请参阅错误消息以获取更多详细信息。
503服务不可用指定的 Firebase 实时数据库暂时不可用,这意味着未尝试请求。
412前提条件失败请求在 if-match 标头中指定的 ETag 值与服务器的值不匹配。