iframe への Azure Data Explorer Web UI の埋め込み

[アーティクル]
12/08/2023

Azure Data Explorer Web UI を iframe に埋め込んで、サードパーティの Web サイトでホストできます。この記事では、Azure Data Explorer Web UI を iframe に埋め込む方法について説明します。

Azure Data Explorer Web UI のスクリーンショット。

すべての機能のアクセシビリティがテストされ、すべての機能が画面テーマのダークとライトをサポートします。

Web UI を iframe に埋め込む方法

Web サイトに次のコードを追加します。

<iframe
  src="https://dataexplorer.azure.com/?f-IFrameAuth=true&f-UseMeControl=false&workspace=<guid>"
></iframe>

クエリパラメーターは f-IFrameAuth 、認証トークンを取得するためにリダイレクト しないように Web UI に指示し、 f-UseMeControl=false パラメーターはユーザーアカウント情報ポップアップウィンドウを表示 しないように Web UI に指示します。これらのアクションは、ホスティング Web サイトが認証を担当するため必要です。

クエリパラメーターは workspace=<guid> 、埋め込み iframe 用に別のワークスペースを作成します。ワークスペースは、タブ、クエリ、設定、接続を含むロジックユニットです。これを一意の値に設定すると、埋め込みバージョンと非埋め込みバージョンの間でデータが共有されるの https://dataexplorer.azure.comを防ぐことができます。

認証の処理

Web UI を埋め込む場合、ホスティングページは認証を担当します。次の図では、認証フローについて説明します。

認証を処理するには、次の手順に従います。

アプリケーションで、 getToken メッセージをリッスンします。

window.addEventListener('message', (event) => {
   if (event.data.signature === "queryExplorer" && event.data.type === "getToken") {
     // CODE-1: Replace this placeholder with code to get the access token from Microsoft Entra ID and
     //         then post a "postToken" message with an access token and an event.data.scope
   }
})

をスコープにマップevent.data.scopeする関数Microsoft Entra定義します。次の表を使用して、Microsoft Entraスコープにマップevent.data.scopeする方法を決定します。

リソース	event.data.scope	スコープMicrosoft Entra
クラスター	`query`	`https://{your_cluster}.{your_region}.kusto.windows.net/.default`
グラフ	`People.Read`	`People.Read`, `User.ReadBasic.All`, `Group.Read.All`
ダッシュボード	`https://rtd-metadata.azurewebsites.net/user_impersonation`	`https://rtd-metadata.azurewebsites.net/user_impersonation`

たとえば、次の関数は、テーブル内の情報に基づいてスコープをマップします。

    function mapScope(scope) {
        switch(scope) {
            case "query": return ["https://your_cluster.your_region.kusto.windows.net/.default"];
            case "People.Read": return ["People.Read", "User.ReadBasic.All", "Group.Read.All"];
            default: return [scope]
        }
    }

スコープのMicrosoft Entra認証エンドポイントから JWT アクセストークンを取得します。このコードは、プレースホルダー CODE-1 を置き換えます。

たとえば、を使用 @azure/MSAL-react してアクセストークンを取得できます。この例では、前に定義した mapScope 関数を使用します。
```
import { useMsal } from "@azure/msal-react";
const { instance, accounts } = useMsal();

instance.acquireTokenSilent({
  scopes: mapScope(event.data.scope),
  account: accounts[0],
})
.then((response) =>
    var accessToken = response.accessToken
    // - CODE-2: Replace this placeholder with code to post a "postToken" message with an access token and an event.data.scope
)
```
重要

ユーザープリンシパル名 (UPN) は認証にのみ使用できます。サービスプリンシパルはサポートされていません。
アクセストークンを含む postToken メッセージを投稿します。このコードは、プレースホルダー CODE-2 を置き換えます。
```
     iframeWindow.postMessage({
         "type": "postToken",
         "message": // the access token your obtained earlier
         "scope": // event.data.scope as passed to the "getToken" message
     }, '*');
   }
```
重要

ホスティングウィンドウでは、更新されたトークンを含む新しい postToken メッセージを送信することで、有効期限が切る前にトークンを更新する必要があります。それ以外の場合、トークンの有効期限が切れると、サービス呼び出しは失敗します。

ヒント

このサンプルプロジェクトでは、認証を使用するアプリケーションを表示できます。

ダッシュボードを埋め込む

ダッシュボードを埋め込むには、ホストのMicrosoft Entra アプリと Azure Data Explorer ダッシュボードサービス (RTD メタデータサービス) の間に信頼関係が確立されている必要があります。

Web クライアント (JavaScript) の認証と承認の手順に従います。
Azure portalを開き、正しいテナントにサインインしていることを確認します。右上隅で、ポータルへのサインインに使用される ID を確認します。
リソースウィンドウで、[MICROSOFT ENTRA ID>アプリの登録 を選択します。
代理フローを使用するアプリを見つけて開きます。
[マニフェスト] を選びます。
[requiredResourceAccess] を選びます。
マニフェストで、次のエントリを追加します。
```
  {
    "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 35e917a9-4d95-4062-9d97-5781291353b9は、Azure Data Explorer ダッシュボードサービスのアプリケーション ID です。
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c は、user_impersonationのアクセス許可です。
マニフェストで、変更を保存します。
[ API のアクセス許可] を選択し、新しいエントリ ( RTD メタデータサービス) があることを確認します。
[Microsoft Graph] で、、、およびのアクセス許可をPeople.ReadUser.ReadBasic.All追加しますGroup.Read.All。
Azure PowerShellで、アプリの次の新しいサービスプリンシパルを追加します。
```
New-MgServicePrincipal -AppId 35e917a9-4d95-4062-9d97-5781291353b9
```
エラーが発生した Request_MultipleObjectsWithSameKeyValue 場合は、アプリが正常に追加されたことを示すテナントに既に存在することを意味します。
[ API のアクセス許可 ] ページで、[すべてのユーザーの 同意に管理者の同意を付与 する] を選択します。

Note

クエリ領域のないダッシュボードを埋め込むには、次の設定を使用します。

 <iframe src="https://dataexplorer.azure.com/dashboards?[feature-flags]" />

ここで [feature-flags] 、は次のとおりです。

"f-IFrameAuth": true,
"f-PersistAfterEachRun": true,
"f-Homepage": false,
"f-ShowPageHeader": false,
"f-ShowNavigation": false,
"f-DisableExploreQuery": false,

機能フラグ

重要

f-IFrameAuth=true iframe を機能させるには、フラグが必要です。その他のフラグは省略可能です。

ホスティングアプリは、ユーザーエクスペリエンスの特定の側面を制御する必要がある場合があります。たとえば、接続ペインを非表示にしたり、他のクラスターへの接続を無効にしたりできます。このシナリオでは、Web エクスプローラーは機能フラグをサポートします。

機能フラグは URL でクエリパラメーターとして使用できます。他のクラスターの追加を無効にするには、ホスティングアプリでを使用 https://dataexplorer.azure.com/?f-ShowConnectionButtons=false します。

設定	説明	既定値
f-ShowShareMenu	共有メニュー項目を表示します	true
f-ShowConnectionButtons	新しいクラスターを追加するための[接続の追加] ボタンを表示します	true
f-ShowOpenNewWindowButton	新しいブラウザーウィンドウを開くための [Web で開く] UI ボタンを表示し、スコープ内の適切なクラスターとデータベースが存在する https://dataexplorer.azure.com をポイントします	false
f-ShowFileMenu	[ファイル] メニュー ([ダウンロード]、[タブ]、[コンテンツ] など) を表示します	true
f-ShowToS	[設定] ダイアログで Azure Data Explorer のサービス使用条件へのリンクを表示します	true
f-ShowPersona	右上隅の設定メニューからユーザー名を表示します。	TRUE
f-UseMeControl	ユーザーのアカウント情報を表示する	true
f-IFrameAuth	true の場合、Web エクスプローラーは iframe が認証を処理し、メッセージを介してトークンを提供することを想定しています。このパラメーターは、iframe シナリオに必要です。	false
f-PersistAfterEachRun	通常、ブラウザーは unload イベントで保持されます。ただし、iframe でホストするときにアンロードイベントが常にトリガーされるとは限りません。このフラグは、各クエリの実行後に永続化ローカル状態イベントをトリガーします。これにより、発生する可能性のあるデータ損失が、実行されていない新しいクエリテキストにのみ影響するように制限されます。	false
f-ShowSmoothIngestion	true の場合、データベースを右クリックしたときにインジェストウィザードエクスペリエンスを表示します	true
f-RefreshConnection	true の場合は、ページの読み込み時に常にスキーマを更新し、ローカルストレージに依存することはありません	false
f-ShowPageHeader	true の場合は、Azure Data Explorer のタイトルと設定を含むページヘッダーを表示します	true
f-HideConnectionPane	true の場合、左側の接続ペインは表示されません	false
f-SkipMonacoFocusOnInit	iframe でホストするときのフォーカスの問題を修正します	false
f-Homepage	ホームページと、それへの新しいユーザーの再ルーティングを有効にします	true
f-ShowNavigation	true の場合、左側にナビゲーションウィンドウが表示されます	true
f-DisableDashboardTopBar	true の場合、ダッシュボードの上部のバーが非表示になります	false
f-DisableNewDashboard	true の場合、新しいダッシュボードを追加するオプションが非表示になります	false
f-DisableNewDashboard	true の場合、ダッシュボードの一覧で検索するオプションが非表示になります	false
f-DisableDashboardEditMenu	true の場合、ダッシュボードを編集するオプションが非表示になります	false
f-DisableDashboardFileMenu	true の場合、ダッシュボードのファイルメニューボタンが非表示になります	false
f-DisableDashboardShareMenu	true の場合、ダッシュボードの共有メニューボタンが非表示になります	false
f-DisableDashboardDelete	true の場合、ダッシュボードの削除ボタンが非表示になります	false
f-DisableTileRefresh	true の場合、ダッシュボードのタイル更新ボタンが無効になります	false
f-DisableDashboardAutoRefresh	true の場合、ダッシュボードのタイルの自動更新が無効になります	false
f-DisableExploreQuery	true の場合、タイルのクエリ探索ボタンが無効になります	false
f-DisableCrossFiltering	true の場合、ダッシュボードのクロスフィルター機能が無効になります	false
f-HideDashboardParametersBar	true の場合、ダッシュボードのパラメーターバーが非表示になります	false

iframe への Azure Data Explorer Web UI の埋め込み

Web UI を iframe に埋め込む方法

認証の処理

ダッシュボードを埋め込む

機能フラグ

フィードバック

フィードバック

その他のリソース

iframe への Azure Data Explorer Web UI の埋め込み

Web UI を iframe に埋め込む方法

認証の処理

ダッシュボードを埋め込む

機能フラグ

関連コンテンツ

フィードバック

フィードバック

その他のリソース