以 Linux 為基礎的模擬器 （預覽）
新一代的 Azure Cosmos DB 模擬器完全是以 Linux 為基礎，可作為 Docker 容器使用。 它支援在各種不同的處理器和操作系統上執行。
必要條件
安裝
使用 docker pull取得 Docker 容器映像。 容器映像會發行至 Microsoft 成品登錄 作為 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview。
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
執行中
若要執行容器，請使用 docker run。 之後，使用 docker ps 來驗證容器是否正在執行。
docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c1bb8cf53f8a mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview "/bin/bash -c /home/…" 5 seconds ago Up 5 seconds 0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp <container-name>
注意
模擬器是由兩個元件所組成：
- 數據總管 - 以互動方式探索模擬器中的數據。 根據預設，這會在埠上執行
1234 - Azure Cosmos DB 模擬器 - Azure Cosmos DB 資料庫服務的本機版本。 根據預設，這會在埠
8081上執行。
模擬器閘道連接點通常可在位址 http://localhost:8081的埠8081上使用。 若要瀏覽至數據總管，請使用網頁瀏覽器中的位址 http://localhost:1234 。 可能需要幾秒鐘的時間，數據總管才能使用。 閘道端點通常可立即使用。
重要
.NET 和 Java SDK 在模擬器中不支援 HTTP 模式。 由於這個版本的模擬器預設會以 HTTP 開頭，因此您必須在啟動容器時明確啟用 HTTPS（請參閱下文）。 針對 Java SDK，您也需要 安裝憑證。
docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https
Docker 命令
下表摘要說明可用來設定模擬器的可用 Docker 命令。 下表詳述每個命令的對應自變數、環境變數、允許的值、預設設定和描述。
| 需求 | 精 氨 酸 | Env | 允許的值 | 預設 | 描述 |
|---|---|---|---|---|---|
| 從容器將設定列印至 stdout | --help, -h |
N/A | N/A | N/A | 顯示可用設定的相關信息 |
| 設定 Cosmos 連接點的埠 | --port [INT] |
連接埠 | INT | 8081 | 容器上 Cosmos 連接點的埠。 您仍然需要發佈此連接埠 （例如 ， 。 -p 8081:8081 |
| 指定 Cosmos 端點所使用的通訊協定 | --protocol |
通訊協定 | https、 、 httphttps-insecure |
http |
容器上 Cosmos 端點的通訊協定。 |
| 啟用數據總管 | --enable-explorer |
ENABLE_EXPLORER | true, false |
true |
在相同的容器上啟用執行 Cosmos 數據總管。 |
| 設定數據總管所使用的埠 | --explorer-port |
EXPLORER_PORT | INT | 1234 | 容器上 Cosmos 數據總管的埠。 您仍然需要發佈此連接埠 （例如 ， 。 -p 1234:1234 |
| 用戶應該能夠指定總管所使用的通訊協定，否則預設為 Cosmos 端點所使用的通訊協定 | --explorer-protocol |
EXPLORER_PROTOCOL | https、 、 httphttps-insecure |
<the value of --protocol> |
容器上 Cosmos 數據總管的通訊協定。 預設為 Cosmos 端點上的通訊協議設定。 |
| 透過檔案指定金鑰 | --key-file [PATH] |
KEY_FILE | PATH | <default secret> |
使用檔案中指定的索引鍵覆寫預設索引鍵。 您需要將此檔案掛接至容器（例如，如果KEY_FILE=/mykey，您會將如下所示的選項新增至 docker run： --mount type=bind,source=./myKey,target=/myKey |
| 設定數據路徑 | --data-path [PATH] |
DATA_PATH | PATH | /data |
指定資料的目錄。 經常搭配docker run --mount選項使用 （例如，如果 DATA_PATH=/usr/cosmos/data，您會將如下所示的選項新增至 Docker 執行： --mount type=bind,source=./.local/data,target=/usr/cosmos/data |
| 指定要用於 HTTPs 的憑證路徑 | --cert-path [PATH] |
CERT_PATH | PATH | <default cert> |
指定憑證的路徑來保護流量。 您需要將此檔案掛接至容器（例如，如果 CERT_PATH=/mycert.pfx，您會將如下所示的選項新增至 Docker 執行： --mount type=bind,source=./mycert.pfx,target=/mycert.pfx |
| 指定要用於 HTTPs 的憑證密碼 | N/A | CERT_SECRET | 字串 | <default secret> |
CERT_PATH上指定之憑證的秘密。 |
| 設定記錄層級 | --log-level [LEVEL] |
LOG_LEVEL | quiet、、errorwarn、info、、debug、trace |
info |
模擬器和數據總管發出之記錄的詳細資訊。 |
| 啟用傳送至Microsoft的診斷資訊 | --enable-telemetry |
ENABLE_TELEMETRY | true, false |
true |
啟用將記錄傳送至Microsoft，以協助我們改善模擬器。 |
功能支援
此模擬器處於使用中開發和預覽狀態。 因此，並非所有 Azure Cosmos DB 功能都受到支援。 未來也不支援某些功能。 下表包含各種功能的狀態及其支援層級。
| 功能 | 支援 |
|---|---|
| Batch API | ✅ 支援 |
| 大量 API | ✅ 支援 |
| 變更摘要 | ⚠️ 尚未實作 |
| 使用 utf 資料建立和讀取檔 | ✅ 支援 |
| 建立集合 | ✅ 支援 |
| 建立集合兩次衝突 | ✅ 支援 |
| 使用自定義索引原則建立集合 | ⚠️ 尚未實作 |
| 建立具有 ttl 到期的集合 | ⚠️ 尚未實作 |
| 建立資料庫 | ✅ 支援 |
| 建立資料庫兩次衝突 | ✅ 支援 |
| 建立檔 | ✅ 支援 |
| 建立數據分割集合 | ⚠️ 尚未實作 |
| 刪除集合 | ✅ 支援 |
| 刪除資料庫 | ✅ 支援 |
| 刪除檔案 | ✅ 支援 |
| 取得和變更集合效能 | ⚠️ 尚未實作 |
| 插入大型檔 | ✅ 支援 |
| 修補檔 | ⚠️ 尚未實作 |
| 平行查詢分割集合 | ⚠️ 尚未實作 |
| 使用匯總查詢 | ⚠️ 尚未實作 |
| 使用和篩選查詢 | ⚠️ 尚未實作 |
| 使用和篩選和投影進行查詢 | ⚠️ 尚未實作 |
| 相等查詢 | ✅ 支援 |
| 標識碼等於的查詢 | ✅ 支援 |
| 使用聯結查詢 | ⚠️ 尚未實作 |
| 依順序查詢 | ✅ 支援 |
| 依數據分割集合排序的查詢 | ⚠️ 尚未實作 |
| 依數位排序的查詢 | ✅ 支援 |
| 依字串排序的查詢 | ⚠️ 尚未實作 |
| 使用分頁查詢 | ⚠️ 尚未實作 |
| 使用範圍運算子的日期時間進行查詢 | ⚠️ 尚未實作 |
| 使用數位範圍運算子進行查詢 | ⚠️ 尚未實作 |
| 使用字串上的範圍運算符進行查詢 | ⚠️ 尚未實作 |
| 使用單一聯結進行查詢 | ⚠️ 尚未實作 |
| 使用字串數學和陣列運算子進行查詢 | ⚠️ 尚未實作 |
| 使用子文件進行查詢 | ⚠️ 尚未實作 |
| 使用兩個聯結進行查詢 | ⚠️ 尚未實作 |
| 使用兩個聯結和篩選進行查詢 | ⚠️ 尚未實作 |
| 讀取集合 | ✅ 支援 |
| 讀取收集摘要 | ⚠️ 尚未實作 |
| 讀取資料庫 | ✅ 支援 |
| 讀取資料庫摘要 | ⚠️ 尚未實作 |
| 讀取檔 | ✅ 支援 |
| 讀取檔案摘要 | ✅ 支援 |
| 取代檔 | ✅ 支援 |
| 要求單位 | ⚠️ 尚未實作 |
| 預存程序 | ❌ 未規劃 |
| 觸發程序 | ❌ 未規劃 |
| UDF | ❌ 未規劃 |
| 更新集合 | ⚠️ 尚未實作 |
| 更新檔 | ✅ 支援 |
限制
除了尚未支援或尚未規劃的功能之外，下列清單還包含模擬器目前的限制。
- 適用於 Azure Cosmos DB 的 .NET SDK 不支援模擬器中的大量執行。
- .NET 和 Java SDK 在模擬器中不支援 HTTP 模式。
安裝 Java SDK 的憑證
在 HTTPs 模式中搭配此版本的模擬器使用 適用於 Azure Cosmos DB 的 Java SDK 時，必須將憑證安裝到本機 Java 信任存放區。
取得憑證
bash在視窗中，執行下列命令：
# If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
安裝憑證
瀏覽至檔案所在的 Java 安裝 cacerts 目錄（將下方取代為正確的目錄）：
cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"
匯入憑證（系統可能會要求您輸入密碼，預設值為 “changeit”）：
keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH
如果您因為別名已經存在而收到錯誤，請將其刪除，然後再次執行上述命令：
keytool -cacerts -delete -alias cosmos_emulator
回報問題
如果您在使用此版本的模擬器時遇到問題，請在 GitHub 存放庫中開啟問題 ，https://github.com/Azure/azure-cosmos-db-emulator-docker並以標籤 cosmosEmulatorVnextPreview它。