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 サーバーがエラーを返しました。	指数バックオフを使用して再試行します。