在 Android 上讀取及寫入資料

本文說明讀取及寫入 Firebase 資料的基本概念。

Firebase 資料會寫入 FirebaseDatabase 參照，並透過將非同步事件監聽器附加至參照來擷取。監聽器會針對資料的初始狀態觸發一次，並且在資料變更時會再次觸發。

(選用) 使用 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 簡介。

取得 DatabaseReference

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

Kotlin+KTX

private lateinit var database: DatabaseReference
// ...
database = Firebase.database.reference
ReadAndWriteSnippets.kt

Java

private DatabaseReference mDatabase;
// ...
mDatabase = FirebaseDatabase.getInstance().getReference();
ReadAndWriteSnippets.java

寫入資料

基本寫入作業

針對基本寫入作業，您可以使用 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.
}
User.kt

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

}
User.java

您可以使用 setValue() 新增使用者，方法如下：

Kotlin+KTX 

fun writeNewUser(userId: String, name: String, email: String) {
    val user = User(name, email)

    database.child("users").child(userId).setValue(user)
}
ReadAndWriteSnippets.kt

Java 

public void writeNewUser(String userId, String name, String email) {
    User user = new User(name, email);

    mDatabase.child("users").child(userId).setValue(user);
}
ReadAndWriteSnippets.java

以這種方式使用 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() 時傳回 false，在您對其呼叫 getValue() 時傳回 null。

以下範例將示範社交網誌應用程式，如何從資料庫中擷取貼文的詳細資料：

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)
ReadAndWriteSnippets.kt

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);
ReadAndWriteSnippets.java

事件監聽器會收到 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,
        )
    }
}
Post.kt

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;
    }
}
Post.java

如要建立貼文並同時將其更新至最近活動動態消息和發布者使用者的活動動態消息，網誌應用程式會使用以下程式碼：

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)
}
ReadAndWriteSnippets.kt

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);
}
ReadAndWriteSnippets.java

這個範例會使用 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
        // ...
    }
ReadAndWriteSnippets.kt

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
                // ...
            }
        });
ReadAndWriteSnippets.java

刪除資料

刪除資料最簡單的方法，就是在資料位置的參照上呼叫 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!!)
        }
    })
}
ReadAndWriteSnippets.kt

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);
        }
    });
}
ReadAndWriteSnippets.java

如果有多位使用者同時為同一個貼文按下星號，或是用戶端有過時的資料，使用交易可避免星號計數出現錯誤。如果交易遭拒，伺服器會將目前的值傳回用戶端，用戶端會使用更新後的值再次執行交易。這項作業會重複執行，直到交易獲得接受或嘗試次數過多為止。

原子伺服器端遞增

在上述用途中，我們會將兩個值寫入資料庫：為貼文加上/移除星號的使用者 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)
}
ReadAndWriteSnippets.kt

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);
}
ReadAndWriteSnippets.java

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

如果您想偵測及拒絕應用程式專屬衝突，例如使用者為自己先前已收藏的貼文收藏，請為該用途編寫自訂安全性規則。

離線處理資料

如果用戶端的網路連線中斷，您的應用程式會繼續正常運作。

每個連線至 Firebase 資料庫的用戶端，都會維護其所使用的事件監聽器或標記為與伺服器保持同步的任何資料的內部版本。讀取或寫入資料時，系統會優先使用這個本機資料版本。接著，Firebase 用戶端會以「盡力」的方式，將該資料與遠端資料庫伺服器和其他用戶端同步。

因此，在與伺服器進行任何互動之前，所有寫入資料庫的作業都會立即觸發本機事件。換句話說，無論網路延遲或連線狀況，應用程式都會持續回應。

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

我們將在「進一步瞭解線上和離線功能」一文中進一步說明離線行為。

後續步驟