2026年5月21日に公開または更新された Azure Cosmos DB 関連情報の要点は、Try Cosmos DB から Azure Cosmos DB Data Explorer を開いたときに、接続文字列を手動で貼り付けなくても自動接続できるようにする変更です。データベース本体、API、RU、パーティション設計が変わる更新ではありません。影響が大きいのは、Try Cosmos DB を使った検証・学習環境、Data Explorer への接続導線、接続文字列を扱う管理ポリシーです。
特に管理者と開発者は、「接続文字列をブラウザー間メッセージで渡す」という仕組みを理解したうえで、キー認証の利用可否、Microsoft Entra ID RBAC との使い分け、postMessage の origin 検証、接続文字列のログ混入防止を確認しておく必要があります。該当する GitHub PR では、Try Cosmos DB が Data Explorer を開き、Data Explorer 側が準備完了メッセージを返した後、接続文字列を postMessage で受け取って接続する流れが示されています。(GitHub)
Azure Cosmos DB documentation updateで何が変わるのか
今回の「Support for connection string deep link from Try Cosmos DB」は、Azure Cosmos DB の利用体験を改善するアップデートです。Azure Cosmos DB Data Explorer は、Azure Cosmos DB に保存されたデータを表示・管理するためのWebベースのインターフェースで、NoSQL、MongoDB、Apache Cassandra、Apache Gremlin、Table に対応しています。Microsoft Learn でも、スタンドアロンの Data Explorer は cosmos.azure.com から利用でき、Azure portal 内の Data Explorer とは別に全画面でデータ参照やクエリ実行を行えることが説明されています。(Microsoft Learn)
今回の変更で重要なのは、「deep link」という名前から想像しがちな「URLに接続文字列を埋め込む方式」ではない点です。PRの説明と差分を見る限り、Try Cosmos DB が window.open() で Data Explorer を開き、Data Explorer が tryCosmosDBReady を返し、その後 Try Cosmos DB 側が tryCosmosDBConnectionString メッセージで接続文字列を渡す構成です。(GitHub)
つまり、ユーザーから見ると「Try Cosmos DB で作成した環境を、Data Explorer ですぐ開ける」ようになります。開発者から見ると、「接続情報をURLではなくブラウザーのメッセージングで渡す連携」が追加された、と捉えるのが正確です。
| 観点 | 変更前 | 変更後 |
|---|---|---|
| Try Cosmos DB から Data Explorer への導線 | Data Explorer を開いた後、接続操作が必要になる可能性がある | Data Explorer 起動後に接続文字列を受け取り、自動接続できる |
| 接続文字列の受け渡し | 手動入力や既存の接続画面が中心 | postMessage によるメッセージ連携が追加 |
| 接続先の検証 | 従来の接続処理に依存 | メッセージ送信元の origin を確認してから処理 |
| Azure Cosmos DB のデータベース機能 | 変更なし | 変更なし |
| アプリケーションのSDK接続 | 変更なし | 変更なし |
実際の接続フロー
今回の実装で想定される流れは、次の4段階です。
| 手順 | 処理 | 実務上の意味 |
|---|---|---|
| 1 | Try Cosmos DB が window.open() で Data Explorer を開く | ユーザー操作をきっかけに新しい Data Explorer 画面を開く |
| 2 | Data Explorer がマウント後、 opener に tryCosmosDBReady を送る | 「接続文字列を受け取る準備ができた」と通知する |
| 3 | Try Cosmos DB が tryCosmosDBConnectionString を返す | 接続文字列を Data Explorer に渡す |
| 4 | Data Explorer が origin を検証し、接続文字列を処理する | 信頼できる送信元からの接続情報だけを受け付ける |
PRのコード差分では、HostedExplorer.tsx にメッセージ待ち受け処理が追加され、event.origin が許可リストに含まれている場合のみ接続文字列を処理する実装になっています。また、接続文字列がリソーストークン形式であれば AuthType.ResourceToken、それ以外は fetchEncryptedToken を経由して AuthType.ConnectionString として扱う処理が追加されています。(GitHub)
あわせて EndpointUtils.ts では、許可された Hosted Explorer の origin が https://cosmos.azure.com と https://localhost:12900 に変更されています。差分上は、従来の https://cosmos.azure.com/ から末尾スラッシュなしの origin へ変わっているため、MessageEvent.origin の形式に合わせた変更と考えられます。(GitHub)
このアップデートの影響範囲
今回の更新は、Azure Cosmos DB アカウントそのものの仕様変更ではありません。影響範囲は主に Data Explorer の接続体験と、Try Cosmos DB からの導線です。
| 対象者 | 影響 | 確認すべきこと |
|---|---|---|
| Azure Cosmos DB 管理者 | 接続文字列を使った Data Explorer 接続が簡単になる | キー認証を許可する運用か、Entra ID RBAC を優先する運用か |
| 開発者 | Try Cosmos DB から検証環境をすぐ開ける | 接続文字列を本番環境で安易に使わないルール |
| 教育・検証環境の担当者 | ハンズオンやデモの手順が短くなる | 参加者に共有する接続情報の権限範囲 |
| Data Explorer を組み込む開発チーム | postMessage 連携の実装・検証が必要 | origin 検証、ポップアップ制御、E2Eテスト |
| 既存アプリの運用担当者 | 通常は直接影響なし | SDK接続、接続文字列管理、キー更新手順は従来通り |
既存アプリケーションのコード、Cosmos DB SDK、コンテナー設計、スループット設定を変更する必要は基本的にありません。今回の変更は、Data Explorer のフロントエンド側で Try Cosmos DB から接続文字列を受け取れるようにするものです。
管理者が確認すべき設定と運用ルール
接続文字列を使う運用を許可しているか
Azure Cosmos DB の接続文字列には、アカウントエンドポイントやキーが含まれる場合があります。Microsoft Learn では、Azure CLI の az cosmosdb keys list でキーや接続文字列を一覧し、az cosmosdb keys regenerate でキーを再生成できることが説明されています。(Microsoft Learn)
Try Cosmos DB や検証環境では接続文字列による接続が便利ですが、企業環境では次の判断が必要です。
| 判断項目 | 推奨される考え方 |
|---|---|
| 本番アカウントの接続文字列をData Explorer連携に使うか | 原則避ける。検証用・学習用・サンドボックス用アカウントに限定する |
| Primary Keyを使うか | 可能ならRead-only key、リソーストークン、または限定スコープの認証を検討する |
| 接続文字列を誰が取得できるか | Azure RBAC、運用手順、監査ルールで制御する |
| 接続文字列を共有するか | チャット、メール、チケット本文への貼り付けを避け、必要最小限にする |
| 検証後のキーをどうするか | デモやハンズオン後はキー再生成を検討する |
接続文字列の利便性が上がるほど、誤って本番キーを使うリスクも上がります。今回の更新を導入する場合は、「Try Cosmos DB や検証環境で使う機能」と「本番運用で許可する接続方法」を分けて考えることが重要です。
キー認証を無効化している環境では期待通りに動かない可能性がある
Azure Cosmos DB for NoSQL では、キー認証を無効化し、Microsoft Entra ID とRBACによる接続を使う構成があります。Microsoft Learn では、Azure Cosmos DB for NoSQL アカウント作成時に Key-based authentication を Disable にして、アプリケーションに Microsoft Entra authentication の利用を求める構成が説明されています。(Microsoft Learn)
このような環境では、接続文字列を渡すだけでは接続できない、または組織のセキュリティポリシーに反する場合があります。Data Explorer 自体は Microsoft Entra 認証を使ったデータ操作にも対応していますが、今回の Try Cosmos DB 連携は「接続文字列を自動で渡す」導線です。キー認証を無効化している本番・準本番環境では、Entra ID RBAC の接続フローを優先して確認してください。
管理プレーンとデータプレーンの権限を混同しない
Azure Cosmos DB では、Azure portal 上でリソースを見られる権限と、コンテナー内のデータを読める権限は同じではありません。Microsoft Learn では、control plane access はアカウントメタデータ、キー、バックアップ、データベースやコンテナー管理などを扱う権限であり、data plane access はアイテムの読み書き、クエリ実行、変更フィードなどのデータ操作を扱う権限だと説明されています。(Microsoft Learn)
Data Explorer で「アカウントは見えるのにデータが読めない」という状態は、管理プレーンのReader権限だけではデータアクセスが足りない場合に起こりやすい問題です。Microsoft Entra ID RBAC を使う場合は、Cosmos DB Built-in Data Reader や Cosmos DB Built-in Data Contributor など、データプレーンのロール割り当てを確認してください。(Microsoft Learn)
開発者が確認すべき実装上の注意点
postMessage では必ず正確な origin を指定する
今回の変更では postMessage が重要な役割を持ちます。MDN Web Docs では、window.postMessage() は異なるWindowオブジェクト間の通信を可能にする一方、targetOrigin はスキーム、ホスト名、ポートまで正確に一致させる必要があり、既知の送信先がある場合は * を使うべきではないと説明されています。(MDN 웹 문서)
Data Explorer 連携を自社サービスや検証ツールに組み込む場合、最低限次のルールを守るべきです。
| 項目 | NG例 | 推奨 |
|---|---|---|
| targetOrigin | * を指定する | https://cosmos.azure.com のように正確な origin を指定する |
| 受信元検証 | event.data.type だけを見る | event.origin と必要に応じて event.source を検証する |
| 接続文字列の扱い | URL、ログ、分析イベントに含める | メモリ上で必要なタイミングだけ扱う |
| メッセージ形式 | 任意のオブジェクトをそのまま信用する | type と connectionString の型・存在を検証する |
| ローカル検証 | 本番originだけで固定する | 開発用originを明示的に分ける |
実装イメージは次のようになります。実際の利用時は、接続文字列をコードに直書きせず、安全な取得元から読み込んでください。
const explorer = window.open("https://cosmos.azure.com/");
window.addEventListener("message", (event) => {
if (event.origin !== "https://cosmos.azure.com") return;
if (event.data?.type === "tryCosmosDBReady") {
explorer?.postMessage(
{
type: "tryCosmosDBConnectionString",
connectionString: connectionStringFromSecureSource
},
"https://cosmos.azure.com"
);
}
});この例で重要なのは、Data Explorer の準備完了メッセージを待ってから接続文字列を送ることです。先に送ってしまうと、Data Explorer 側のリスナーがまだ登録されておらず、接続が成立しない可能性があります。
URLに接続文字列を載せない
今回の実装が postMessage を使っている点は、セキュリティ上も重要です。接続文字列をURLクエリに載せると、ブラウザー履歴、プロキシ、アクセスログ、リファラー、監視ツールなどに残るリスクがあります。
postMessage を使っても接続文字列が完全に安全になるわけではありませんが、少なくともURLに直接露出させるより管理しやすい方式です。開発者は、次のようなログ混入を避けてください。
console.log(connectionString)を残したままにする- Application Insights やフロントエンド分析イベントに接続文字列を含める
- エラーオブジェクトに接続文字列を連結して送信する
- 問い合わせ対応用の画面キャプチャに接続文字列を表示する
- CI/CD の環境変数やテストログに接続文字列を出力する
PRの差分では、接続失敗時に logError が呼ばれています。自社実装で同様のエラーログを追加する場合は、接続文字列そのものを含めず、失敗種別や相関IDだけを記録する設計にしてください。(GitHub)
移行・展開時にやるべき確認
今回の更新により、一般ユーザーがデータ移行を行う必要はありません。ただし、Data Explorer を独自にホストしている、あるいは Azure/cosmos-explorer のコードをフォークしているチームは、該当PRの差分を取り込むかどうかを判断する必要があります。
| 確認項目 | 確認方法 | 期待結果 |
|---|---|---|
| Try Cosmos DB から Data Explorer が開くか | Try Cosmos DB の導線から起動する | ポップアップがブロックされず Data Explorer が表示される |
| 準備完了メッセージを受け取れるか | ブラウザー開発者ツールやE2Eテストで確認する | tryCosmosDBReady を受信できる |
| 接続文字列メッセージを送れるか | 許可された origin に対して送信する | Data Explorer 側が接続処理を開始する |
| origin 検証が効いているか | 未許可originからのメッセージを送るテストを行う | 接続文字列が処理されない |
| リソーストークン形式を扱えるか | リソーストークンの接続文字列で試す | AuthType.ResourceToken として処理される |
| 通常の接続文字列を扱えるか | キー付き接続文字列で試す | encrypted token 取得後に接続される |
| キー認証無効環境で誤用しないか | Entra ID RBAC の環境で検証する | 接続文字列前提の導線を本番運用に混ぜない |
展開前には、成功ケースだけでなく失敗ケースも確認してください。特に、ポップアップブロック、origin の末尾スラッシュ違い、localhost と本番originの混同、キー再生成後の古い接続文字列利用は、検証時に見落としやすいポイントです。
よくあるトラブルと切り分け
| 症状 | 主な原因 | 確認ポイント |
|---|---|---|
| Data Explorer は開くが接続されない | 準備完了前に接続文字列を送っている | tryCosmosDBReady 受信後に送信しているか |
| ローカルでは動くが本番で動かない | origin の許可リストが違う | https://cosmos.azure.com など、末尾スラッシュなしの origin を使っているか |
| 本番では動くがローカルで動かない | 開発用originが許可されていない | https://localhost:12900 などの開発originを分離しているか |
| 接続文字列を送ってもエラーになる | キーが無効、形式が違う、キー認証が無効 | 接続文字列の形式、キー再生成履歴、認証ポリシーを確認 |
| Data Explorer でアカウント切り替えが想定と違う | 接続文字列モードでUI表示が変わる | PR差分では接続文字列がある場合、AccountSwitcherの表示条件が変わっている |
| Azure portalでは見えるがData Explorerでデータが読めない | データプレーン権限不足 | Entra ID RBAC のデータロール割り当てを確認 |
| セキュリティレビューで止まる | 接続文字列の取り扱いルールが未整理 | ログ、URL、分析イベント、画面表示への混入防止を明文化 |
本番環境での使いどころと避けるべき使い方
今回のアップデートは、Try Cosmos DB や学習・検証用途では非常に便利です。たとえば、ハンズオンで参加者が Azure Cosmos DB を試す場合、接続文字列のコピー、接続画面の入力、接続失敗時の再確認といった手順を減らせます。講師やサポート担当者にとっても、環境構築でつまずく時間を短縮できます。
一方、本番環境では「便利だから接続文字列で開けばよい」と考えるのは危険です。管理者は、少なくとも次の線引きを行ってください。
| 用途 | 推奨度 | 理由 |
|---|---|---|
| Try Cosmos DB の一時検証 | 高い | 今回の変更の主な想定ユースケース |
| 社内ハンズオン用サンドボックス | 高い | 環境を限定すれば手順短縮の効果が大きい |
| 開発者の個人検証環境 | 中 | 接続文字列の保存・共有ルールが必要 |
| 準本番データの調査 | 低 | 権限と監査の設計が必要 |
| 本番アカウントの運用作業 | 原則避ける | Entra ID RBAC、監査、承認フローを優先すべき |
本番のデータ確認や障害調査では、個人の接続文字列共有ではなく、Microsoft Entra ID、データプレーンRBAC、承認済みの運用端末、監査可能な手順を使う方が安全です。
この記事のまとめと次に取るべき行動
今回の Azure Cosmos DB documentation update は、Try Cosmos DB から Data Explorer へ接続文字列を渡し、自動接続できるようにする導線改善です。データベースエンジン、API、SDK、コンテナー、RU設定を変更するアップデートではありません。
管理者は、接続文字列を使う範囲、キー認証の可否、Microsoft Entra ID RBAC との使い分け、検証後のキー再生成ルールを確認してください。開発者は、postMessage の targetOrigin を * にしないこと、event.origin を検証すること、接続文字列をURLやログに残さないことを徹底する必要があります。
まずは、検証用の Azure Cosmos DB アカウントまたは Try Cosmos DB 環境で、Data Explorer が自動接続される流れを確認しましょう。そのうえで、本番環境では接続文字列の利便性よりも、RBAC、監査、最小権限、キー管理を優先する運用に整理することが重要です。
コメント