データの取得

GET によるデータの読み取り

Firebase データベースからデータを読み取るには、Firebase データベースの URL エンドポイントに対して GET リクエストを発行します。ここでは、前のセクションのブログサンプルを続けて使用して、ブログのすべての投稿データを読み取ります。

curl 'https://docs-examples.firebaseio.com/rest/saving-data/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/rest/saving-data/auth-example.json?auth=CREDENTIAL'

print

print=pretty を指定した場合、データは人が読める形式で返されます。

curl 'https://samplechat.firebaseio-demo.com/users/jack/name.json?print=pretty'

print=silent を指定した場合、成功時に 204 No Content が返されます。

curl 'https://samplechat.firebaseio-demo.com/users/jack/name.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/rest/saving-data/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'

データのフィルタリング

さまざまな要素に基づいてデータをフィルタリングするクエリを構築できます。初めに、orderBy パラメータを使用して、データをどのようにフィルタリングするかを指定します。 次に、orderBy を他の 5 つのパラメータ(limitToFirstlimitToLaststartAtendAtequalTo)のいずれかと組み合わせます。

Firebase の担当者は皆、恐竜が大好きなので、恐竜に関するファクトのデータベースを使用してデータをフィルタリングする方法について説明します。次に、恐竜データのスニペットを示します。

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

データは、3 つの方法(子キーキー)のいずれかでフィルタリングできます。クエリは、これらのいずれかのパラメータで始まり、パラメータ startAtendAtlimitToFirstlimitToLastequalTo のうち 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" パラメータを使用してそのキーでフィルタリングすることもできます。次の例では、名前が文字 am で始まるすべての恐竜を取得しています。

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 個についてのみデータを受け取ります。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'

範囲クエリ

startAtendAtequalTo を使用すると、クエリ用に任意の始点と終点を選択できます。たとえば、体高が 3 メートル以上のすべての恐竜を検索する場合は、orderBystartAt を組み合わせることができます。

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'

startAtendAt を組み合わせてクエリの両端を制限できます。 次の例では、「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 を子キーとともに使用すると、指定した子キーを含んでいるデータが次のように並べ替えられます。

  1. 指定した子キーに null 値を持つ子が最初に来ます。
  2. 指定した子キーに false 値を持つ子が次に来ます。複数の子が値 false を持つ場合、キーで辞書順に並べ替えられます。
  3. 指定した子キーに true 値を持つ子が次に来ます。複数の子が値 true を持つ場合、キーで辞書順に並べ替えられます。
  4. 数値を持つ子が次に来ます。ただし、昇順に並べ替えられます。複数の子が指定した子ノードに同じ数値を持つ場合、キーで並べ替えられます。
  5. 文字列は数値の後に来て、辞書順で昇順に並べ替えられます。複数の子が指定した子ノードに同じ値を持つ場合、キーで辞書順に並べ替えられます。
  6. オブジェクトが最後に来て、キーで、辞書順で昇順に並べ替えられます。
フィルタリングされた結果は、並べ替えられずに返されます。データの順序が重要な場合は、結果が Firebase から返された後、アプリケーションで結果を並べ替える必要があります。

orderBy="$key"

orderBy="$key" パラメータを使用してデータを並べ替えると、次のようにキーで昇順にデータが返されます。キーには文字列しか使用できないことに注意してください。

  1. 32 ビット整数として解析できるキーを持つ子が最初に来ます。ただし、昇順に並べ替えられます。
  2. 文字列値をキーとして持つ子が次に来ます。ただし、辞書順で昇順に並べ替えられます。

orderBy="$value"

orderBy="$value" パラメータを使用してデータを並べ替えると、子はその値で並べ替えられます。並べ替えの条件は、指定した子キーの値の代わりにノードの値が使用されるという点を除いて、子キーでデータを並べ替える場合と同じです。

orderBy="$priority"

orderBy="$priority" パラメータを使用してデータを並べ替える場合は、子の並べ替えは次のようにその優先度とキーによって決定されます。優先度の値には数値または文字列しか使用できないことに注意してください。

  1. 優先度を持たない子(デフォルト)が最初に来ます。
  2. 優先度として数値を持つ子が次に来ます。該当する子は優先度の数値で昇順に並べ替えられます。
  3. 優先度として文字列を持つ子が最後に来ます。該当する子は優先度で辞書順に並べ替えられます。
  4. 2 つの子が同じ優先度を持つ場合(ともに優先度を持たない場合も含む)、キーで並べ替えられます。 数値キーが最初に来て(数値で並べ替えられます)、残りのキーが続きます(辞書順で並べ替えられます)。

優先度の詳細については、API リファレンスをご覧ください。

REST API からのストリーミング

Firebase の REST エンドポイントは EventSource / Server-Sent Events プロトコルをサポートしているため、Firebase Database 内の単一の場所に簡単に変更をストリーミングできます。

ストリーミングを始めるには、次のことを行う必要があります。

  1. クライアントの Accept ヘッダーを text/event-stream に設定する
  2. HTTP リダイレクト(特に HTTP ステータス コード 307)を尊重する
  3. 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 を検討してください。

フィードバックを送信...