在Android上讀取和寫入數據

本文檔涵蓋了讀取和寫入 Firebase 資料的基礎知識。

Firebase 資料寫入FirebaseDatabase引用，並透過將非同步偵聽器附加到該引用來檢索。偵聽器在資料初始狀態時觸發一次，並在資料變更時再次觸發。

（可選）使用 Firebase 本機模擬器套件進行原型設計和測試

在討論您的應用程式如何讀取和寫入即時資料庫之前，我們先介紹一組可用於原型設計和測試即時資料庫功能的工具：Firebase Local Emulator Suite。如果您正在嘗試不同的資料模型、優化安全規則或努力尋找與後端互動的最具成本效益的方式，那麼能夠在本地工作而不部署即時服務可能是一個好主意。

即時資料庫模擬器是本機模擬器套件的一部分，它使您的應用程式能夠與模擬資料庫內容和配置以及可選的模擬專案資源（函數、其他資料庫和安全規則）進行互動。

使用即時資料庫模擬器只需幾個步驟：

  1. 將一行程式碼新增至應用程式的測試配置以連接到模擬器。
  2. 從本地專案目錄的根目錄中，運行firebase emulators:start 。
  3. 像往常一樣使用即時資料庫平台 SDK 或使用即時資料庫 REST API 從應用程式的原型程式碼進行呼叫。

提供了涉及即時資料庫和雲端功能的詳細演練。您還應該看看本地仿真器套件的介紹。

取得資料庫參考

若要從資料庫讀取或寫入數據，您需要一個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>
  • 傳遞自訂 Java 對象，如果定義它的類別具有不帶參數的預設建構函數，並且具有用於指派屬性的公共 getter。

如果您使用 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()以刪除回呼。

將資料儲存為交易

當處理可能被並發修改損壞的資料（例如增量計數器）時，您可以使用交易操作。您為此操作提供兩個參數：一個更新函數和一個可選的完成回呼。更新函數將資料的目前狀態作為參數，並傳回您想要寫入的新的所需狀態。如果在成功寫入新值之前另一個用戶端寫入該位置，則會使用新的目前值再次呼叫您的更新函數，並重試寫入。

例如，在範例社交部落格應用程式中，您可以允許用戶對貼文加註星標和取消星標，並追蹤貼文收到的星數，如下所示：

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 用戶端會「盡力」將該資料與遠端資料庫伺服器和其他用戶端同步。

因此，在與伺服器進行任何互動之前，對資料庫的所有寫入都會立即觸發本地事件。這意味著無論網路延遲或連接如何，您的應用程式都保持回應。

重新建立連線後，您的應用程式會收到適當的事件集，以便用戶端與目前伺服器狀態同步，而無需編寫任何自訂程式碼。

我們將在了解有關線上和離線功能的更多資訊中詳細討論離線行為。

下一步