Cloud Firestore REST API の使用

Cloud Firestore を使用する場合、ネイティブのクライアント ライブラリを使用するのが最も簡単な方法ですが、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 トークンのいずれかを取得したら、それを Authorization ヘッダーで Bearer {YOUR_TOKEN} のように設定して 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 が便利です。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 API と RPC API に適用されます。Cloud Firestore SDK とクライアント ライブラリでは、これらの同じエラーコードが返されない場合があります。

標準的なエラーコード 説明 推奨される対応
ABORTED リクエストが別のリクエストと競合しています。 非トランザクション commit の場合:
リクエストを再試行するか、データモデルを再構成して競合を減らします。

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

そうでない場合は、指数バックオフで再試行します。
UNAUTHENTICATED リクエストに有効な認証情報が含まれていません。 問題を解決してから再試行します。
UNAVAILABLE Cloud Firestore サーバーがエラーを返しました。 指数バックオフを使用して再試行します。