Firestore エミュレータを使用して Datastore モードをテストする

Google Cloud CLI には、Datastore モード アプリケーションで Firestore をテストする際に使用できる Firestore 用のローカル インメモリ エミュレータが用意されています。このエミュレータは、すべての Datastore モード クライアント ライブラリで使用できます。エミュレータはローカルテストでのみ使用してください。

Datastore モードにおける Firestore の動作をテストするには、gcloud emulators firestore と --database-mode=datastore-mode を使用します。

エミュレータは、本番環境のデプロイには使用しないでください。エミュレータはメモリ内にのみデータを保存するため、終了時にデータは失われます。

エミュレータをインストールする

Firestore エミュレータをインストールするには、gcloud CLI をインストールして更新します。

1. gcloud CLI をインストールします。

2. gcloud CLI インストールを更新して、最新の機能を取得します。

   gcloud components update
   

エミュレータを実行する

1. 次のコマンドを実行して、エミュレータを起動します。

   gcloud emulators firestore start --database-mode=datastore-mode
   

   エミュレータによって、実行中のホストとポート番号が表示されます。

   デフォルトでは、エミュレータは 127.0.0.1:8080 の使用を試みます。エミュレータを特定のホストとポートにバインドするには、オプションの --host-port フラグを使用し、HOST と PORT を置き換えます。

   gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT
   

2. エミュレータを停止するには、キーボード ショートカット Control + C を使用します。

注: エミュレータのデフォルト ポートは 8080 です。これは、デフォルト ポート 8081 を使用していた以前の Cloud Datastore エミュレータとは異なります。

エミュレータに接続する

クライアント ライブラリとアプリをエミュレータに接続するには、DATASTORE_EMULATOR_HOST 環境変数を設定します。この環境変数が設定されると、クライアント ライブラリは自動的にエミュレータに接続されます。

export DATASTORE_EMULATOR_HOST="HOST:PORT"

エンティティをエミュレータにインポートする

エミュレータのインポート機能を使用することによって、一連のエンティティ エクスポート ファイルからエミュレータにエンティティを読み込むことができます。エンティティ エクスポート ファイルは、Datastore モードのデータベースのエクスポートまたはエミュレータ インスタンスから取得できます。

エンティティをエミュレータにインポートするには、2 つの方法があります。1 つ目は、エミュレータの起動コマンドに import-data フラグを追加する方法です。2 つ目は、POST インポート リクエストをエミュレータに送信する方法です。curl や同様のツールを使用します。次の例を参照してください。

プロトコル

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:import \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'

エミュレータが別のポートを使用している場合は、localhost:8080 を変更します。

CLI のフラグ

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY

ここで

• [PROJECT_ID] は、プロジェクトの ID です。

• [DATABASE] はデータベース パスです。たとえば、デフォルトのデータベースを使用するプロジェクトは次のようになります。

  {"database":"projects/myProject/databases/"}

• [EXPORT_DIRECTORY] は、エンティティ エクスポート ファイルの overall_export_metadata ファイルへのパスです。次に例を示します。

  {"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}

注: 特定の種類または名前空間のエンティティをエクスポートすることはできません。

エミュレータ内のエンティティをエクスポートする

エミュレータのエクスポート機能を使用することによって、エミュレータ内のエンティティを一連のエンティティ エクスポート ファイルに保存できます。その後、インポート オペレーションを使用して、エンティティ エクスポート ファイル内のエンティティを Datastore モードのデータベースまたはエミュレータ インスタンスに読み込むことができます。

エミュレータからエンティティをエクスポートするには、次の 2 つの方法があります。1 つ目は、エミュレータの起動コマンドに export-on-exit フラグを追加する方法です。2 つ目は、POST エクスポート リクエストをエミュレータに送信する方法です。curl や同様のツールを使用します。次の例を参照してください。

プロトコル

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:export \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE_PATH", "export_directory":"EXPORT_DIRECTORY"}'

エミュレータが別のポートを使用している場合は、localhost:8080 を変更します。

CLI のフラグ

gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY

ここで

• [PROJECT_ID] は、プロジェクトの ID です。

• [DATABASE_PATH] はデータベースのパスです。たとえば、デフォルトのデータベースを使用するプロジェクトは次のようになります。

  {"database":"projects/myProject/databases/"}

• [EXPORT_DIRECTORY] は、エンティティ エクスポート ファイルを保存するディレクトリを指定します。このディレクトリには、一連のエンティティ エクスポート ファイルが含まれていないようにしてください。次に例を示します。

  {"export_directory":"/home/user/myexports/2024-03-26/"}

注: 特定の種類または名前空間のエンティティをエクスポートすることはできません。

エミュレータ内でデータを保持する

デフォルトでは、Firestore エミュレータはデータをディスクに保持しません。エミュレータ データを保持するには、次のコマンドを実行してインポート フラグとエクスポート フラグを使用し、エミュレータ インスタンス間でデータを読み込んで保存します。

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY --export-on-exit=EXPORT_DIRECTORY

エミュレータ データをリセットする

Firestore エミュレータには、エミュレータ内のすべてのデータをリセットする REST エンドポイントが含まれています。このエンドポイントを使用すると、エミュレータをシャットダウンしなくても、テストの合間にデータを消去できます。

エミュレータ内のすべてのデータをリセットするには、次のエンドポイントに対して HTTP POST オペレーションを実行します。HOST と PORT は、選択したホストとポートに置き換え、PROJECT_ID は実際のプロジェクト ID に置き換えます。

http://HOST:PORT/reset

エミュレータで 127.0.0.1:8080 を使用しない場合は、ホストとポートを調整します。コードは、リセットが終了または失敗したことを REST が確認するまで待機します。

この操作は curl を使用してシェルから実行できます。

$ curl -X POST "http://HOST:PORT/reset"

エミュレータと本番環境の違い

エミュレータは、本番環境サービスの動作を忠実に再現しようとしますが、いくつか注意が必要な制限事項があります。

同時実行と整合性

エミュレータでは、ペシミスティック同時実行と強整合性のみがサポートされています。オプティミスティック同時実行と結果整合性の設定はサポートされていません。

トランザクション

エミュレータは、本番環境で発生するトランザクションの動作すべてを実装しているわけではありません。1 つのドキュメントに対して複数の書き込みが同時に実行される機能をテストする場合、エミュレータでは書き込みリクエストが完了するまで時間がかかることがあります。場合によっては、ロックが解除されるまでに最長で 30 秒かかります。必要に応じて、この問題に対応するように、テストのタイムアウトを調整することを検討してください。

インデックス

このエミュレータでは複合インデックスは追跡されず、有効なクエリであればそのまま実行されます。実際の Datastore モード インスタンスでアプリをテストし、必要なインデックスを特定してください。

上限

このエミュレータでは、本番環境で適用される制限すべてが適用されるわけではありません。たとえば、本番環境サービスではサイズが大きいことを理由に拒否されるトランザクションでも、エミュレータでは許容される場合があります。ドキュメントに記載されている制限を十分に理解し、事前にこうした制限を回避するようにアプリを設計してください。

次のステップ

• エンティティ、プロパティ、キーを操作する方法を学習する
• クエリについて学習する