本文說明讀取及寫入 Firebase 資料的基本概念。
Firebase 資料會寫入 FirebaseDatabase
參照,並將非同步事件監聽器附加至參照來擷取。事件監聽器會在資料的初始狀態上觸發一次,且在資料變更時再次觸發。
(選用) 使用 Firebase 本機模擬器套件設計原型並進行測試
在討論應用程式如何讀取即時資料庫及寫入資料之前,我們會先介紹一組工具,讓您用來設計原型及測試即時資料庫功能:Firebase 本機模擬器套件。如果您正在嘗試不同的資料模型、最佳化安全性規則,或想找出最符合成本效益的方式與後端互動,那麼即使不部署即時服務,也能在本機工作。
即時資料庫模擬器屬於本機模擬器套件的一部分,可讓應用程式與模擬資料庫內容和設定互動,並選擇性地與模擬專案資源 (函式、其他資料庫和安全性規則) 互動。
使用即時資料庫模擬器只需完成幾個步驟:
- 將一行程式碼新增至應用程式的測試設定,即可與模擬器連線。
- 從本機專案目錄的根目錄中執行
firebase emulators:start
。 - 照常透過即時資料庫平台 SDK 或即時資料庫 REST API,從應用程式的原型程式碼發出呼叫。
歡迎查看詳細的即時資料庫和 Cloud Functions 逐步操作說明。建議您也參閱「本機模擬器套件簡介」一文。
取得 DatabaseReference
如要從資料庫讀取或寫入資料,您需要 DatabaseReference
的執行個體:
Kotlin+KTX
private lateinit var database: DatabaseReference // ... database = Firebase.database.reference
Java
private DatabaseReference mDatabase; // ... mDatabase = FirebaseDatabase.getInstance().getReference();
寫入資料
基本寫入作業
針對基本寫入作業,您可以使用 setValue()
將資料儲存至指定的參照,取代該路徑中的所有現有資料。您可以使用這個方法:
- 與可用 JSON 類型對應的票證類型,如下所示:
String
Long
Double
Boolean
Map<String, Object>
List<Object>
- 如果定義該物件的類別具有不使用引數且擁有要指派屬性的公開 getter,請傳遞自訂 Java 物件。
如果使用的是 Java 物件,物件內容會以巢狀方式自動對應至子項位置。使用 Java 物件通常也可讓程式碼更易讀和維護更加容易。舉例來說,如果應用程式具備基本使用者個人資料,User
物件可能如下所示:
Kotlin+KTX
@IgnoreExtraProperties data class User(val username: String? = null, val email: String? = null) { // Null default values create a no-argument default constructor, which is needed // for deserialization from a DataSnapshot. }
Java
@IgnoreExtraProperties public class User { public String username; public String email; public User() { // Default constructor required for calls to DataSnapshot.getValue(User.class) } public User(String username, String email) { this.username = username; this.email = email; } }
您可以按照以下方式新增擁有 setValue()
的使用者:
Kotlin+KTX
fun writeNewUser(userId: String, name: String, email: String) { val user = User(name, email) database.child("users").child(userId).setValue(user) }
Java
public void writeNewUser(String userId, String name, String email) { User user = new User(name, email); mDatabase.child("users").child(userId).setValue(user); }
透過這種方式使用 setValue()
會覆寫指定位置的資料,包括任何子節點。不過,您仍可更新子項,不必重寫整個物件。如要允許使用者更新個人資料,可以按照下列方式更新使用者名稱:
Kotlin+KTX
database.child("users").child(userId).child("username").setValue(name)
Java
mDatabase.child("users").child(userId).child("username").setValue(name);
讀取資料
使用永久事件監聽器讀取資料
如要在路徑中讀取資料及監聽變更,請使用 addValueEventListener()
方法將 ValueEventListener
新增至 DatabaseReference
。
監聽器 | 事件回呼 | 一般用量 |
---|---|---|
ValueEventListener |
onDataChange() |
讀取及監聽路徑完整內容的異動。 |
您可以使用 onDataChange()
方法讀取特定路徑的內容靜態快照,因為這些快照在事件發生時就存在。此方法會在連接事件監聽器時觸發一次,並在每次資料 (包括子項) 變更時再次觸發。事件回呼會傳遞一個快照,當中包含該位置的所有資料,包括子項資料。如果沒有資料,則當您在其上呼叫 exists()
和 null
時,快照會傳回 false
。getValue()
以下範例將示範社交網誌應用程式,如何從資料庫中擷取貼文的詳細資料:
Kotlin+KTX
val postListener = object : ValueEventListener { override fun onDataChange(dataSnapshot: DataSnapshot) { // Get Post object and use the values to update the UI val post = dataSnapshot.getValue<Post>() // ... } override fun onCancelled(databaseError: DatabaseError) { // Getting Post failed, log a message Log.w(TAG, "loadPost:onCancelled", databaseError.toException()) } } postReference.addValueEventListener(postListener)
Java
ValueEventListener postListener = new ValueEventListener() { @Override public void onDataChange(DataSnapshot dataSnapshot) { // Get Post object and use the values to update the UI Post post = dataSnapshot.getValue(Post.class); // .. } @Override public void onCancelled(DatabaseError databaseError) { // Getting Post failed, log a message Log.w(TAG, "loadPost:onCancelled", databaseError.toException()); } }; mPostReference.addValueEventListener(postListener);
事件監聽器會收到 DataSnapshot
,其中包含事件發生時資料庫中指定的位置資料。對快照呼叫 getValue()
會傳回資料的 Java 物件表示法。如果位置上沒有任何資料,則呼叫 getValue()
會傳回 null
。
在這個範例中,ValueEventListener
也定義了讀取作業取消時會呼叫的 onCancelled()
方法。舉例來說,如果用戶端權限不足,無法讀取 Firebase 資料庫位置,系統就會取消讀取作業。此方法會傳遞 DatabaseError
物件,指出失敗的原因。
讀取資料一次
使用 get() 讀取一次
無論應用程式處於線上或離線狀態,SDK 都能用來管理與資料庫伺服器的互動。
一般來說,您應使用上述的 ValueEventListener
技術來讀取資料,以便從後端取得資料更新的通知。事件監聽器技術會減少用量和費用,並經過最佳化調整,可讓使用者在線上及離線時享有最佳體驗。
如果您只需要資料一次,可以使用 get()
取得資料庫中的資料快照。如果因任何原因 get()
無法傳回伺服器值,用戶端會探測本機儲存空間快取,如果還是找不到該值,就會傳回錯誤。
不必要的使用 get()
可能會增加頻寬用量,並導致效能遺失,可以如上所示使用即時事件監聽器來避免這種情況。
Kotlin+KTX
mDatabase.child("users").child(userId).get().addOnSuccessListener {
Log.i("firebase", "Got value ${it.value}")
}.addOnFailureListener{
Log.e("firebase", "Error getting data", it)
}
Java
mDatabase.child("users").child(userId).get().addOnCompleteListener(new OnCompleteListener<DataSnapshot>() {
@Override
public void onComplete(@NonNull Task<DataSnapshot> task) {
if (!task.isSuccessful()) {
Log.e("firebase", "Error getting data", task.getException());
}
else {
Log.d("firebase", String.valueOf(task.getResult().getValue()));
}
}
});
使用事件監聽器朗讀一次
在某些情況下,您可能會希望立即傳回本機快取中的值,而不是檢查伺服器上的更新值。在這類情況下,您可以使用 addListenerForSingleValueEvent
立即從本機磁碟快取取得資料。
如果資料只需載入一次、預期不會經常變更或需要主動監聽,這項功能就能派上用場。舉例來說,上述範例中的網誌應用程式會使用這個方法,在使用者開始撰寫新文章時載入個人資料。
更新或刪除資料
更新特定欄位
如要同時寫入節點的特定子項,而不覆寫其他子節點,請使用 updateChildren()
方法。
呼叫 updateChildren()
時,您可以指定索引鍵路徑,更新較低層級的子項值。如果資料儲存在多個位置以利擴充,您可以使用資料擴散傳遞功能更新該資料的所有執行個體。舉例來說,社交網誌應用程式可能擁有如下所示的 Post
類別:
Kotlin+KTX
@IgnoreExtraProperties data class Post( var uid: String? = "", var author: String? = "", var title: String? = "", var body: String? = "", var starCount: Int = 0, var stars: MutableMap<String, Boolean> = HashMap(), ) { @Exclude fun toMap(): Map<String, Any?> { return mapOf( "uid" to uid, "author" to author, "title" to title, "body" to body, "starCount" to starCount, "stars" to stars, ) } }
Java
@IgnoreExtraProperties public class Post { public String uid; public String author; public String title; public String body; public int starCount = 0; public Map<String, Boolean> stars = new HashMap<>(); public Post() { // Default constructor required for calls to DataSnapshot.getValue(Post.class) } public Post(String uid, String author, String title, String body) { this.uid = uid; this.author = author; this.title = title; this.body = body; } @Exclude public Map<String, Object> toMap() { HashMap<String, Object> result = new HashMap<>(); result.put("uid", uid); result.put("author", author); result.put("title", title); result.put("body", body); result.put("starCount", starCount); result.put("stars", stars); return result; } }
如要建立貼文,並同時將其更新為最近活動動態饋給和發布使用者的活動動態消息,網誌應用程式會使用以下程式碼:
Kotlin+KTX
private fun writeNewPost(userId: String, username: String, title: String, body: String) { // Create new post at /user-posts/$userid/$postid and at // /posts/$postid simultaneously val key = database.child("posts").push().key if (key == null) { Log.w(TAG, "Couldn't get push key for posts") return } val post = Post(userId, username, title, body) val postValues = post.toMap() val childUpdates = hashMapOf<String, Any>( "/posts/$key" to postValues, "/user-posts/$userId/$key" to postValues, ) database.updateChildren(childUpdates) }
Java
private void writeNewPost(String userId, String username, String title, String body) { // Create new post at /user-posts/$userid/$postid and at // /posts/$postid simultaneously String key = mDatabase.child("posts").push().getKey(); Post post = new Post(userId, username, title, body); Map<String, Object> postValues = post.toMap(); Map<String, Object> childUpdates = new HashMap<>(); childUpdates.put("/posts/" + key, postValues); childUpdates.put("/user-posts/" + userId + "/" + key, postValues); mDatabase.updateChildren(childUpdates); }
此範例使用 push()
在節點中建立貼文,其中包含 /posts/$postid
中所有使用者發布的貼文,並使用 getKey()
同時擷取金鑰。這樣就能在使用者的貼文中,運用此鍵在 /user-posts/$userid/$postid
建立第二個項目。
您可以使用這些路徑,只呼叫 updateChildren()
就能同時更新 JSON 樹狀結構中的多個位置,例如這個範例如何在兩個位置建立新貼文。以這種方式進行的同步更新是不可分割的:所有更新成功或所有更新都會失敗。
新增完成回呼
如要瞭解資料修訂時間,您可以新增完成事件監聽器。setValue()
和 updateChildren()
皆採用選用的完成事件監聽器。系統會在成功將寫入內容提交至資料庫時呼叫監聽器。如果呼叫失敗,事件監聽器會傳送錯誤物件,指出失敗的原因。
Kotlin+KTX
database.child("users").child(userId).setValue(user) .addOnSuccessListener { // Write was successful! // ... } .addOnFailureListener { // Write failed // ... }
Java
mDatabase.child("users").child(userId).setValue(user) .addOnSuccessListener(new OnSuccessListener<Void>() { @Override public void onSuccess(Void aVoid) { // Write was successful! // ... } }) .addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { // Write failed // ... } });
刪除資料
刪除資料最簡單的方法是對該資料位置的參照呼叫 removeValue()
。
您也可以指定 null
為其他寫入作業 (例如 setValue()
或 updateChildren()
) 的值來刪除。您可以將這項技術與 updateChildren()
搭配使用,在單一 API 呼叫中刪除多個子項。
卸離事件監聽器
如要移除回呼,請對 Firebase 資料庫參考資料呼叫 removeEventListener()
方法。
如果已在資料位置中多次新增事件監聽器,系統會針對每個事件多次呼叫該事件監聽器,因此您必須按照相同的次數卸離,才能完全移除事件監聽器。
對父項事件監聽器呼叫 removeEventListener()
不會自動移除在其子節點上註冊的事件監聽器;此外,您也必須在任何子項事件監聽器上呼叫 removeEventListener()
,才能移除回呼。
將資料儲存為交易
處理可能會因為並行修改而損毀的資料 (例如漸進式計數器) 時,您可以使用交易作業。您將為這項作業提供兩個引數:更新函式和選用的完成回呼。update 函式會將資料目前狀態當做引數,並傳回您要寫入的新所需狀態。如果其他用戶端在成功寫入新值之前寫入位置,系統會以新的目前值再次呼叫更新函式,並重試寫入。
舉例來說,在社交網誌應用程式範例中,您可以讓使用者為文章加上星號或移除星號,也可以追蹤貼文獲得的星星數量,如下所示:
Kotlin+KTX
private fun onStarClicked(postRef: DatabaseReference) { // ... postRef.runTransaction(object : Transaction.Handler { override fun doTransaction(mutableData: MutableData): Transaction.Result { val p = mutableData.getValue(Post::class.java) ?: return Transaction.success(mutableData) if (p.stars.containsKey(uid)) { // Unstar the post and remove self from stars p.starCount = p.starCount - 1 p.stars.remove(uid) } else { // Star the post and add self to stars p.starCount = p.starCount + 1 p.stars[uid] = true } // Set value and report transaction success mutableData.value = p return Transaction.success(mutableData) } override fun onComplete( databaseError: DatabaseError?, committed: Boolean, currentData: DataSnapshot?, ) { // Transaction completed Log.d(TAG, "postTransaction:onComplete:" + databaseError!!) } }) }
Java
private void onStarClicked(DatabaseReference postRef) { postRef.runTransaction(new Transaction.Handler() { @NonNull @Override public Transaction.Result doTransaction(@NonNull MutableData mutableData) { Post p = mutableData.getValue(Post.class); if (p == null) { return Transaction.success(mutableData); } if (p.stars.containsKey(getUid())) { // Unstar the post and remove self from stars p.starCount = p.starCount - 1; p.stars.remove(getUid()); } else { // Star the post and add self to stars p.starCount = p.starCount + 1; p.stars.put(getUid(), true); } // Set value and report transaction success mutableData.setValue(p); return Transaction.success(mutableData); } @Override public void onComplete(DatabaseError databaseError, boolean committed, DataSnapshot currentData) { // Transaction completed Log.d(TAG, "postTransaction:onComplete:" + databaseError); } }); }
如果多位使用者同時為同一則貼文加上星號,或用戶端取得過時的資料,使用交易可避免星號計數有誤。如果交易遭拒,伺服器會將目前的值傳回用戶端,用戶端會使用更新後的值再次執行交易。系統會重複此動作,直到接受交易或嘗試次數過多。
整體伺服器端增量
在上述用途中,我們要將兩個值寫入資料庫:為貼文加上星號/移除星號的使用者 ID,以及增加的星號數量。如果我們知道使用者已為貼文加上星號,則可使用不可分割的遞增作業,而非交易。
Kotlin+KTX
private fun onStarClicked(uid: String, key: String) { val updates: MutableMap<String, Any> = hashMapOf( "posts/$key/stars/$uid" to true, "posts/$key/starCount" to ServerValue.increment(1), "user-posts/$uid/$key/stars/$uid" to true, "user-posts/$uid/$key/starCount" to ServerValue.increment(1), ) database.updateChildren(updates) }
Java
private void onStarClicked(String uid, String key) { Map<String, Object> updates = new HashMap<>(); updates.put("posts/"+key+"/stars/"+uid, true); updates.put("posts/"+key+"/starCount", ServerValue.increment(1)); updates.put("user-posts/"+uid+"/"+key+"/stars/"+uid, true); updates.put("user-posts/"+uid+"/"+key+"/starCount", ServerValue.increment(1)); mDatabase.updateChildren(updates); }
此程式碼不會使用交易作業,所以在有衝突的更新時,不會自動重新執行。不過,由於增量作業會直接在資料庫伺服器上進行,因此不會發生衝突。
如要偵測並拒絕應用程式特定衝突 (例如使用者為先前已加上星號的貼文加上星號),則必須針對該用途編寫自訂安全性規則。
離線使用資料
如果用戶端的網路連線中斷,您的應用程式會繼續正常運作。
凡是連線至 Firebase 資料庫的用戶端,對於要使用事件監聽器的任何資料,或已標記為與伺服器保持同步的任何資料,其內部版本都會維持自己的內部版本。當讀取或寫入資料時,會先使用此本機版本的資料。接著,Firebase 用戶端會「盡可能」將這些資料與遠端資料庫伺服器和其他用戶端同步處理。
因此,在與伺服器進行任何互動之前,所有寫入資料庫的作業都會立即觸發本機事件。換句話說,無論網路延遲或連線狀況,應用程式都會持續回應。
重新建立連線後,應用程式會收到一組適當的事件,讓用戶端與目前的伺服器狀態同步,而不必編寫任何自訂程式碼。
我們會在進一步瞭解線上和離線功能中,進一步說明離線行為。