正在儲存資料

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

使用條件要求更新資料

1. 如要在某個位置執行條件要求，請取得該位置目前資料的專屬 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
   

2. 在下一次 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
   

3. 如果您決定重試要求，請使用新資訊。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'

列印

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 會傳回錯誤代碼：

保護資料

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