Datastore エミュレータは、Datastore 本番環境のローカル エミュレーションを可能にします。 このエミュレータを使用して、アプリケーションを開発してローカルでテストすることができます。加えて、このエミュレータを使用すると、Cloud Datastore の本番環境インスタンス用のインデックスを生成し、不要なインデックスを削除することができます。このページでは、エミュレータのインストール、エミュレータの開始、およびアプリケーションをエミュレータに接続するための環境変数の設定について説明します。
既知の問題
デフォルトでは、Datastore エミュレータは Datastore モードの Firestore で導入された機能をエミュレートしません。次のデフォルト エミュレータの動作は、Datastore モードと一致しません。
- デフォルトで、エミュレータは結果整合性をシミュレートします。Datastore モードの Firestore は強整合性に対応しています。
- エミュレータでは、トランザクション内で祖先以外のクエリを使用できません。Datastore モードの Firestore では、この制限がなくなりました。
- エミュレータでは、
IN、!=、NOT-INクエリはサポートされていません。 - エミュレータでは、
COUNT(*)などの集約クエリはサポートされていません。
ただし、--use-firestore-in-datastore-mode フラグを使用すると、Datastore モードの Firestore に関する制限の一部が緩和されます。
- エミュレータは、強整合性を持つ祖先以外のクエリをシミュレートします。
- エミュレータでは、トランザクション内で祖先以外のクエリを使用できます。
- エミュレータでは、トランザクション内のエンティティ グループ数に関する上限（最大 25 個）が解消されています。
Datastore モードの Firestore をエミュレートするには、代わりに gcloud emulators firestore start --database-mode=datastore-mode を使用します。
始める前に
Datastore エミュレータを使用するには、次のものが必要です。
- Java JRE（バージョン 11 以降）
- Google Cloud CLI
- Google Cloud クライアント ライブラリを使用して構築されたアプリケーション
エミュレータのインストール
Datastore エミュレータは、gcloud CLI のコンポーネントです。gcloud components install コマンドを使用して、Datastore エミュレータをインストールします。
gcloud components install cloud-datastore-emulator
エミュレータ データ ディレクトリ
エミュレータは、指定されたデータ ディレクトリに /WEB-INF/appengine-generated/local_db.bin を作成し、local_db.bin にデータを格納して、Datastore のシミュレーションを行います。デフォルトでは、エミュレータはデータ ディレクトリ ~/.config/gcloud/emulators/datastore/ を使用します。local_db.bin ファイルは、エミュレータのセッションを通じて継続します。複数のデータ ディレクトリを設定し、それぞれを別々のローカル Datastore モードのインスタンスとして扱うことができます。local_db.bin ファイルの内容をクリアするには、エミュレータを停止して、ファイルを手動で削除します。
エミュレータの開始
コマンド プロンプトで datastore start を実行してエミュレータを起動します。
gcloud emulators datastore start [flags]
ここで、[flags] は gcloud CLI に渡されるオプションのコマンドライン引数です。例:
--data-dir=[DATA_DIR]で、エミュレータのデータ ディレクトリを変更します。エミュレータは、[DATA_DIR]の内部に/WEB-INF/appengine-generated/local_db.binファイルを作成するか、既存のファイルが使用可能な場合にはそれを使用します。--no-store-on-diskで、エミュレータ セッション用のデータをディスクに残さないようにエミュレータを構成します。
オプション フラグの一覧については、gcloud beta emulators datastore start のリファレンスをご覧ください。
エミュレータを開始すると、次のようなメッセージが表示されます。
...
[datastore] Dev App Server is now running.
エミュレータを停止するには、コマンド プロンプトで Ctrl+C を入力します。
環境変数の設定
エミュレータを開始したら、アプリケーションが本番環境用の Datastore モードのデータベースではなくエミュレータに接続するように環境変数を設定する必要があります。これらの環境変数は、アプリケーションの実行に使用するものと同じマシン上で設定します。
環境変数はエミュレータを開始するたびに設定する必要があります。環境変数は、動的に割り当てられるポート番号に依存しています。この番号は、エミュレータを再起動するたびに変わる可能性があります。
変数の自動設定
アプリケーションとエミュレータが同じマシン上で動作している場合は、次のようにして環境変数を自動的に設定できます。
Linux / macOS
コマンド代入を使用して env-init を実行します。
$(gcloud beta emulators datastore env-init)
Windows
env-init からの出力を使用してバッチファイルを作成、実行します。
gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd
これで、アプリケーションが Datastore エミュレータに接続します。
変数の手動設定
アプリケーションとエミュレータが別々のマシン上で動作している場合は、次のようにして環境変数を手動で設定します。
env-initコマンドを実行します。gcloud beta emulators datastore env-init
アプリケーションを実行するマシンで、
env-initコマンドの出力結果に基づいて環境変数と値を設定します。例:Linux / macOS export DATASTORE_DATASET=my-project-id export DATASTORE_EMULATOR_HOST=::1:8432 export DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore export DATASTORE_HOST=http://::1:8432 export DATASTORE_PROJECT_ID=my-project-id
Windows set DATASTORE_DATASET=my-project-id set DATASTORE_EMULATOR_HOST=::1:8432 set DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore set DATASTORE_HOST=http://::1:8432 set DATASTORE_PROJECT_ID=my-project-id
これで、アプリケーションが Datastore エミュレータに接続します。 コマンドで提供されるプロジェクト ID とポートは、上記の例とは異なることに注意してください。
インデックスの更新と削除
エミュレータを使用してアプリケーションを実行すると、本番環境用の Datastore モード データベースのインデックスを生成でき、不要なインデックスを削除することもできます。詳細については、gcloud CLI の使用をご覧ください。
環境変数の削除
エミュレータの使用が終わったら、アプリケーションが本番環境用の Datastore モード データベースに接続するように、エミュレータを停止して（Ctrl+C）、環境変数を削除します。
変数の自動削除
アプリケーションとエミュレータが同じマシン上で動作している場合は、次のようにして環境変数を自動的に削除できます。
Linux / macOS
コマンド代入を使用して env-unset を実行します。
$(gcloud beta emulators datastore env-unset)
Windows
env-unset からの出力を使用してバッチファイルを作成、実行します。
gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd
これで、アプリケーションが本番環境用の Datastore モード データベースに接続するようになります。
変数の手動削除
アプリケーションとエミュレータが別々のマシン上で動作している場合は、次のようにして環境変数を手動で削除します。
env-unsetコマンドを実行します。gcloud beta emulators datastore env-unset
アプリケーションを実行するマシンで、
env-unsetコマンドの出力結果に基づいて環境変数を削除します。例:Linux / macOS unset DATASTORE_DATASET unset DATASTORE_EMULATOR_HOST unset DATASTORE_EMULATOR_HOST_PATH unset DATASTORE_HOST unset DATASTORE_PROJECT_ID
Windows set DATASTORE_DATASET= set DATASTORE_EMULATOR_HOST= set DATASTORE_EMULATOR_HOST_PATH= set DATASTORE_HOST= set DATASTORE_PROJECT_ID=
これで、アプリケーションが本番環境用の Datastore モード データベースに接続するようになります。