データの保存

PUT によるデータの書き込み

REST API による基本的な書き込み操作はPUTです。データの保存を示すために、投稿とユーザーを含むブログ アプリケーションを作成します。アプリケーションのすべてのデータは、Firebase データベース URL「https://docs-examples.firebaseio.com/fireblog」の「fireblog」のパスに保存されます。

まず、いくつかのユーザー データを Firebase データベースに保存することから始めましょう。各ユーザーを一意のユーザー名で保存し、氏名と生年月日も保存します。各ユーザーには一意のユーザー名があるため、ここではPOSTの代わりにPUTを使用するのが理にかなっています。これは、キーが既にあり、キーを作成する必要がないためです。

PUTを使用すると、文字列、数値、ブール値、配列、または任意の JSON オブジェクトを Firebase データベースに書き込むことができます。この場合、オブジェクトを渡します。

curl -X PUT -d '{
  "alanisawesome": {
    "name": "Alan Turing",
    "birthday": "June 23, 1912"
  }
}' 'https://docs-examples.firebaseio.com/fireblog/users.json'

JSON オブジェクトがデータベースに保存されると、オブジェクトのプロパティはネストされた方法で子の場所に自動的にマップされます。新しく作成されたノードに移動すると、「Alan Turing」という値が表示されます。データを子の場所に直接保存することもできます。

curl -X PUT -d '"Alan Turing"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/name.json'

curl -X PUT -d '"June 23, 1912"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/birthday.json'

上記の 2 つの例 (オブジェクトと同時に値を書き込み、子の場所に別々に書き込む) では、同じデータが Firebase データベースに保存されます。

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing"
    }
  }
}

成功したリクエストは200 OK HTTP ステータス コードで示され、レスポンスにはデータベースに書き込んだデータが含まれます。最初の例では、データを監視しているクライアントで 1 つのイベントのみがトリガーされますが、2 番目の例では 2 つのイベントがトリガーされます。ユーザー パスにデータが既に存在する場合、最初の方法ではデータが上書きされますが、2 番目の方法では個別の子ノードの値のみが変更され、他の子ノードは変更されないことに注意してください。 PUTは、JavaScript SDK のset()に相当します。

PATCH によるデータの更新

PATCHリクエストを使用すると、既存のデータを上書きすることなく、ある場所で特定の子を更新できます。 PATCHリクエストを使用して、Turing のニックネームを彼のユーザー データに追加しましょう。

curl -X PATCH -d '{
  "nickname": "Alan The Machine"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

上記のリクエストは、 nameやbirthdayの子供を削除せずに、 alanisawesomeオブジェクトにnicknameを書き込みます。代わりにここでPUTリクエストを発行した場合、 nameとbirthdayはリクエストに含まれていなかったため、削除されていたことに注意してください。 Firebase データベースのデータは次のようになります。

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    }
  }
}

成功した要求は200 OK HTTP ステータス コードで示され、応答にはデータベースに書き込まれた更新されたデータが含まれます。

Firebase はマルチパス更新もサポートしています。これは、 PATCHが Firebase データベースの複数の場所で同時に値を更新できるようになったことを意味します。これは、データの非正規化に役立つ強力な機能です。マルチパス更新を使用すると、Alan と Grace の両方に同時にニックネームを追加できます。

curl -X PATCH -d '{
  "alanisawesome/nickname": "Alan The Machine",
  "gracehopper/nickname": "Amazing Grace"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

この更新の後、アランとグレースのニックネームが追加されました。

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "date_of_birth": "December 9, 1906",
      "full_name": "Grace Hopper",
      "nickname": "Amazing Grace"
    }
  }
}

パスを含めてオブジェクトを書き込んでオブジェクトを更新しようとすると、動作が異なることに注意してください。 Grace と Alan を次のように更新しようとするとどうなるか見てみましょう。

curl -X PATCH -d '{
  "alanisawesome": {"nickname": "Alan The Machine"},
  "gracehopper": {"nickname": "Amazing Grace"}
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

これにより、異なる動作が発生します。つまり、 /fireblog/usersノード全体が上書きされます。

{
  "users": {
    "alanisawesome": {
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "nickname": "Amazing Grace"
    }
  }
}

条件付きリクエストによるデータの更新

1. ある場所で条件付きリクエストを実行するには、その場所の現在のデータの一意の識別子または ETag を取得します。その場所でデータが変更されると、ETag も変更されます。 PATCH以外の方法で ETag をリクエストできます。次の例では、 GET要求を使用しています。

   curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
   

   ヘッダーで ETag を具体的に呼び出すと、HTTP 応答で指定された場所の ETag が返されます。

   HTTP/1.1 200 OK
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   ETag: [ETAG_VALUE]
   Cache-Control: no-cache
   
   10 // Current value of the data at the specified location
   

2. 返された ETag を次のPUTまたはDELETE要求に含めて、その ETag 値と明確に一致するデータを更新します。この例に従って、カウンターを 11 に更新するか、最初にフェッチされた値 10 よりも 1 大きい値に更新し、値が一致しなくなった場合に要求を

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

   させるには、次のコードを使用します。 location は 10 のままで、 PUT要求の ETag が一致し、要求が成功し、データベースに 11 が書き込まれます。

   HTTP/1.1 200 OK
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   Cache-Control: no-cache
   
   11 // New value of the data at the specified location, written by the conditional request
   

   場所が ETag と一致しなくなった場合 (別のユーザーがデータベースに新しい値を書き込んだ場合に発生する可能性があります)、要求は場所に書き込まれずに失敗します。返される応答には、新しい値と ETag が含まれます。

   HTTP/1.1 412 Precondition Failed
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   ETag: [ETAG_VALUE]
   Cache-Control: no-cache
   
   12 // New value of the data at the specified location
   

3. 要求を再試行する場合は、新しい情報を使用してください。 Realtime Database は、失敗した条件付きリクエストを自動的に再試行しません。ただし、新しい値と ETag を使用して、失敗応答によって返された情報を使用して新しい条件付き要求を作成できます。

REST ベースの条件付きリクエストは、HTTP if-match標準を実装しています。ただし、次の点で標準とは異なります。

• 各 if-match リクエストに対して指定できる ETag 値は 1 つのみであり、複数指定することはできません。
• 標準では、すべてのリクエストで ETag を返すことが推奨されていますが、Realtime Database は、 X-Firebase-ETagヘッダーを含むリクエストで ETag のみを返します。これにより、標準リクエストの請求コストが削減されます。

条件付きリクエストは、通常の REST リクエストよりも遅くなる場合もあります。

データのリストを保存する

Firebase データベース参照に追加されたすべての子に対して一意のタイムスタンプ ベースのキーを生成するには、 POSTリクエストを送信します。各ユーザーは一意のユーザー名を持っているため、 usersパスでは独自のキーを定義することが理にかなっています。ただし、ユーザーがアプリにブログ投稿を追加すると、 POST要求を使用して、各ブログ投稿のキーを自動生成します。

curl -X POST -d '{
  "author": "alanisawesome",
  "title": "The Turing Machine"
}' 'https://docs-examples.firebaseio.com/fireblog/posts.json'

postsパスには次のデータが含まれるようになりました。

{
  "posts": {
    "-JSOpn9ZC54A4P4RoqVa": {
      "author": "alanisawesome",
      "title": "The Turing Machine"
    }
  }
}

POST要求を使用したため、キー-JSOpn9ZC54A4P4RoqVaが自動的に生成されたことに注意してください。成功したリクエストは200 OK HTTP ステータス コードで示され、レスポンスには追加された新しいデータのキーが含まれます。

{"name":"-JSOpn9ZC54A4P4RoqVa"}

データの削除

データベースからデータを削除するには、データを削除するパスの URL を指定してDELETEリクエストを送信します。次の例では、 usersパスから Alan を削除します。

curl -X DELETE \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

DELETEリクエストが成功すると、HTTP ステータス コード200 OKと JSON nullを含むレスポンスで示されます。

URI パラメータ

REST API は、データベースにデータを書き込むときに次の URI パラメーターを受け入れます。

認証

authリクエスト パラメータは、 Firebase Realtime Database Rulesによって保護されたデータへのアクセスを許可し、すべてのリクエスト タイプでサポートされています。引数は、Firebase アプリ シークレットまたは認証トークンのいずれかです。これについては、ユーザー認証セクションで説明します。次の例では、 authパラメータを使用してPOSTリクエストを送信します。ここで、 CREDENTIALは Firebase アプリ シークレットまたは認証トークンのいずれかです。

curl -X POST -d '{"Authenticated POST request"}' \
  'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

印刷する

printパラメーターを使用すると、データベースからの応答の形式を指定できます。リクエストにprint=prettyを追加すると、人間が読める形式でデータが返されます。 print=prettyは、 GET 、 PUT 、 POST 、 PATCH 、およびDELETEリクエストでサポートされています。

データの書き込み時にサーバーからの出力を抑制するには、リクエストにprint=silentを追加します。リクエストが成功した場合、結果のレスポンスは空になり、 204 No Content HTTP ステータス コードで示されます。 print=silentは、 GET 、 PUT 、 POST 、およびPATCHリクエストでサポートされています。

サーバー値の書き込み

サーバー値は、単一の".sv"キーを持つオブジェクトであるプレースホルダー値を使用して、ある場所に書き込むことができます。そのキーの値は、設定したいサーバー値のタイプです。たとえば、ユーザーの作成時にタイムスタンプを設定するには、次のようにします。

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://docs-examples.firebaseio.com/alanisawesome/createdAt.json'

"timestamp"は、サポートされている唯一のサーバー値であり、ミリ秒単位の UNIX エポックからの時間です。

書き込みパフォーマンスの向上

データベースに大量のデータを書き込んでいる場合は、 print=silentパラメータを使用して、書き込みパフォーマンスを改善し、帯域幅の使用を減らすことができます。通常の書き込み動作では、サーバーは書き込まれた JSON データで応答します。 print=silentが指定されている場合、サーバーはデータを受信するとすぐに接続を閉じ、帯域幅の使用量を減らします。

データベースに対して多くのリクエストを行う場合、HTTP ヘッダーでKeep-Aliveリクエストを送信することにより、HTTPS 接続を再利用できます。

エラー条件

REST API は、次の状況でエラー コードを返します。

データの保護

Firebase には、データのさまざまなノードへの読み取りおよび書き込みアクセス権を持つユーザーを定義できるセキュリティ言語があります。詳しくはRealtime Database のルールをご覧ください。

PUT によるデータの書き込み

REST API による基本的な書き込み操作はPUTです。データの保存を示すために、投稿とユーザーを含むブログ アプリケーションを作成します。アプリケーションのすべてのデータは、Firebase データベース URL「https://docs-examples.firebaseio.com/fireblog」の「fireblog」のパスに保存されます。

まず、いくつかのユーザー データを Firebase データベースに保存することから始めましょう。各ユーザーを一意のユーザー名で保存し、氏名と生年月日も保存します。各ユーザーには一意のユーザー名があるため、ここではPOSTの代わりにPUTを使用するのが理にかなっています。これは、キーが既にあり、キーを作成する必要がないためです。

PUTを使用すると、文字列、数値、ブール値、配列、または任意の JSON オブジェクトを Firebase データベースに書き込むことができます。この場合、オブジェクトを渡します。

curl -X PUT -d '{
  "alanisawesome": {
    "name": "Alan Turing",
    "birthday": "June 23, 1912"
  }
}' 'https://docs-examples.firebaseio.com/fireblog/users.json'

JSON オブジェクトがデータベースに保存されると、オブジェクトのプロパティはネストされた方法で子の場所に自動的にマップされます。新しく作成されたノードに移動すると、「Alan Turing」という値が表示されます。データを子の場所に直接保存することもできます。

curl -X PUT -d '"Alan Turing"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/name.json'

curl -X PUT -d '"June 23, 1912"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/birthday.json'

上記の 2 つの例 (オブジェクトと同時に値を書き込み、子の場所に別々に書き込む) では、同じデータが Firebase データベースに保存されます。

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing"
    }
  }
}

成功したリクエストは200 OK HTTP ステータス コードで示され、レスポンスにはデータベースに書き込んだデータが含まれます。最初の例では、データを監視しているクライアントで 1 つのイベントのみがトリガーされますが、2 番目の例では 2 つのイベントがトリガーされます。ユーザー パスにデータが既に存在する場合、最初の方法ではデータが上書きされますが、2 番目の方法では個別の子ノードの値のみが変更され、他の子ノードは変更されないことに注意してください。 PUTは、JavaScript SDK のset()に相当します。

PATCH によるデータの更新

PATCHリクエストを使用すると、既存のデータを上書きすることなく、ある場所で特定の子を更新できます。 PATCHリクエストを使用して、Turing のニックネームを彼のユーザー データに追加しましょう。

curl -X PATCH -d '{
  "nickname": "Alan The Machine"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

上記のリクエストは、 nameやbirthdayの子供を削除せずに、 alanisawesomeオブジェクトにnicknameを書き込みます。代わりにここでPUTリクエストを発行した場合、 nameとbirthdayはリクエストに含まれていなかったため、削除されていたことに注意してください。 Firebase データベースのデータは次のようになります。

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    }
  }
}

成功した要求は200 OK HTTP ステータス コードで示され、応答にはデータベースに書き込まれた更新されたデータが含まれます。

Firebase はマルチパス更新もサポートしています。これは、 PATCHが Firebase データベースの複数の場所で同時に値を更新できるようになったことを意味します。これは、データの非正規化に役立つ強力な機能です。マルチパス更新を使用すると、Alan と Grace の両方に同時にニックネームを追加できます。

curl -X PATCH -d '{
  "alanisawesome/nickname": "Alan The Machine",
  "gracehopper/nickname": "Amazing Grace"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

この更新の後、アランとグレースのニックネームが追加されました。

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "date_of_birth": "December 9, 1906",
      "full_name": "Grace Hopper",
      "nickname": "Amazing Grace"
    }
  }
}

パスを含めてオブジェクトを書き込んでオブジェクトを更新しようとすると、動作が異なることに注意してください。 Grace と Alan を次のように更新しようとするとどうなるか見てみましょう。

curl -X PATCH -d '{
  "alanisawesome": {"nickname": "Alan The Machine"},
  "gracehopper": {"nickname": "Amazing Grace"}
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

これにより、異なる動作が発生します。つまり、 /fireblog/usersノード全体が上書きされます。

{
  "users": {
    "alanisawesome": {
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "nickname": "Amazing Grace"
    }
  }
}

条件付きリクエストによるデータの更新

1. ある場所で条件付きリクエストを実行するには、その場所の現在のデータの一意の識別子または ETag を取得します。その場所でデータが変更されると、ETag も変更されます。 PATCH以外の方法で ETag をリクエストできます。次の例では、 GET要求を使用しています。

   curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
   

   ヘッダーで ETag を具体的に呼び出すと、HTTP 応答で指定された場所の ETag が返されます。

   HTTP/1.1 200 OK
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   ETag: [ETAG_VALUE]
   Cache-Control: no-cache
   
   10 // Current value of the data at the specified location
   

2. 返された ETag を次のPUTまたはDELETE要求に含めて、その ETag 値と明確に一致するデータを更新します。この例に従って、カウンターを 11 に更新するか、最初にフェッチされた値 10 よりも 1 大きい値に更新し、値が一致しなくなった場合に要求を

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

   させるには、次のコードを使用します。 location は 10 のままで、 PUT要求の ETag が一致し、要求が成功し、データベースに 11 が書き込まれます。

   HTTP/1.1 200 OK
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   Cache-Control: no-cache
   
   11 // New value of the data at the specified location, written by the conditional request
   

   場所が ETag と一致しなくなった場合 (別のユーザーがデータベースに新しい値を書き込んだ場合に発生する可能性があります)、要求は場所に書き込まれずに失敗します。返される応答には、新しい値と ETag が含まれます。

   HTTP/1.1 412 Precondition Failed
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   ETag: [ETAG_VALUE]
   Cache-Control: no-cache
   
   12 // New value of the data at the specified location
   

3. 要求を再試行する場合は、新しい情報を使用してください。 Realtime Database は、失敗した条件付きリクエストを自動的に再試行しません。ただし、新しい値と ETag を使用して、失敗応答によって返された情報を使用して新しい条件付き要求を作成できます。

REST ベースの条件付きリクエストは、HTTP if-match標準を実装しています。ただし、次の点で標準とは異なります。

• 各 if-match リクエストに対して指定できる ETag 値は 1 つのみであり、複数指定することはできません。
• 標準では、すべてのリクエストで ETag を返すことが推奨されていますが、Realtime Database は、 X-Firebase-ETagヘッダーを含むリクエストで ETag のみを返します。これにより、標準リクエストの請求コストが削減されます。

条件付きリクエストは、通常の REST リクエストよりも遅くなる場合もあります。

データのリストを保存する

Firebase データベース参照に追加されたすべての子に対して一意のタイムスタンプ ベースのキーを生成するには、 POSTリクエストを送信します。各ユーザーは一意のユーザー名を持っているため、 usersパスでは独自のキーを定義することが理にかなっています。ただし、ユーザーがアプリにブログ投稿を追加すると、 POST要求を使用して、各ブログ投稿のキーを自動生成します。

curl -X POST -d '{
  "author": "alanisawesome",
  "title": "The Turing Machine"
}' 'https://docs-examples.firebaseio.com/fireblog/posts.json'

postsパスには次のデータが含まれるようになりました。

{
  "posts": {
    "-JSOpn9ZC54A4P4RoqVa": {
      "author": "alanisawesome",
      "title": "The Turing Machine"
    }
  }
}

POST要求を使用したため、キー-JSOpn9ZC54A4P4RoqVaが自動的に生成されたことに注意してください。成功したリクエストは200 OK HTTP ステータス コードで示され、レスポンスには追加された新しいデータのキーが含まれます。

{"name":"-JSOpn9ZC54A4P4RoqVa"}

データの削除

データベースからデータを削除するには、データを削除するパスの URL を指定してDELETEリクエストを送信します。次の例では、 usersパスから Alan を削除します。

curl -X DELETE \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

DELETEリクエストが成功すると、HTTP ステータス コード200 OKと JSON nullを含むレスポンスで示されます。

URI パラメータ

REST API は、データベースにデータを書き込むときに次の URI パラメーターを受け入れます。

認証

authリクエスト パラメータは、 Firebase Realtime Database Rulesによって保護されたデータへのアクセスを許可し、すべてのリクエスト タイプでサポートされています。引数は、Firebase アプリ シークレットまたは認証トークンのいずれかです。これについては、ユーザー認証セクションで説明します。次の例では、 authパラメータを使用してPOSTリクエストを送信します。ここで、 CREDENTIALは Firebase アプリ シークレットまたは認証トークンのいずれかです。

curl -X POST -d '{"Authenticated POST request"}' \
  'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

印刷する

printパラメーターを使用すると、データベースからの応答の形式を指定できます。リクエストにprint=prettyを追加すると、人間が読める形式でデータが返されます。 print=prettyは、 GET 、 PUT 、 POST 、 PATCH 、およびDELETEリクエストでサポートされています。

データの書き込み時にサーバーからの出力を抑制するには、リクエストにprint=silentを追加します。リクエストが成功した場合、結果のレスポンスは空になり、 204 No Content HTTP ステータス コードで示されます。 print=silentは、 GET 、 PUT 、 POST 、およびPATCHリクエストでサポートされています。

サーバー値の書き込み

サーバー値は、単一の".sv"キーを持つオブジェクトであるプレースホルダー値を使用して、ある場所に書き込むことができます。そのキーの値は、設定したいサーバー値のタイプです。たとえば、ユーザーの作成時にタイムスタンプを設定するには、次のようにします。

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://docs-examples.firebaseio.com/alanisawesome/createdAt.json'

"timestamp"は、サポートされている唯一のサーバー値であり、ミリ秒単位の UNIX エポックからの時間です。

書き込みパフォーマンスの向上

データベースに大量のデータを書き込んでいる場合は、 print=silentパラメータを使用して、書き込みパフォーマンスを改善し、帯域幅の使用を減らすことができます。通常の書き込み動作では、サーバーは書き込まれた JSON データで応答します。 print=silentが指定されている場合、サーバーはデータを受信するとすぐに接続を閉じ、帯域幅の使用量を減らします。

データベースに対して多くのリクエストを行う場合、HTTP ヘッダーでKeep-Aliveリクエストを送信することにより、HTTPS 接続を再利用できます。

エラー条件

REST API は、次の状況でエラー コードを返します。

データの保護

Firebase には、データのさまざまなノードへの読み取りおよび書き込みアクセス権を持つユーザーを定義できるセキュリティ言語があります。詳しくはRealtime Database のルールをご覧ください。