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 Security Rules を使用して、リクエストを認可するかどうかを判断します。

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

Firebase ID トークンに関する処理

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

• Firebase Authentication REST API を使用して Firebase ID トークンを生成する。
• Firebase Authentication SDK からユーザーの Firebase ID トークンを取得する。

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

Firebase ID トークンで認証されたリクエストと、未認証のリクエストに対して、Cloud Firestore は Cloud Firestore Security Rules を使用して、リクエストを認可するかどうかを判断します。

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 が便利です。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 とクライアント ライブラリでは、これらのエラーコードと同じものが返されない場合があります。