データの取得

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 Security Rules で保護されたデータにアクセスできます。このパラメータはすべての種類のリクエストでサポートされています。引数には、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 で子キーの名前を指定すると、指定した子キーを含むデータが次のように並べ替えられます。

  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 です。アクションは必要ありません。
キャンセル このイベントのデータは null です。
このイベントは、Firebase Realtime Database Security Rules により、リクエストされた場所での読み取りが許可されなくなった場合に送信されます。
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 の使用を検討してください。