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 エラーで終了します。これは、少量のデータ転送が予想され、潜在的に巨大なサブツリーをフェッチするのにあまり長く待ちたくない場合に特に便利です。実際の読み取り時間は、データ サイズとキャッシュによって異なる場合があります。
数値と単位を含む3ms
、 3s
、または3min
の形式を使用してtimeouts
指定します。指定しない場合、最大15min
のtimeout
が適用されます。 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 エンコードされたデータは、 pathとdataという 2 つのキーを持つオブジェクトです。パスキーは、リクエスト URL からの相対的な場所を指します。クライアントは、キャッシュ内のその場所にあるすべてのデータをdataに置き換える必要があります。
パッチ
JSON エンコードされたデータは、 pathとdataという 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不正な要求 | 次のエラー状態のいずれか:
|
401不正 | 次のエラー状態のいずれか:
|
404お探しのページが見つかりませんでした | 指定されたリアルタイム データベースが見つかりませんでした。 |
500内部サーバーエラー | サーバーがエラーを返しました。詳細については、エラー メッセージを参照してください。 |
503サービスは利用できません | 指定された Firebase Realtime Database は一時的に利用できません。これは、リクエストが試行されなかったことを意味します。 |
412前提条件が失敗しました | リクエストの if-match ヘッダーに指定された ETag 値がサーバーの値と一致しませんでした。 |
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2024-03-20 UTC。