執行 Datastore 模擬器

Datastore 模擬器可在本機上模擬實際運作的 Datastore 環境。您可以用這個模擬器在本機上開發及測試應用程式。此外，模擬器還可幫您對實際運作的 Datastore 執行個體產生索引，以及刪除不需要的索引。本頁說明如何安裝及啟動模擬器，並設定環境變數，將您的應用程式連接至模擬器。

已知問題

根據預設，Datastore 模擬器不會模擬 Firestore (Datastore 模式) 導入的功能。下列預設模擬器行為與 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 模擬器，您需要：

安裝模擬器

Datastore 模擬器是 gcloud CLI 的元件。使用 gcloud components install 指令安裝 Datastore 模擬器：

gcloud components install cloud-datastore-emulator

模擬器資料目錄

模擬器模擬 Datastore 時，會在指定資料目錄建立 /WEB-INF/appengine-generated/local_db.bin，並將資料儲存在 local_db.bin。預根據預設，模擬器使用的資料目錄是 ~/.config/gcloud/emulators/datastore/。local_db.bin 檔案介於模擬器的工作階段之間。您可以設定多個資料目錄，並將每個目錄視為單獨的本機 Datastore 模式執行個體。如要清除 local_db.bin 檔案的內容，請停止模擬器並手動刪除該檔案。

啟動模擬器

在命令提示字元執行 datastore start，以啟動模擬器：

gcloud beta 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 模擬器。

手動設定變數

如果您的應用程式與模擬器在不同機器上執行，可手動設定環境變數：

  1. 執行 env-init 指令：

    gcloud beta emulators datastore env-init

  2. 在執行應用程式的機器上，依照 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」。

移除環境變數

使用完模擬器後，停止模擬器 (Ctrl-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 模式資料庫。

手動移除變數

如果您的應用程式和模擬器在不同機器上執行，請手動刪除環境變數：

  1. 執行 env-unset 指令：

    gcloud beta emulators datastore env-unset

  2. 在執行應用程式的機器上，依照 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 模式資料庫。