本頁面由 Cloud Translation API 翻譯而成。

正在儲存資料

省用資料的方式
PUT	將資料寫入或取代至已定義的路徑，例如 `fireblog/users/user1/<data>`
PATCH	更新已定義路徑的部分金鑰，而不會取代所有資料。
POST	新增至 Firebase 資料庫中的資料清單。每次傳送 `POST` 要求時，Firebase 用戶端都會產生專屬索引鍵，例如 `fireblog/users/<unique-id>/<data>`
刪除	從指定的 Firebase 資料庫參照移除資料。

請注意，所有範例都使用唯讀的 Firebase Realtime Database，即 docs-example.firebaseio.com。將這個 Realtime Database 網址替換為您有權存取的 Firebase 主控台中的網址。

使用 PUT 寫入資料

透過 REST API 進行的基本寫入作業是 PUT。為示範如何儲存資料，我們將建立一個含有文章和使用者的部落格應用程式。應用程式的所有資料都會儲存在 `fireblog` 路徑下，位於 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 物件儲存到資料庫時，系統會以巢狀方式自動將物件屬性對應至子項位置。如果我們前往新建立的節點，就會看到「Alan Turing」這個值。我們也可以直接將資料儲存到子位置：

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"
    }
  }
}

成功的要求會顯示 200 OK HTTP 狀態碼，回應則會包含我們寫入資料庫的資料。第一個範例只會在監控資料的用戶端上觸發一個事件，而第二個範例會觸發兩個事件。請注意，如果資料已存在於使用者路徑中，第一個方法會覆寫資料，但第二個方法只會修改各個子項節點的值，而不會變更其他子項。PUT 等同於 JavaScript SDK 中的 set()。

使用 PATCH 更新資料

使用 PATCH 要求，我們可以更新位置中的特定子項，而不會覆寫現有資料。讓我們透過 PATCH 要求，將 Turing 的暱稱加入他的使用者資料：

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"
    }
  }
}

成功的要求會顯示 200 OK HTTP 狀態碼，而回應會包含寫入資料庫的更新資料。

Firebase 也支援多路更新。這表示 PATCH 現在可以同時更新 Firebase 資料庫中多個位置的值，這項強大的功能可協助您將資料去規格化。使用多路徑更新功能，我們可以同時為 Alan 和 Grace 新增暱稱：

curl -X PATCH -d '{
  "alanisawesome/nickname": "Alan The Machine",
  "gracehopper/nickname": "Amazing Grace"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

這次更新後，Alan 和 Grace 都已新增暱稱：

{
  "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"
    }
  }
}

請注意，如果您嘗試透過寫入包含路徑的物件來更新物件，會導致不同的行為。讓我們看看如果改用這種方式更新 Grace 和 Alan 會發生什麼事：

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)，根據現有狀態更新資料。舉例來說，如果您想增加讚數計數器，並確保計數器準確反映多個同時讚數，請使用條件要求將新值寫入計數器。請注意，這兩次寫入作業不會將計數器變更為相同的數字，其中一個寫入要求會失敗，您可以使用新值重試要求。

如要在某個位置執行條件要求，請取得該位置目前資料的專屬 ID 或 ETag。如果該位置的資料有所變更，ETag 也會隨之變更。您可以使用 PATCH 以外的任何方法申請電子標籤。以下範例使用 GET 要求。
```
curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
```
在標頭中呼叫 ETag 時，會傳回 HTTP 回應中指定位置的 ETag。
```
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
```

在下一次 PUT 或 DELETE 要求中加入已傳回的 ETag，以便更新與該 ETag 值完全相符的資料。依照我們的範例，如要將計數器更新為 11，或比初始擷取值 10 大 1，並在值不再相符時要求失敗，請使用以下程式碼：

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match:[ETAG_VALUE]'

如果指定位置的資料值仍為 10，PUT 要求中的 ETag 會相符，且要求成功，系統會將 11 寫入資料庫。

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

如果位置不再符合 ETag (如果其他使用者將新值寫入資料庫，就可能發生這種情況)，要求就會失敗，且不會寫入位置。傳回回應包含新的值和 ETag。

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 標準。不過，這兩種圖層與標準圖層的差異如下：

每個 if-match 要求只能提供一個 ETag 值，不能提供多個。
雖然標準建議透過所有要求傳回 ETag，但 Realtime Database 只會在包含 X-Firebase-ETag 標頭的要求中傳回 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"
    }
  }
}

請注意，由於我們使用 POST 要求，因此系統會自動為我們產生 -JSOpn9ZC54A4P4RoqVa 金鑰。成功的要求會顯示 200 OK HTTP 狀態碼，而回應會包含新增資料的鍵：

{"name":"-JSOpn9ZC54A4P4RoqVa"}

移除資料

如要從資料庫中移除資料，我們可以傳送 DELETE 要求，並附上要刪除資料的路徑網址。以下指令會從 users 路徑中刪除 Alan：

curl -X DELETE \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

成功的 DELETE 要求會顯示 200 OK HTTP 狀態碼，並附帶含有 JSON null 的回應。

URI 參數

將資料寫入資料庫時，REST API 會接受下列 URI 參數：

auth

auth 要求參數可讓您存取受 Firebase Realtime Database Security Rules 保護的資料，且所有要求類型都支援這項參數。這個引數可以是 Firebase 應用程式密鑰或驗證權杖，我們會在使用者授權一節中說明。在以下範例中，我們會傳送含有 auth 參數的 POST 要求，其中 CREDENTIAL 是 Firebase 應用程式密鑰或驗證權杖：

curl -X POST -d '{"Authenticated POST request"}' \
  'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

如果已設定符記 debug 旗標，您可以在回應的 X-Firebase-Auth-Debug 標頭中找到偵錯資訊。

列印

print 參數可讓我們指定資料庫的回應格式。將 print=pretty 新增至要求後，系統會以人類可讀的格式傳回資料。print=pretty 支援 GET、PUT、POST、PATCH 和 DELETE 要求。

如要在寫入資料時抑制伺服器的輸出內容，我們可以將 print=silent 新增至要求。如果要求成功，則產生的回應會是空白，並以 204 No Content HTTP 狀態碼表示。print=silent 支援 GET、PUT、POST 和 PATCH 要求。

寫入伺服器值

您可以使用預留位置值，也就是具有單一 ".sv" 鍵的物件，在位置上寫入伺服器值。該鍵的值是我們要設定的伺服器值類型。舉例來說，如要設定使用者建立時的時間戳記，可以執行以下操作：

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://docs-examples.firebaseio.com/alanisawesome/createdAt.json'

"timestamp" 是唯一支援的伺服器值，以 UNIX Epoch 紀元時間為始 (單位為毫秒)。

提升寫入效能

如果我們要將大量資料寫入資料庫，可以使用 print=silent 參數來改善寫入效能，並減少頻寬使用量。在正常寫入行為中，伺服器會傳回已寫入的 JSON 資料。指定 print=silent 後，伺服器會在收到資料後立即關閉連線，藉此減少頻寬使用量。

如果我們向資料庫提出許多要求，可以在 HTTP 標頭中傳送 Keep-Alive 要求，藉此重複使用 HTTPS 連線。

錯誤條件

在下列情況下，REST API 會傳回錯誤代碼：

HTTP 狀態碼
400 錯誤的要求	發生下列任一錯誤情況：無法剖析 `PUT` 或 `POST` 資料。缺少 `PUT` 或 `POST` 資料。要求嘗試 `PUT` 或 `POST` 過大的資料。 REST API 呼叫包含無效的子項名稱做為路徑的一部分。 REST API 呼叫路徑太長。要求含有不相符的伺服器值。 Firebase Realtime Database Security Rules 中未定義查詢的索引。要求不支援指定的其中一個查詢參數。要求會將查詢參數與淺層 `GET` 要求混合。
401 未授權	發生下列任一錯誤情況：驗證權杖已過期。要求中使用的授權權杖無效。使用 access_token 驗證失敗。這項要求違反了您的 Firebase Realtime Database Security Rules。
404 找不到	找不到指定的 Firebase 資料庫。
500 內部伺服器錯誤	伺服器傳回錯誤。詳情請參閱錯誤訊息。
503 無法提供服務	指定的 Firebase 即時資料庫暫時無法使用，因此無法嘗試要求。

保護資料

Firebase 提供安全性語言，可讓我們定義哪些使用者可讀取及寫入資料的不同節點。詳情請參閱 Realtime Database Security Rules。

我們已介紹資料儲存作業，接下來將在下一節說明如何透過 REST API 從 Firebase 資料庫擷取資料。

正在儲存資料

省用資料的方式

使用 PUT 寫入資料

使用 PATCH 更新資料

使用條件式要求更新資料

儲存資料清單

移除資料

URI 參數

auth

列印

寫入伺服器值

提升寫入效能

錯誤條件

保護資料