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 值與伺服器的值不符。 |
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2024-03-20 (世界標準時間)。