在網路上讀取及寫入資料

(選用) 使用 Firebase Local Emulator Suite 製作原型並進行測試

在說明應用程式如何從 Realtime Database 讀取及寫入資料之前，請先瞭解可用於原型設計和測試 Realtime Database 功能的一組工具：Firebase Local Emulator Suite。如果您正在嘗試不同的資料模型、調整安全性規則，或是尋找與後端互動時最經濟實惠的方式，那麼在本地作業而不部署即時服務，就是絕佳的選擇。

Realtime Database模擬器是 Local Emulator Suite 的一部分，可讓應用程式與模擬的資料庫內容和設定互動，以及選擇性地與模擬的專案資源 (函式、其他資料庫和安全性規則) 互動。

使用 Realtime Database 模擬器只需幾個步驟：

  1. 在應用程式的測試設定中加入一行程式碼，即可連線至模擬器。
  2. 從本機專案目錄的根目錄執行 firebase emulators:start。
  3. 使用 Realtime Database 平台 SDK 照常從應用程式的原型程式碼發出呼叫，或使用 Realtime Database REST API。

我們提供詳細的逐步操作說明，其中包含 Realtime Database 和 Cloud Functions。建議您也參閱 Local Emulator Suite 簡介。

取得資料庫參照

如要從資料庫讀取或寫入資料，您需要 firebase.database.Reference 的執行個體：

Web

import { getDatabase } from "firebase/database";

const database = getDatabase();
rtdb_get_reference.js

Web

var database = firebase.database();
index.js

寫入資料

本文將說明擷取資料的基本概念，以及如何排序和篩選 Firebase 資料。

將非同步事件監聽器附加至 firebase.database.Reference，即可擷取 Firebase 資料。監聽器會針對資料的初始狀態觸發一次，並且在資料變更時會再次觸發。

基本寫入作業

如要執行基本寫入作業，可以使用 set() 將資料儲存至指定參照，並取代該路徑中的所有現有資料。舉例來說，社交部落格應用程式可能會使用 set() 新增使用者，如下所示：

Web

import { getDatabase, ref, set } from "firebase/database";

function writeUserData(userId, name, email, imageUrl) {
  const db = getDatabase();
  set(ref(db, 'users/' + userId), {
    username: name,
    email: email,
    profile_picture : imageUrl
  });
}
rtdb_write_new_user.js

Web

function writeUserData(userId, name, email, imageUrl) {
  firebase.database().ref('users/' + userId).set({
    username: name,
    email: email,
    profile_picture : imageUrl
  });
}
read-and-write.js

使用 set() 會覆寫指定位置的資料，包括任何子項節點。

讀取資料

監聽值事件

如要在路徑讀取資料並監聽變更，請使用 onValue() 觀察 事件。您可以使用這個事件，讀取指定路徑的內容靜態快照，也就是事件發生時的內容。這個方法會在附加監聽器時觸發一次，之後每次資料 (包括子項) 變更時都會再次觸發。事件回呼會傳遞包含該位置所有資料 (包括子項資料) 的快照。如果沒有資料，當您在快照上呼叫 exists() 時，快照會傳回 false，呼叫 val() 時則會傳回 null。

以下範例說明社群網誌應用程式如何從資料庫擷取文章的星號數：

Web

import { getDatabase, ref, onValue } from "firebase/database";

const db = getDatabase();
const starCountRef = ref(db, 'posts/' + postId + '/starCount');
onValue(starCountRef, (snapshot) => {
  const data = snapshot.val();
  updateStarCount(postElement, data);
});
rtdb_social_listen_star_count.js

Web

var starCountRef = firebase.database().ref('posts/' + postId + '/starCount');
starCountRef.on('value', (snapshot) => {
  const data = snapshot.val();
  updateStarCount(postElement, data);
});
read-and-write.js

事件發生時，監聽器會收到 snapshot，其中包含資料庫中指定位置的資料。您可以使用 val() 方法，在 snapshot 中擷取資料。

讀取資料一次

使用 get() 讀取資料一次

無論應用程式處於連線或離線狀態，SDK 都能管理與資料庫伺服器的互動。

一般而言，您應使用上述值事件技術讀取資料，以便在後端資料更新時收到通知。這些監聽器技術可減少用量和帳單費用，並經過最佳化，可為使用者提供最佳的連線和離線體驗。

如果只需要資料一次，可以使用 get() 從資料庫取得資料快照。如果 get() 無法傳回伺服器值，用戶端會探查本機儲存空間快取，如果仍找不到該值，就會傳回錯誤。

不必要地使用 get() 可能會增加頻寬用量，導致效能降低。如要避免這種情況，請使用上述即時監聽器。

Web

import { getDatabase, ref, child, get } from "firebase/database";

const dbRef = ref(getDatabase());
get(child(dbRef, `users/${userId}`)).then((snapshot) => {
  if (snapshot.exists()) {
    console.log(snapshot.val());
  } else {
    console.log("No data available");
  }
}).catch((error) => {
  console.error(error);
});
rtdb_read_once_get.js

Web

const dbRef = firebase.database().ref();
dbRef.child("users").child(userId).get().then((snapshot) => {
  if (snapshot.exists()) {
    console.log(snapshot.val());
  } else {
    console.log("No data available");
  }
}).catch((error) => {
  console.error(error);
});
read-and-write.js

使用觀察器讀取一次資料

在某些情況下，您可能希望系統立即傳回本機快取中的值，而不是檢查伺服器上是否有更新的值。在這些情況下，您可以使用 once() 立即從本機磁碟快取取得資料。

這類資料只需要載入一次，且預期不會經常變更或需要主動監聽，因此非常實用。舉例來說，在先前的範例中，網誌應用程式會在使用者開始撰寫新文章時，使用這個方法載入使用者設定檔：

Web

import { getDatabase, ref, onValue } from "firebase/database";
import { getAuth } from "firebase/auth";

const db = getDatabase();
const auth = getAuth();

const userId = auth.currentUser.uid;
return onValue(ref(db, '/users/' + userId), (snapshot) => {
  const username = (snapshot.val() && snapshot.val().username) || 'Anonymous';
  // ...
}, {
  onlyOnce: true
});
rtdb_social_single_value_read.js

Web

var userId = firebase.auth().currentUser.uid;
return firebase.database().ref('/users/' + userId).once('value').then((snapshot) => {
  var username = (snapshot.val() && snapshot.val().username) || 'Anonymous';
  // ...
});
read-and-write.js

更新或刪除資料

更新特定欄位

如要同時寫入節點的特定子項，而不覆寫其他子節點，請使用 update() 方法。

呼叫 update() 時，您可以指定鍵的路徑，更新下層子項目的值。如果資料儲存在多個位置，以便更妥善地擴充，您可以使用資料扇出更新所有資料例項。

舉例來說，社群部落格應用程式可能會建立貼文，並同時使用下列程式碼，將貼文更新至近期活動動態消息和發布貼文的使用者活動動態消息：

Web

import { getDatabase, ref, child, push, update } from "firebase/database";

function writeNewPost(uid, username, picture, title, body) {
  const db = getDatabase();

  // A post entry.
  const postData = {
    author: username,
    uid: uid,
    body: body,
    title: title,
    starCount: 0,
    authorPic: picture
  };

  // Get a key for a new Post.
  const newPostKey = push(child(ref(db), 'posts')).key;

  // Write the new post's data simultaneously in the posts list and the user's post list.
  const updates = {};
  updates['/posts/' + newPostKey] = postData;
  updates['/user-posts/' + uid + '/' + newPostKey] = postData;

  return update(ref(db), updates);
}
rtdb_social_write_fan_out.js

Web

function writeNewPost(uid, username, picture, title, body) {
  // A post entry.
  var postData = {
    author: username,
    uid: uid,
    body: body,
    title: title,
    starCount: 0,
    authorPic: picture
  };

  // Get a key for a new Post.
  var newPostKey = firebase.database().ref().child('posts').push().key;

  // Write the new post's data simultaneously in the posts list and the user's post list.
  var updates = {};
  updates['/posts/' + newPostKey] = postData;
  updates['/user-posts/' + uid + '/' + newPostKey] = postData;

  return firebase.database().ref().update(updates);
}
read-and-write.js

這個範例會使用 push() 在節點中建立貼文，其中包含 /posts/$postid 中所有使用者的貼文，並同時擷取金鑰。然後，您可以使用該金鑰在 /user-posts/$userid/$postid 的使用者貼文中建立第二個項目。

使用這些路徑，您只需呼叫一次 update()，即可同時更新 JSON 樹狀結構中的多個位置，例如這個範例會在兩個位置建立新貼文。以這種方式進行的同步更新是不可分割的作業：所有更新都會成功，或所有更新都會失敗。

新增完成回呼

如要瞭解資料的提交時間，可以新增完成回呼。set() 和 update() 都會採用選用的完成回呼，在寫入作業已提交至資料庫時呼叫。如果呼叫失敗，回呼會收到錯誤物件，指出失敗原因。

Web

import { getDatabase, ref, set } from "firebase/database";

const db = getDatabase();
set(ref(db, 'users/' + userId), {
  username: name,
  email: email,
  profile_picture : imageUrl
})
.then(() => {
  // Data saved successfully!
})
.catch((error) => {
  // The write failed...
});
rtdb_social_completion_callback.js

Web

firebase.database().ref('users/' + userId).set({
  username: name,
  email: email,
  profile_picture : imageUrl
}, (error) => {
  if (error) {
    // The write failed...
  } else {
    // Data saved successfully!
  }
});
read-and-write.js

刪除資料

如要刪除資料，最簡單的方法是在該資料位置的參照上呼叫 remove()。

您也可以指定 null 做為其他寫入作業的值 (例如 set() 或 update())，藉此刪除資料。您可以使用這項技術，透過單一 API 呼叫刪除多個子項。update()

收到 Promise

如要瞭解資料何時會提交至 Firebase Realtime Database 伺服器，可以使用 Promise。set() 和 update() 都會傳回 Promise，您可以用來瞭解寫入作業何時會提交至資料庫。

卸離監聽器

如要移除回呼，請針對 Firebase 資料庫參照呼叫 off() 方法。

如要移除單一監聽器，請將其做為參數傳遞至 off()。 如果呼叫 off() 時未提供任何引數，系統會移除該位置的所有接聽者。

在父項監聽器上呼叫 off() 不會自動移除在子項節點上註冊的監聽器；您也必須在任何子項監聽器上呼叫 off()，才能移除回呼。

將資料儲存為交易

處理可能因並行修改而損毀的資料 (例如遞增計數器) 時，可以使用交易作業。您可以為這項作業提供更新函式和選用的完成回呼。更新函式會將資料的目前狀態做為引數，並傳回您要寫入的新所需狀態。如果其他用戶端在您的新值成功寫入位置之前寫入該位置，系統會使用新的目前值再次呼叫更新函式，並重試寫入作業。

舉例來說，在社群網誌應用程式範例中，您可以允許使用者為貼文加上和移除星號，並追蹤貼文獲得的星號數量，如下所示：

Web

import { getDatabase, ref, runTransaction } from "firebase/database";

function toggleStar(uid) {
  const db = getDatabase();
  const postRef = ref(db, '/posts/foo-bar-123');

  runTransaction(postRef, (post) => {
    if (post) {
      if (post.stars && post.stars[uid]) {
        post.starCount--;
        post.stars[uid] = null;
      } else {
        post.starCount++;
        if (!post.stars) {
          post.stars = {};
        }
        post.stars[uid] = true;
      }
    }
    return post;
  });
}
rtdb_social_star_transaction.js

Web

function toggleStar(postRef, uid) {
  postRef.transaction((post) => {
    if (post) {
      if (post.stars && post.stars[uid]) {
        post.starCount--;
        post.stars[uid] = null;
      } else {
        post.starCount++;
        if (!post.stars) {
          post.stars = {};
        }
        post.stars[uid] = true;
      }
    }
    return post;
  });
}
read-and-write.js

如果多位使用者同時為同一則貼文加上星號，或用戶端資料過時，使用交易可避免星號計數錯誤。如果交易遭拒，伺服器會將目前值傳回給用戶端，用戶端會使用更新後的值再次執行交易。這個程序會重複執行，直到交易獲得核准或您中止交易為止。

不可分割的伺服器端遞增

在上述用途中，我們會將兩個值寫入資料庫：為貼文加上/取消加星號的使用者 ID，以及遞增的星號數。如果我們已知道使用者正在為貼文加上星號，則可使用原子遞增作業，而非交易。

Web

function addStar(uid, key) {
  import { getDatabase, increment, ref, update } from "firebase/database";
  const dbRef = ref(getDatabase());

  const updates = {};
  updates[`posts/${key}/stars/${uid}`] = true;
  updates[`posts/${key}/starCount`] = increment(1);
  updates[`user-posts/${key}/stars/${uid}`] = true;
  updates[`user-posts/${key}/starCount`] = increment(1);
  update(dbRef, updates);
}
rtdb_social_star_increment.js

Web

function addStar(uid, key) {
  const updates = {};
  updates[`posts/${key}/stars/${uid}`] = true;
  updates[`posts/${key}/starCount`] = firebase.database.ServerValue.increment(1);
  updates[`user-posts/${key}/stars/${uid}`] = true;
  updates[`user-posts/${key}/starCount`] = firebase.database.ServerValue.increment(1);
  firebase.database().ref().update(updates);
}
read-and-write.js

這段程式碼不會使用交易作業，因此如果發生更新衝突，系統不會自動重新執行。不過，由於遞增作業是直接在資料庫伺服器上進行，因此不會發生衝突。

如要偵測及拒絕應用程式專屬的衝突，例如使用者為先前已加星號的貼文加上星號，請為該用途編寫自訂安全規則。

離線處理資料

如果用戶端失去網路連線，應用程式仍會正常運作。

連線至 Firebase 資料庫的每個用戶端都會維護任何有效資料的內部版本。寫入資料時，系統會先寫入這個本機版本。Firebase 用戶端隨後會盡力將資料與遠端資料庫伺服器和其他用戶端同步。

因此，所有寫入資料庫的作業都會立即觸發本機事件，然後才將資料寫入伺服器。也就是說，無論網路延遲或連線狀況如何，應用程式都能保持回應。

重新建立連線後，應用程式會收到適當的事件集，讓用戶端與目前的伺服器狀態同步，不必撰寫任何自訂程式碼。

如要進一步瞭解離線行為，請參閱「進一步瞭解線上和離線功能」。

後續步驟