このドキュメントでは、Firebase データの読み取りと書き込みの基本について説明します。
Firebase データは FirebaseDatabase 参照に書き込まれ、取得する際にはその参照に非同期リスナーをアタッチします。リスナーはデータの初期状態で 1 回トリガーされます。さらに、データが変更されると、そのたびに再度トリガーされます。
（省略可）Firebase Local Emulator Suite でプロトタイピングとテストを行う
アプリが Realtime Database との間でどのようにデータを読み取り / 書き込みするのかを説明する前に、Realtime Database の機能のプロトタイピングとテストに使用できるツールである Firebase Local Emulator Suite をご紹介します。異なるデータモデルの試行や、セキュリティ ルールの最適化、あるいはバックエンドとのやり取りで費用対効果の高い方法の検出を行う場合は、ライブサービスをデプロイせずにローカルで作業できるようにすると、大きなメリットが得られます。
Realtime Database エミュレータは Local Emulator Suite の一部であり、これを使用すると、アプリはエミュレートしたデータベースのコンテンツや構成とやり取りできるほか、エミュレートされたプロジェクトのリソース（関数、他のデータベース、セキュリティ ルール）とも任意でやり取りできます。
いくつかの手順を実施するだけで、Realtime Database エミュレータを使用できます。
- アプリのテスト構成にコード行を追加して、エミュレータに接続します。
- ローカル プロジェクトのディレクトリのルートから、
firebase emulators:startを実行します。 - 通常どおり 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
Java
private DatabaseReference mDatabase; // ... mDatabase = FirebaseDatabase.getInstance().getReference();
データを書き込む
基本的な書き込みオペレーション
基本的な書き込みオペレーションは、setValue() を使用してデータを特定の参照に保存できます。そのパスにある既存のデータが置換されます。このメソッドを使用して行える操作は次のとおりです。
- 次のような、使用可能な JSON 型に対応する型を渡します。
StringLongDoubleBooleanMap<String, Object>List<Object>
- カスタム 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() をこの方法で使用すると、特定の場所にあるデータ（子ノードも含む）が上書きされます。ただし、オブジェクト全体を書き換えずに子を更新することもできます。ユーザーに自分のプロフィールの更新を許可する場合、次のように username を更新できます。
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() メソッドを使用して、特定のパスにあるコンテンツの静的スナップショットを、イベントの発生時に存在していたとおりに読み取ることができます。このメソッドはリスナーがアタッチされたときに 1 回トリガーされます。さらに、データ（子も含む）が変更されると、そのたびに再びトリガーされます。イベントのコールバックには、その場所にあるすべてのデータ（子のデータも含む）を含んでいるスナップショットが渡されます。データが存在しない場合、スナップショットから返されるのは、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)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 オブジェクトが渡されます。
データの 1 回読み取り
get() を使用して 1 回読み取る
SDK は、アプリがオンラインかオフラインかに関係なく、データベース サーバーとのやり取りを管理するように設計されています。
通常は、データを読み取り、バックエンドからデータの更新に関する通知を受け取るには、上記の ValueEventListener 手法を使用する必要があります。リスナーの手法は、使用量と課金を削減し、オンラインとオフラインのどちらでも最高のユーザー エクスペリエンスを実現できるよう最適化されています。
データが 1 回だけ必要な場合は、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()));
}
}
});
リスナーを使用して 1 回読み取る
更新された値をサーバーで確認するのではなく、値をローカル キャッシュから直ちに返したい場合があります。そのような場合は、addListenerForSingleValueEvent を使用してローカル ディスク キャッシュから直ちにデータを取得できます。
これは 1 回読み込む必要があるだけで頻繁な変更やアクティブなリッスンを行うことは想定していないデータに対して有用です。たとえば、前の例にあるブログアプリでは、このメソッドを使用して、ユーザーが新しい投稿を作成し始めたときにユーザーのプロフィールを読み込んでいます。
データの更新または削除
特定のフィールドを更新する
他の子ノードを上書きすることなく、ノードの特定の複数の子に同時に書き込むには、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() を 1 回呼び出すだけで JSON ツリー内の複数の場所に対して更新を同時に実行できます。この方法による同時更新はアトミック（不可分）です。つまり、すべての更新が成功するか、すべての更新が失敗するかのどちらかです。
完了コールバックを追加する
データがいつ commit されたのかを把握する場合は、完了リスナーを追加します。setValue() と updateChildren() はどちらも、完了リスナーをオプションとして取ります。このリスナーは、書き込みがデータベースに commit されたときに呼び出されます。呼び出しに失敗すると、障害が発生した理由を示すエラー オブジェクトがリスナーに渡されます。
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() を呼び出すことです。
また、他の書き込みオペレーション（setValue() や updateChildren() など）の値として null を指定する方法でも削除できます。この方法と updateChildren() を併用すると、API を 1 回呼び出すだけで複数の子を削除できます。
リスナーのデタッチ
コールバックを削除するには、Firebase データベース参照の removeEventListener() メソッドを呼び出します。
1 つのデータの場所にリスナーが複数回追加されると、そのリスナーはイベントごとに複数回呼び出されるため、そのリスナーを完全に削除するには同じ回数だけデタッチする必要があります。
親リスナーの removeEventListener() を呼び出しても、その子ノードに登録されているリスナーが自動的に削除されるわけではありません。また、コールバックを削除するために子リスナーの removeEventListener() も呼び出す必要があります。
トランザクションとしてのデータの保存
増分カウンタなど、同時変更によって破損する可能性があるデータを操作する場合は、トランザクション オペレーションを使用します。このオペレーションには、2 つの引数（update 関数とオプションの完了コールバック）を与えます。update 関数はデータの現在の状態を引数として取り、書き込みたい新しい状態を返します。新しい値が正常に書き込まれる前に別のクライアントがその場所に書き込んだ場合、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);
}
});
}トランザクションを使用することで、複数のユーザーが同じ投稿にスターを同時に付けた場合や、クライアントのデータが古くなった場合でも、スターの数が不正確になることを防ぎます。トランザクションが拒否された場合、サーバーは現在の値をクライアントに返します。クライアントは更新された値でトランザクションを再度実行します。この処理は、トランザクションが受け入れられるか、試行の回数が上限に達するまで繰り返されます。
サーバーサイドのアトミックなインクリメント
上のユースケースでは 2 つの値をデータベースに書き込みます。投稿にスターを付ける / スターを外すユーザーの 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 クライアントは、「ベスト エフォート」ベースでそのデータをリモート データベース サーバーや他のクライアントと同期します。
その結果、データベースへの書き込み処理はすべて、サーバーとのやり取りの直前にローカル イベントをトリガーします。つまり、ネットワークのレイテンシや接続に関係なく、アプリの応答性の応答性が維持されます。
接続が再確立されると、アプリは適切な一連のイベントを受け取り、クライアントが現在のサーバー状態と同期されます。この処理のためにカスタムコードを記述する必要はありません。
オフラインの動作については、オンライン機能とオフラインの機能の詳細で説明します。