GET によるデータの読み取り
Firebase データベースからデータを読み取るには、Firebase データベースの URL エンドポイントに対して GET
リクエストを発行します。ここでは、前のセクションのブログサンプルを続けて使用して、ブログのすべての投稿データを読み取ります。
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
成功したリクエストは 200 OK
HTTP ステータス コードで示されます。レスポンスには、取得しようとしたデータが含まれています。
URI パラメータの追加
REST API は、Firebase データベースからデータを読み取るときにいくつかのクエリ パラメータを受け入れます。最もよく使用されるパラメータを次に示します。完全なリストについては、REST API リファレンスをご覧ください。
auth
auth
リクエスト パラメータを使用すると、Firebase Realtime Database セキュリティ ルールで保護されたデータにアクセスできます。このパラメータはすべての種類のリクエストでサポートされています。引数には、Firebase プロジェクトのユーザーに説明されているように、Firebase アプリのシークレット、認証トークンのいずれも使用できます。次の例では、auth
パラメータを指定して GET
リクエストを送信しています。ここで、CREDENTIAL
は、Firebase アプリのシークレットか、認証トークンのいずれかです。
curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'
print=pretty
を指定した場合、データは人が読める形式で返されます。
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
print=silent
を指定した場合、成功時に 204 No Content
が返されます。
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'
callback
ウェブブラウザからドメインをまたいだ REST 呼び出しを行うには、JavaScript コールバック関数で JSONP を使用してレスポンスをラップします。callback=
を追加して、返されたデータを REST API に、指定したコールバック関数でラップさせます。例:
<script> function gotData(data) { console.log(data); } </script> <script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">
shallow
これは大きなデータセットの全体をダウンロードすることなく操作できる、高度な機能です。これを使用するには、パラメータとして shallow=true
を追加します。追加すると、返されるデータの深度が制限されます。その場所にあるデータが JSON プリミティブ(文字列、数値、またはブール値)である場合は、その値を直接返します。その場所にあるデータ スナップショットが JSON オブジェクトの場合、各キーの値が true に切り捨てられます。たとえば、次のデータを使用するとします。
{ "message": { "user": { "name": "Chris" }, "body": "Hello!" } } // A request to /message.json?shallow=true // would return the following: { "user": true, "body": true } // A request to /message/body.json?shallow=true // would simply return: "Hello!"
次の curl
リクエストで試してみましょう。
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'
timeout
この値を使用して、サーバー側の読み取り時間を制限します。読み取りリクエストが割り当てられた時間内に終了しない場合、HTTP 400 エラーで終了します。これは、小さなデータ転送を想定しており、巨大なサブツリーの取得によって待ち時間が長くなることを防止したい場合に特に便利です。実際の読み取り時間は、データサイズとキャッシュによって異なります。
timeouts
を指定するには、3ms
、3s
、または 3min
の形式を使用し、数値と単位を指定します。指定しない場合、最大の timeout
である 15min
が適用されます。timeout
の値が正でないか、または最大値を超えている場合、リクエストは HTTP 400 エラーで拒否されます。次の例では、GET
リクエストに 10 秒の timeout
を指定しています。
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'
データのフィルタリング
さまざまな要素に基づいてデータをフィルタリングするクエリを構築できます。初めに、orderBy
パラメータを使用して、データをどのようにフィルタリングするかを指定します。次に、orderBy
を他の 5 つのパラメータ(limitToFirst
、limitToLast
、startAt
、endAt
、equalTo
)のいずれかと組み合わせます。
Firebase の担当者は皆、恐竜が大好きなので、恐竜に関するファクトのサンプル データベースのスニペットを使用して、データをフィルタリングする方法について説明します。
{ "lambeosaurus": { "height": 2.1, "length": 12.5, "weight": 5000 }, "stegosaurus": { "height": 4, "length": 9, "weight": 2500 } }
データは子キー、キー、値のいずれかでフィルタリングできます。クエリは、これらのいずれかのパラメータで始まり、パラメータ startAt
、endAt
、limitToFirst
、limitToLast
、equalTo
のうち 1 つ以上と組み合わせる必要があります。
指定した子キーでのフィルタリング
共通の子キーを orderBy
パラメータに渡すことにより、ノードをそのキーでフィルタリングできます。たとえば、体高が 3 以上の恐竜をすべて取得するには、次のようにします。
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'
フィルタに指定した子キーを持たないノードはすべて、値 null
として並べ替えられます。データが並べ替えられる仕組みの詳細については、データが並べ替えられる仕組みをご覧ください。
Firebase では、1 レベル下の子だけでなく、深くネストされた子で並べ替えるクエリもサポートされています。これは、次のような深くネストされたデータがある場合に役立ちます。
{ "lambeosaurus": { "dimensions": { "height" : 2.1, "length" : 12.5, "weight": 5000 } }, "stegosaurus": { "dimensions": { "height" : 4, "length" : 9, "weight" : 2500 } } }
ここで体高のクエリを実行するには、単一のキーではなく、オブジェクトへの完全なパスを使用します。
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'
クエリでフィルタリングに使用できるキーの数は一度に 1 つだけです。同じリクエストで orderBy
パラメータを複数回使用すると、エラーがスローされます。
キーによるフィルタリング
orderBy="$key"
パラメータを使用して、ノードをキーでフィルタリングすることもできます。次の例は、名前が文字 a
~m
で始まるすべての恐竜を取得します。
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'
値でのフィルタリング
orderBy="$value"
パラメータを使用して、ノードを子キーの値でフィルタリングできます。恐竜スポーツ競技会があり、そのスコアを次の形式で記録しているとします。
{ "scores": { "bruhathkayosaurus": 55, "lambeosaurus": 21, "linhenykus": 80, "pterodactyl": 93, "stegosaurus": 5, "triceratops": 22 } }
スコアが 50 以上のすべての恐竜を取得するには、次のリクエストを行います。
curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'
orderBy="$value"
の使用時に null
、ブール値、文字列、オブジェクト値が並べ替えられる仕組みについては、データが並べ替えられる仕組みをご覧ください。
複雑なフィルタリング
複数のパラメータを組み合わせると、より複雑なクエリを構築できます。
制限クエリ
limitToFirst
パラメータと limitToLast
パラメータは、データを受け取る対象の子の最大数を設定するために使用します。上限を 100 に設定した場合、最大 100 個の一致する子のみが取得されます。データベースに保存されているメッセージが 100 個未満の場合は、すべての子が取得されます。100 個を超えるメッセージが保存されている場合は、これらのメッセージのうち 100 個のみのデータが取得されます。limitToFirst
を使用した場合は並べ替えられたメッセージの最初の 100 個が取得され、limitToLast
を使用した場合は並べ替えられたメッセージの最後の 100 個が取得されます。
恐竜ファクト データベースと orderBy
を使用して、体重が重い上位 2 頭の恐竜を検索できます。
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'
同様に、limitToFirst
を使用して体高が低い上位 2 頭の恐竜を検索できます。
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'
また、制限クエリを orderBy="$value"
と併用することもできます。恐竜スポーツ競技会のスコアが高い上位 3 頭を含むリーダーボードを作成する場合は、次のようにします。
curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'
範囲クエリ
startAt
、endAt
、equalTo
を使用すると、クエリの開始点と終了点を任意に選択できます。たとえば、体高が 3 メートル以上のすべての恐竜を検索する場合は、orderBy
と startAt
を組み合わせます。
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'
endAt
を使用して、名前が辞書順で Pterodactyl よりも前に来るすべての恐竜を検索できます。
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'
startAt
と endAt
を組み合わせてクエリの開始点と終了点の両方を制限できます。次の例では、「b」で始まる名前を持つすべての恐竜を検索しています。
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'
範囲クエリは、データをページ分割する場合にも便利です。
すべてを組み合わせる
これらすべてのテクニックを組み合わせて複雑なクエリを作成できます。たとえば、体高がステゴサウルスと同じかそれよりも低いすべての恐竜の名前を検索できます。
MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"` curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"
データが並べ替えられる仕組み
このセクションでは、3 つのフィルタリング パラメータをそれぞれ使用したときにデータがどのように並べ替えられるかについて説明します。
orderBy
orderBy
で子キーの名前を指定すると、指定した子キーを含むデータが次のように並べ替えられます。
-
指定した子キーに
null
値を持つ子が最初に来ます。 -
指定した子キーの値が
false
である子が次に来ます。複数の子が値false
を持つ場合、キーで辞書順に並べ替えられます。 -
指定した子キーの値が
true
である子が次に来ます。複数の子がtrue
値を持つ場合、それらの子はキーの辞書順に並べ替えられます。 - 数値を持つ子が次に来ます。ただし、昇順に並べ替えられます。指定した子ノードに対して複数の子が同じ数値を持つ場合、それらの子はキーで並べ替えられます。
- 文字列は数値の後に来て、辞書順で昇順に並べ替えられます。指定した子ノードに対して複数の子が同じ値を持つ場合、それらの子はキーの辞書順に並べ替えられます。
- オブジェクトが最後に来て、キーで、辞書順かつ昇順に並べ替えられます。
orderBy="$key"
orderBy="$key"
パラメータを使用してデータを並べ替えると、返されるデータは次のようにキーの昇順に並べ替えられます。キーには文字列しか使用できないことに注意してください。
- 32 ビット整数として解析できるキーを持つ子が最初に来ます。これらの子は数値の昇順に並べ替えられます。
- 文字列値をキーとして持つ子が次に来ます。これらの子は辞書順の昇順に並べ替えられます。
orderBy="$value"
orderBy="$value"
パラメータを使用してデータを並べ替えると、子はその値で並べ替えられます。並べ替えの条件は、指定した子キーの値の代わりにノードの値が使用されるという点を除いて、子キーでデータを並べ替える場合と同じです。
orderBy="$priority"
orderBy="$priority"
パラメータを使用してデータを並べ替える場合、子の並べ替えは次のようにその優先度とキーによって決定されます。優先度の値には数値または文字列しか使用できないことに注意してください。
- 優先度を持たない子(デフォルト)が最初に来ます。
- 優先度として数値を持つ子が次に来ます。これらの子は優先度の数値の昇順に並べ替えられます。
- 優先度として文字列を持つ子が最後に来ます。これらの子は優先度の辞書順に並べ替えられます。
- 2 つの子が同じ優先度を持つ場合(ともに優先度を持たない場合も含む)、それらの子はキーで並べ替えられます。数値キーが最初に来て(数値で並べ替えられます)、残りのキーが続きます(辞書順で並べ替えられます)。
優先度の詳細については、API リファレンスをご覧ください。
REST API からのストリーミング
Firebase の REST エンドポイントは EventSource / Server-Sent Events プロトコルをサポートしているため、Firebase Database 内の単一の場所に簡単に変更をストリーミングできます。
ストリーミングを始めるには、次のことを行う必要があります。
- クライアントの Accept ヘッダーを
text/event-stream
に設定する - HTTP リダイレクト(特に HTTP ステータス コード 307)を尊重する
- Firebase データベースの場所の読み取りに権限が必要な場合は、
auth
クエリ パラメータを含める
これに対し、サーバーからは、リクエストされた URL にあるデータの状態が変化したときに名前付きイベントが送信されます。これらのメッセージの構造は EventSource プロトコルに準拠しています。
event: event name data: JSON encoded data payload
サーバーは、次のイベントを送信することがあります。
put | JSON エンコードされたデータは、2 つのキー(パスとデータ)を持つオブジェクトになります。 パスは、リクエスト URL からの相対的な場所を指し示します。 クライアントは、キャッシュ内のその場所にあるすべてのデータを、メッセージで与えられたデータに置き換える必要があります。 |
patch | JSON エンコードされたデータは、2 つのキー(パスとデータ)を持つオブジェクトになります。 パスは、リクエスト URL からの相対的な場所を指し示します。 クライアントは、データ内のそれぞれのキーについて、キャッシュ内の対応するキーを、メッセージ内のそのキーのデータに置き換える必要があります。 |
keep-alive | このイベントのデータは null です。アクションは必要ありません。 |
cancel | このイベントのデータは null です。 このイベントは、Firebase Realtime Database セキュリティ ルールにより、リクエストされた場所での読み取りが許可されなくなった場合に送信されます。 |
auth_revoked | このイベントのデータは、認証情報の有効期限が切れたことを示す文字列です。 このイベントは、指定された auth パラメータが有効でなくなったときに送信されます。 |
サーバーから送信されることがあるイベントのセットの例を次に示します。
// Set your entire cache to {"a": 1, "b": 2} event: put data: {"path": "/", "data": {"a": 1, "b": 2}} // Put the new data in your cache under the key 'c', so that the complete cache now looks like: // {"a": 1, "b": 2, "c": {"foo": true, "bar": false}} event: put data: {"path": "/c", "data": {"foo": true, "bar": false}} // For each key in the data, update (or add) the corresponding key in your cache at path /c, // for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}} event: patch data: {"path": "/c", "data": {"foo": 3, "baz": 4}}
Go を使用する場合は、Firebase REST および Streaming API に対するサードパーティのラッパーである Firego の使用を検討してください。