Linux ベースのエミュレータ (プレビュー)
次世代の Azure Cosmos DB エミュレータは、完全に Linux ベースであり、Docker コンテナーとして使用できます。 さまざまなプロセッサとオペレーティング システムでの実行をサポートしています。
重要
このバージョンのエミュレータでは、特定の機能のサブセットを持つ、ゲートウェイ モードの NoSQL 用 API のみがサポートされます。 詳しくは、「機能のサポート」をご覧ください。
前提条件
インストール
docker pull を使用して Docker コンテナー イメージを取得します。 コンテナー イメージは、mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview として Microsoft アーティファクト レジストリに公開されます。
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>
Note
エミュレータは、次の 2 つのコンポーネントで構成されます。
- データ エクスプローラー - エミュレータ内のデータを対話形式で探索します。 既定では、これはポート
1234で実行されます - Azure Cosmos DB エミュレータ - Azure Cosmos DB データベース サービスのローカル バージョン。 既定では、これはポート
8081で実行されます。
エミュレータ ゲートウェイ エンドポイントは通常、アドレス http://localhost:8081 のポート 8081 で使用できます。 データ エクスプローラーに移動するには、Web ブラウザーでアドレス 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 コマンドをまとめています。 この表では、対応する引数、環境変数、使用できる値、既定の設定、および各コマンドの説明について詳しく説明します。
| 要件 | Arg | Env | 使用できる値 | 既定値 | 説明 |
|---|---|---|---|---|---|
| コンテナーから stdout に設定を出力する | --help、-h |
該当なし | 該当なし | 該当なし | 使用可能な構成に関する情報を表示する |
| Cosmos エンドポイントのポートを設定する | --port [INT] |
ポート | INT | 8081 | コンテナー上の Cosmos エンドポイントのポート。 引き続きこのポートを公開する必要があります (たとえば、-p 8081:8081)。 |
| Cosmos エンドポイントによって使用されるプロトコルを指定する | --protocol |
プロトコル | https、http、https-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、http、https-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 run に次のようなオプションを追加します: --mount type=bind,source=./.local/data,target=/usr/cosmos/data) |
| https に使用する証明書のパスを指定する | --cert-path [PATH] |
CERT_PATH | PATH | <default cert> |
トラフィックをセキュリティで保護するために証明書へのパスを指定します。 このファイルをコンテナーにマウントする必要があります (たとえば、CERT_PATH=/mycert.pfx の場合は、docker run に次のようなオプションを追加します: --mount type=bind,source=./mycert.pfx,target=/mycert.pfx) |
| https に使用する証明書のシークレットを指定する | 該当なし | CERT_SECRET | string | <default secret> |
CERT_PATH で指定された証明書のシークレット。 |
| ログ レベルを設定する | --log-level [LEVEL] |
LOG_LEVEL | quiet、error、warn、info、debug、trace |
info |
エミュレータとデータ エクスプローラーによって出力されるログの詳細度。 |
| Microsoft に診断情報を送信できるようにする | --enable-telemetry |
ENABLE_TELEMETRY | true、false |
true |
エミュレータの改善に役立つようにログを Microsoft に送信できるようにします。 |
機能サポート
このエミュレータは開発が進められ、プレビュー段階です。 その結果、すべての Azure Cosmos DB 機能がサポートされるわけではありません。 一部の機能は、今後もサポートされません。 この表には、さまざまな機能の状態とそのサポート レベルが記載されています。
| 機能 | サポート |
|---|---|
| Batch API | ✅ サポートされています |
| Bulk API | ✅ サポートされています |
| 変更フィード | ⚠ まだ実装されていません |
| utf データを持つドキュメントの作成と読み取り | ✅ サポートされています |
| コレクションの作成 | ✅ サポートされています |
| コレクション 2 回競合の発生 | ✅ サポートされています |
| カスタム インデックス ポリシーを持つコレクションの作成 | ⚠ まだ実装されていません |
| ttl の有効期限を持つコレクションの作成 | ⚠ まだ実装されていません |
| データベースの作成 | ✅ サポートされています |
| データベース 2 回競合の発生 | ✅ サポートされています |
| ドキュメントの作成 | ✅ サポートされています |
| パーティション分割コレクションの作成 | ⚠ まだ実装されていません |
| コレクションを削除する | ✅ サポートされています |
| データベースの削除 | ✅ サポートされています |
| ドキュメントの削除 | ✅ サポートされています |
| コレクションのパフォーマンスの取得および変更 | ⚠ まだ実装されていません |
| 大きなドキュメントの挿入 | ✅ サポートされています |
| ドキュメントのパッチ適用 | ⚠ まだ実装されていません |
| 並列でのパーティション分割コレクションのクエリ | ⚠ まだ実装されていません |
| 集計を使用したクエリ | ⚠ まだ実装されていません |
| AND フィルターを使用したクエリ | ⚠ まだ実装されていません |
| AND フィルターとプロジェクションを使用したクエリ | ⚠ まだ実装されていません |
| 等値を使用したクエリ | ✅ サポートされています |
| ID で等号を使用したクエリ | ✅ サポートされています |
| 結合を使用したクエリ | ⚠ まだ実装されていません |
| Order By を使用するクエリ | ✅ サポートされています |
| パーティション分割コレクションに対する Order By を使用したクエリ | ⚠ まだ実装されていません |
| Order By 番号を使用するクエリ | ✅ サポートされています |
| Order By 文字列を使用するクエリ | ⚠ まだ実装されていません |
| ページングを使用したクエリ | ⚠ まだ実装されていません |
| 範囲演算子の日時を使用したクエリ | ⚠ まだ実装されていません |
| 数値で範囲演算子を使用したクエリ | ⚠ まだ実装されていません |
| 文字列で範囲演算子を使用したクエリ | ⚠ まだ実装されていません |
| 単一の結合を使用したクエリ | ⚠ まだ実装されていません |
| 文字列、数値、および配列の演算子を使用するクエリ | ⚠ まだ実装されていません |
| サブドキュメントを使用したクエリ | ⚠ まだ実装されていません |
| 2 つの結合を使用したクエリ | ⚠ まだ実装されていません |
| 2 つの結合とフィルターを使用したクエリ | ⚠ まだ実装されていません |
| コレクションの読み取り | ✅ サポートされています |
| コレクション フィードの読み取り | ⚠ まだ実装されていません |
| データベースの読み取り | ✅ サポートされています |
| データベース フィードの読み取り | ⚠ まだ実装されていません |
| ドキュメントの読み取り | ✅ サポートされています |
| ドキュメント フィードの読み取り | ✅ サポートされています |
| ドキュメントを置換する | ✅ サポートされています |
| 要求ユニット | ⚠ まだ実装されていません |
| ストアド プロシージャ | ❌ 計画されていません |
| トリガー | ❌ 計画されていません |
| UDF | ❌ 計画されていません |
| コレクションの更新 | ⚠ まだ実装されていません |
| ドキュメントの更新 | ✅ サポートされています |
制限事項
次の一覧には、まだサポートされていない機能や計画されていない機能に加えて、エミュレータの現在の制限事項が記載されています。
- Azure Cosmos DB 用の .NET SDK では、エミュレータでの一括実行はサポートされていません。
- .NET および Java SDK でエミュレータの HTTP モードはサポートされていません。
Java SDK の証明書をインストールする
このバージョンのエミュレータで Azure Cosmos DB 用の Java SDK を https モードで使用する場合は、その証明書をローカルの 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
証明書のインストール
cacerts ファイルがある Java インストールのディレクトリに移動します (以下を正しいディレクトリで置き換えます)。
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 を使用してタグ付けします。