Firebase Summit のすべての発表内容に目を通し、Firebase を活用してアプリ開発を加速し、自信を持ってアプリを実行できる方法をご確認ください。 詳細

Cloud Firestore RESTAPIを使用する

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Cloud Firestore を使用する最も簡単な方法はネイティブ クライアント ライブラリの 1 つを使用することですが、REST API を直接呼び出すと便利な場合もあります。

REST API は、次のユース ケースに役立ちます。

  • 完全なクライアント ライブラリを実行することができない、モノのインターネット (IoT) デバイスなど、リソースに制約のある環境から Cloud Firestore にアクセスする。
  • データベース管理の自動化または詳細なデータベース メタデータの取得。

gRPC 対応言語を使用している場合は、REST API ではなくRPC APIの使用を検討してください。

認証と認可

認証のために、Cloud Firestore REST API はFirebase Authentication ID トークンまたはGoogle Identity OAuth 2.0トークンを受け入れます。提供するトークンは、リクエストの承認に影響します。

  • Firebase ID トークンを使用して、アプリケーションのユーザーからのリクエストを認証します。これらのリクエストに対して、Cloud Firestore はCloud Firestore セキュリティ ルールを使用して、リクエストが承認されているかどうかを判断します。

  • Google Identity OAuth 2.0 トークンとサービス アカウントを使用して、データベース管理のリクエストなど、アプリケーションからのリクエストを認証します。これらのリクエストに対して、Cloud Firestore はIdentity and Access Management (IAM)を使用して、リクエストが承認されているかどうかを判断します。

Firebase ID トークンの操作

Firebase ID トークンは次の 2 つの方法で取得できます。

ユーザーの Firebase ID トークンを取得することで、ユーザーに代わってリクエストを行うことができます。

Firebase ID トークンで認証されたリクエストと認証されていないリクエストの場合、Cloud Firestore はCloud Firestore セキュリティ ルールを使用して、リクエストが承認されているかどうかを判断します。

Google Identity OAuth 2.0 トークンの操作

アクセス トークンは、Google API クライアント ライブラリサービス アカウントを使用するか、サーバー間アプリケーションでの OAuth 2.0 の使用の手順に従って生成できます。 gcloudコマンドライン ツールとコマンドgcloud auth application-default print-access-token使用してトークンを生成することもできます。

Cloud Firestore REST API にリクエストを送信するには、このトークンに次のスコープが必要です。

  • https://www.googleapis.com/auth/datastore

サービス アカウントと Google Identity OAuth 2.0 トークンを使用してリクエストを認証する場合、Cloud Firestore は、リクエストが個々のユーザーではなくアプリケーションに代わって動作すると想定します。 Cloud Firestore では、これらのリクエストでセキュリティ ルールを無視できます。代わりに、Cloud Firestore はIAMを使用して、リクエストが承認されているかどうかを判断します。

Cloud Firestore IAM の役割を割り当てることで、サービス アカウントのアクセス権限を制御できます。

アクセストークンによる認証

Firebase ID トークンまたは Google Identity OAuth 2.0 トークンを取得したら、 Bearer {YOUR_TOKEN}に設定されたAuthorizationヘッダーとして Cloud Firestore エンドポイントに渡します。

REST 呼び出しの実行

すべての REST API エンドポイントは、ベース URL https://firestore.googleapis.com/v1/の下に存在します。

プロジェクトYOUR_PROJECT_IDの下のコレクションcitiesで ID LAを持つドキュメントへのパスを作成するには、次の構造を使用します。

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

このパスを操作するには、ベース API URL と組み合わせます。

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

REST API の実験を開始する最良の方法は、 API Explorerを使用することです。これにより、Google Identity OAuth 2.0 トークンが自動的に生成され、API を調べることができます。

メソッド

以下は、最も重要な 2 つのメソッド グループの簡単な説明です。完全なリストについては、 REST API リファレンスを参照するか、 API Explorerを使用してください。

v1.projects.databases.documents

データの追加またはデータの取得ガイドで説明されている操作と同様に、ドキュメントに対して CRUD 操作を実行します。

v1.projects.databases.collectionGroups.indexes

新しいインデックスの作成、既存のインデックスの無効化、現在のすべてのインデックスの一覧表示など、インデックスに対してアクションを実行します。データ構造の移行の自動化や、プロジェクト間のインデックスの同期に役立ちます。

また、特定のドキュメントのすべてのフィールドとサブコレクションのリストなど、ドキュメント メタデータの取得も可能にします。

エラーコード

Cloud Firestore リクエストが成功すると、Cloud Firestore API は HTTP 200 OKステータス コードとリクエストされたデータを返します。リクエストが失敗すると、Cloud Firestore API は HTTP 4xxまたは5xxステータス コードと、エラーに関する情報を含むレスポンスを返します。

次の表に、エラー コードごとに推奨されるアクションを示します。これらのコードは、Cloud Firestore REST および RPC API に適用されます。 Cloud Firestore SDK とクライアント ライブラリは、これらと同じエラー コードを返さない場合があります。

正規のエラー コード説明推奨される行動
ABORTEDリクエストが別のリクエストと競合しました。非トランザクション コミットの場合:
要求を再試行するか、データ モデルを再構築して競合を減らします。

トランザクション内のリクエストの場合:
トランザクション全体を再試行するか、データ モデルを再構築して競合を減らします。
ALREADY_EXISTSリクエストは、すでに存在するドキュメントを作成しようとしました。問題を修正せずに再試行しないでください。
DEADLINE_EXCEEDEDリクエストを処理する Cloud Firestore サーバーが期限を超えました。指数バックオフを使用して再試行します。
FAILED_PRECONDITION要求が前提条件の 1 つを満たしていませんでした。たとえば、クエリ要求では、まだ定義されていないインデックスが必要になる場合があります。失敗した前提条件については、エラー応答のメッセージ フィールドを参照してください。問題を修正せずに再試行しないでください。
INTERNAL Cloud Firestore サーバーがエラーを返しました。この要求を複数回再試行しないでください。
INVALID_ARGUMENTリクエスト パラメータに無効な値が含まれています。無効な値については、エラー応答のメッセージ フィールドを参照してください。問題を修正せずに再試行しないでください。
NOT_FOUND要求は、存在しないドキュメントを更新しようとしました。問題を修正せずに再試行しないでください。
PERMISSION_DENIEDユーザーはこの要求を行う権限がありません。問題を修正せずに再試行しないでください。
RESOURCE_EXHAUSTEDプロジェクトが割り当て量またはリージョン/マルチリージョンのキャパシティを超えました。プロジェクトの割り当てを超えていないことを確認します。プロジェクトのクォータを超えた場合は、問題を解決せずに再試行しないでください。

それ以外の場合は、指数バックオフで再試行します。
UNAUTHENTICATED要求に有効な認証資格情報が含まれていませんでした。問題を修正せずに再試行しないでください。
UNAVAILABLE Cloud Firestore サーバーがエラーを返しました。指数バックオフを使用して再試行します。