Firebase データベース REST API

APIの使用法

任意の Firebase Realtime Database URL を REST エンドポイントとして使用できます。 URL の末尾に.jsonを追加し、お気に入りの HTTPS クライアントからリクエストを送信するだけです。

HTTPS が必要です。 Firebase は暗号化されたトラフィックにのみ応答するため、データは安全に保たれます。

GET - データの読み取り

リアルタイム データベースからのデータは、エンドポイントに HTTP GETリクエストを発行することで読み取ることができます。次の例は、Realtime Database に以前に保存したユーザー名を取得する方法を示しています。

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

リクエストが成功したことは、 200 OK HTTP ステータス コードで示されます。応答には、 GETリクエストのパスに関連付けられたデータが含まれます。

{ "first": "Jack", "last": "Sparrow" }

PUT - データの書き込み

PUTリクエストを使用してデータを書き込むことができます。

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

リクエストが成功したことは、 200 OK HTTP ステータス コードで示されます。応答には、 PUTリクエストで指定されたデータが含まれます。

{ "first": "Jack", "last": "Sparrow" }

POST - データのプッシュ

JavaScript のpush()メソッド ( 「データのリスト」を参照) と同等の機能を実行するには、 POSTリクエストを発行します。

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

リクエストが成功したことは、 200 OK HTTP ステータス コードで示されます。応答には、 POSTリクエストで指定された新しいデータの子名が含まれます。

{ "name": "-INOQPH-aV_psbk3ZXEX" }

PATCH - データの更新

PATCHリクエストを使用すると、既存のデータを上書きせずに、ある場所の特定の子を更新できます。 PATCHで書き込まれるデータ内の名前付きの子は上書きされますが、省略された子は削除されません。これは、JavaScript のupdate()関数と同等です。

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

リクエストが成功したことは、 200 OK HTTP ステータス コードで示されます。応答には、 PATCHリクエストで指定されたデータが含まれます。

{ "last": "Jones" }

DELETE - データの削除

DELETEリクエストを使用してデータを削除できます。

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

DELETEリクエストが成功した場合は、JSON nullを含む応答を伴う200 OK HTTP ステータス コードによって示されます。

メソッドのオーバーライド

上記のメソッドをサポートしていないブラウザから REST 呼び出しを行う場合は、 POSTリクエストを作成し、 X-HTTP-Method-Overrideリクエスト ヘッダーを使用してメソッドを設定することにより、リクエスト メソッドをオーバーライドできます。

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

x-http-method-overrideクエリ パラメーターを使用することもできます。

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

条件付きリクエスト

条件付きリクエストは、SDK トランザクション操作に相当する REST であり、特定の条件に従ってデータを更新します。ワークフローの概要を参照し、REST の条件付きリクエストの詳細については、 「データの保存」を参照してください。

Firebase ETag

Firebase ETag は、指定された場所にある現在のデータの一意の識別子です。その場所でデータが変更されると、ETag も変更されます。 Firebase ETag は、最初の REST リクエスト (通常はGETですが、 PATCH以外のものでも構いません) のヘッダーで指定する必要があります。

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

一致する場合

if-match条件では、更新するデータの ETag 値を指定します。この条件を使用すると、Realtime Database は、書き込みリクエストで指定された ETag がデータベース内の既存データの ETag と一致するリクエストのみを完了します。 Firebase ETag リクエストを使用して、ある場所で ETag を取得します。 null の場所を上書きする場合は、 null_etagを使用します。

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

期待される応答

次の表は、ETag の一致に基づいて、各リクエスト タイプで予想される応答の概要を示しています。

リクエストの種類「X-Firebase-ETag: true」 ETag の一致
if_match: <matching etag>
ETagが一致しません
if_match: <no matching etag>
得る対応状況・内容200: "<データパス>" 400: 「...サポートされていません..」 400: 「...サポートされていません..」
追加されたヘッダーETag: <ETag_of_data>該当なし該当なし
置く対応状況・内容200: "<put_data>" 200: "<put_data>" 412: 「...ETag が一致しません..」
追加されたヘッダーETag: <ETag_of_put_data>該当なしETag: <データベース_ETag>
役職対応状況・内容200: "<ポストデータ>" 400: 「...サポートされていません..」 400: 「...サポートされていません..」
追加されたヘッダーETag: <ETag_of_post_data>該当なし該当なし
パッチ対応状況・内容400: 「...サポートされていません..」 400: 「...サポートされていません..」 400: 「...サポートされていません..」
追加されたヘッダー該当なし該当なし該当なし
消去対応状況・内容200: ヌル200: "<data_after_put>" 412: 「...ETag が一致しません..」
追加されたヘッダーETag: <ETag_of_null>該当なしETag: <データベース_ETag>

クエリパラメータ

Firebase Database REST API は、次のクエリ パラメータと値を受け入れます。

アクセストークン

すべてのリクエスト タイプでサポートされます。このリクエストを認証して、Firebase Realtime Database セキュリティ ルールによって保護されているデータへのアクセスを許可します。詳細については、 REST 認証のドキュメントを参照してください。

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

浅い

これは高度な機能で、すべてをダウンロードすることなく大規模なデータセットを操作できるように設計されています。ある場所で返されるデータの深さを制限するには、これをtrueに設定します。その場所のデータが JSON プリミティブ (文字列、数値、またはブール値) の場合、その値が単純に返されます。その場所のデータ スナップショットが JSON オブジェクトである場合、各キーの値はtrueに切り捨てられます。

引数RESTメソッド説明
浅い得る応答の深さを制限します。
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

shallow他のクエリ パラメータと混合することはできないことに注意してください。

印刷する

サーバーからの応答で返されたデータをフォーマットします。

引数RESTメソッド説明
かわいい取得、配置、投稿、パッチ、削除人間が読める形式でデータを表示します。
静けさ取得、挿入、投稿、パッチデータ書き込み時にサーバーからの出力を抑制するために使用されます。結果の応答は空になり、 204 No Content HTTP ステータス コードで示されます。
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

折り返し電話

GETのみでサポートされます。 Web ブラウザからドメイン間で REST 呼び出しを行うには、JSONP を使用して応答を JavaScript コールバック関数でラップします。 callback=を追加すると、REST API は返されたデータを指定したコールバック関数でラップします。

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

フォーマット

exportに設定すると、サーバーは応答内の優先度をエンコードします。

引数RESTメソッド説明
輸出得る応答に優先度情報を含めます。
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

ダウンロード

GETのみでサポートされます。 Web ブラウザからデータのファイル ダウンロードをトリガーしたい場合は、 download=を追加します。これにより、REST サービスは適切なヘッダーを追加し、ブラウザーがデータをファイルに保存することを認識できるようにします。

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

タイムアウト

これを使用して、サーバー側での読み取りにかかる時間を制限します。読み取りリクエストが割り当てられた時間内に完了しない場合、HTTP 400 エラーで終了します。これは、少量のデータ転送が予想され、潜在的に巨大なサブツリーをフェッチするのにあまり長く待ちたくない場合に特に便利です。実際の読み取り時間は、データ サイズとキャッシュによって異なる場合があります。

数値と単位を含む3ms3s 、または3minの形式を使用してtimeouts指定します。指定しない場合、最大15mintimeoutが適用されます。 timeoutが正でない場合、または最大値を超えている場合、リクエストは HTTP 400 エラーで拒否されます。

書き込みサイズ制限

書き込みサイズを制限するには、 writeSizeLimitクエリ パラメーターをtiny (target=1s)、 small (target=10s)、 medium (target=30s)、 large (target=60s) として指定できます。 Realtime Database は、各書き込みリクエストのサイズを見積もり、目標時間より長くかかるリクエストを中止します。

unlimitedを指定すると、例外的に大規模な書き込み (最大 256MB のペイロード) が許可され、データベースが現在の操作を処理している間、後続のリクエストがブロックされる可能性があります。書き込みはサーバーに到達するとキャンセルできません。

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

書き込みが大きすぎる場合は、次のエラー メッセージが表示されます。

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

さらに、Firebase CLI を使用して、データベース インスタンス全体のdefaultWriteSizeLimitを設定できます。この制限は、SDK からのリクエストを含むすべてのリクエストに適用されます。新しいデータベースは、 defaultWriteSizeLimit largeに設定して作成されます。 Firebase CLI を使用して、 defaultWriteSizeLimit tinyに設定することはできません。

firebase database:settings:set defaultWriteSizeLimit large

注文方法

詳細については、注文されたデータに関するガイドのセクションを参照してください。

limitToFirst、limitToLast、startAt、endAt、equalTo

詳細については、ガイドのデータのフィルタリングに関するセクションを参照してください。

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

Firebase REST エンドポイントは、EventSource / Server-Sent Eventsプロトコルをサポートしています。変更をリアルタイム データベース内の単一の場所にストリーミングするには、次のことを行う必要があります。

  • クライアントの Accept ヘッダーを"text/event-stream"に設定します。
  • HTTP リダイレクト、特に HTTP ステータス コード 307 を尊重する
  • 場所に読み取り権限が必要な場合は、 authパラメータを含める必要があります

その代わりに、サーバーは、要求された URL のデータの状態が変化すると、名前付きイベントを送信します。これらのメッセージの構造はEventSourceプロトコルに準拠しています。

event: event name
data: JSON encoded data payload

サーバーは次のイベントを送信する場合があります。

置く

JSON エンコードされたデータは、 pathdataという 2 つのキーを持つオブジェクトです。パスキーは、リクエスト URL からの相対的な場所を指します。クライアントは、キャッシュ内のその場所にあるすべてのデータをdataに置き換える必要があります。

パッチ

JSON エンコードされたデータは、 pathdataという 2 つのキーを持つオブジェクトです。パスキーは、リクエスト URL からの相対的な場所を指します。 data内のキーごとに、クライアントはキャッシュ内の対応するキーをメッセージ内のそのキーのデータに置き換える必要があります。

生き続ける

このイベントのデータはnullです。アクションは必要ありません。

キャンセル

予期しないエラーによっては、「cancel」イベントが送信され、接続が終了する場合があります。原因は、このイベントのために提供されたデータに記載されています。考えられる原因は次のとおりです。 1. Firebase Realtime Database セキュリティ ルールにより、要求された場所での読み取りが許可されなくなりました。この原因の「データ」の説明は「許可が拒否されました」です。 2. 書き込みによってイベント ストリーマーがトリガーされ、制限である 512 MB を超える大きな JSON ツリーが送信されました。この原因の「データ」は、「指定されたペイロードが大きすぎます。データの少ない場所を要求してください。」です。

認証取り消し

このイベントのデータは、資格情報の有効期限が切れたことを示す文字列です。このイベントは、指定された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}}

優先順位

場所の優先度情報は、 .priorityという名前の「仮想子」を使用して参照できます。 GETリクエストで優先度を読み取り、 PUTリクエストで優先度を書き込むことができます。たとえば、次のリクエストはusers/tomノードの優先順位を取得します。

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

優先度とデータを同時に書き込むには、 .priority子を JSON ペイロードに追加します。

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

優先度とプリミティブ値 (文字列など) を同時に書き込むには、 .priority子を追加し、プリミティブ値を.value子の中に入れることができます。

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

これにより、優先度1.0"Tom"が書き込まれます。優先順位は、JSON ペイロードの任意の深さに含めることができます。

サーバー値

単一の.svキーを持つオブジェクトであるプレースホルダー値を使用して、サーバー値を特定の場所に書き込むことができます。そのキーの値は、設定するサーバー値のタイプです。たとえば、次のリクエストは、ノードの値を Firebase サーバーの現在のタイムスタンプに設定します。

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

前述の「仮想子」パスを使用して、サーバー値を使用して優先順位を記述することもできます。

サポートされているサーバー値は次のとおりです。

サーバーの値
タイムスタンプUNIX エポックからの時間 (ミリ秒単位)。
インクリメント現在のデータベース値をアトミックにインクリメントする整数または浮動小数点デルタ値を{ ".sv": {"increment": <delta_value> }}の形式で指定します。データがまだ存在しない場合、更新によりデータがデルタ値に設定されます。デルタ値または既存のデータのいずれかが浮動小数点数である場合、両方の値は浮動小数点数として解釈され、バックエンドで double 値として適用されます。 double の算術演算と double 値の表現は、IEEE 754 のセマンティクスに従います。正/負の整数のオーバーフローがある場合、合計は double として計算されます。

Firebase Realtime Database セキュリティ ルールの取得と更新

REST API を使用して、Firebase プロジェクトのFirebase Realtime Database セキュリティ ルールを取得および更新することもできます。 Firebase プロジェクトのシークレットが必要になります。これは、Firebase プロジェクトの設定の[サービス アカウント]パネルにあります。

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

リクエストの認証

デフォルトでは、REST リクエストは認証なしで実行され、リアルタイム データベース ルールでデータへのパブリック読み取りまたは書き込みアクセスが許可されている場合にのみ成功します。リクエストを認証するには、 access_token=またはauth=クエリ パラメーターを使用します。

REST API を介した認証の詳細については、「REST リクエストの認証」を参照してください。

エラー状態

Firebase Database REST API は次のエラー コードを返す場合があります。

HTTPステータスコード
400不正な要求

次のエラー状態のいずれか:

  • PUTまたはPOSTデータを解析できません。
  • PUTまたはPOSTデータがありません。
  • リクエストが大きすぎるデータをPUTまたはPOSTとしました。
  • REST API 呼び出しには、パスの一部として無効な子名が含まれています。
  • REST API 呼び出しパスが長すぎます。
  • リクエストには、認識できないサーバー値が含まれています。
  • クエリのインデックスがFirebase Realtime Database セキュリティ ルールで定義されていません。
  • リクエストは、指定されたクエリ パラメーターの 1 つをサポートしていません。
  • このリクエストでは、クエリ パラメータと浅いGETリクエストが混合されます。
401不正

次のエラー状態のいずれか:

404お探しのページが見つかりませんでした指定されたリアルタイム データベースが見つかりませんでした。
500内部サーバーエラーサーバーがエラーを返しました。詳細については、エラー メッセージを参照してください。
503サービスは利用できません指定された Firebase Realtime Database は一時的に利用できません。これは、リクエストが試行されなかったことを意味します。
412前提条件が失敗しましたリクエストの if-match ヘッダーに指定された ETag 値がサーバーの値と一致しませんでした。