运行 Datastore 模拟器

Datastore 模拟器可在本地模拟 Datastore 生产环境。您可以使用该模拟器在本地开发和测试应用。此外，该模拟器有助于为 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.

要停止模拟器，请在命令提示符下按下 Control-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。

移除环境变量

使用完模拟器后，停止模拟器 (Control-C) 并移除环境变量，以便将应用连接到 Datastore 模式生产数据库。

自动移除变量

如果您的应用和模拟器在同一台机器上运行，您可以自动移除环境变量：

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 模式生产数据库。