在 iframe 中內嵌 Azure 數據總管 Web UI

2025-05-04

適用於： ✅Microsoft Fabric✅Azure 資料探查器

Azure 數據總管 Web UI 可以內嵌在 iframe 中，並裝載於第三方網站。本文說明如何在 iframe 中內嵌 Azure 數據總管 Web UI。

Azure 資料總管 Web U I 的螢幕快照。

所有功能都已進行無障礙測試，並支援螢幕上的深色和淺色主題。

如何在 iframe 中內嵌 Web UI

將下列程式代碼新增至您的網站：

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

查詢 f-IFrameAuth 參數會告知 Web UI 不要重新導向以取得驗證令牌，而 f-UseMeControl=false 參數會告知 Web UI 不要顯示使用者帳戶資訊彈出視窗。由於裝載網站負責驗證，因此需要執行這些動作。

workspace=<guid>查詢參數會為內嵌 iframe 建立個別的工作區。工作區是一個邏輯單元，其中包含索引標籤、查詢、設定和連線。將它設定為唯一值，可防止內嵌與非內嵌版本 https://dataexplorer.azure.com之間的數據共用。

處理身份驗證

內嵌 Web UI 時，主控頁面會負責驗證。下圖描述驗證流程。

使用下列步驟來處理驗證：

在您的應用程式中，聽取 getToken 訊息。

window.addEventListener('message', (event) => {
   if (event.origin === "https://dataexplorer.azure.com" && 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 範圍。使用下表來決定如何對應 event.data.scope 至 Microsoft Entra 範疇：

資源	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]
        }
    }

從單頁應用程式（SPA）認證過程中，為該範圍取得 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）進行驗證，不支援服務主體。

請使用 access token 張貼 postToken 訊息。此程式碼會取代佔位元 CODE-2：
```
     iframeWindow.postMessage({
         "type": "postToken",
         "message": // the access token your obtained earlier
         "scope": // event.data.scope as passed to the "getToken" message
     }, 'https://dataexplorer.azure.com'); 
   }
```
重要

裝載窗口必須在到期前重新整理令牌，方法是傳送具有更新令牌的新 postToken 訊息。否則，令牌到期后，服務呼叫將會失敗。

提示

在我們的範例專案中，您可以檢視使用驗證的應用程式。

內嵌儀表板

若要內嵌儀錶板，必須在主機的 Microsoft Entra 應用程式和 Azure 數據總管儀錶板服務（RTD 元數據服務）之間建立信任關係。

請遵循在執行單頁應用程式（SPA）驗證中提到的步驟。
開啟 Azure 入口網站，並確定您已登入正確的租使用者。在右上角，確認用來登入入口網站的身份。
在 [資源] 窗格中，選取 [Microsoft Entra ID]>[應用程式註冊]。
找出使用代為流程的應用程式，然後開啟它。
選取清單。
選取 requiredResourceAccess。

在清單中，新增下列條目：

  {
    "resourceAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }

00001111-aaaa-2222-bbbb-3333cccc4444 是 Azure 資料總管儀錶板服務的應用程式識別碼。
388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c 是 user_impersonation 許可權。

在清單中儲存您的變更。
選取 API 權限，並驗證您有新的專案：RTD 元數據服務。
在 Microsoft Graph 下，為 People.Read 、User.ReadBasic.All 和 Group.Read.All 新增許可權。
在 Azure PowerShell 中，為應用程式新增下列新的服務主體：
```
New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444
```
如果您遇到 Request_MultipleObjectsWithSameKeyValue 錯誤，這表示應用程式已經在租戶中，表示應用程式已成功新增。
在 [ API 許可權] 頁面中，選取 [ 授與管理員同意 以同意所有使用者]。

注意

若要內嵌沒有查詢區域的儀錶板，請使用下列設定：

 <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,

功能旗幟

重要

iframe 必須有 f-IFrameAuth=true 標誌才能運作。其他旗標是選擇性的。

裝載應用程式可能想要控制用戶體驗的某些層面。例如，隱藏連接窗格，或停用與其他叢集的連線。在此案例中，網頁瀏覽器支援功能標誌。

功能旗標可以在 URL 中當做查詢參數使用。若要停用新增其他叢集，請在主控應用程式中使用 https://dataexplorer.azure.com/?f-ShowConnectionButtons=false 。

設定	描述:	預設值
f-顯示分享選單	顯示共用選單項目	是
f-顯示連接按鈕	顯示 [ 新增連線] 按鈕以新增叢集	是
f-顯示開啟新視窗按鈕	顯示「在網頁中開啟」UI 按鈕，這個按鈕將開啟新的瀏覽器視窗，並指向範圍內正確的叢集與資料庫。	假的
顯示檔案選單	顯示檔案選單（下載、索引標籤、內容等等）	是
f-ShowToS	從 [設定] 對話框顯示 Azure 資料探索器服務條款的連結	是
f-ShowPersona	在右上角的 [設定] 選單中顯示使用者名稱。	是
f-UseMeControl	顯示用戶帳戶資訊	是
f-IFrameAuth	如果為 true，網頁瀏覽器探索者預計 iframe 會處理驗證，並透過訊息提供令牌。 iframe 案例需要此參數。	假的
f-PersistAfterEachRun	瀏覽器通常會在卸載事件中保留狀態。不過，在 iframe 中裝載時，不會一律觸發卸載事件。此旗標會在每次查詢執行之後觸發本機狀態的保存事件。這會將可能發生的任何數據遺失限制為只會影響從未執行的新查詢文字。	假的
f-ShowSmoothIngestion	如果為 true，請在資料庫上按下滑鼠右鍵時顯示擷取精靈體驗	是
f-RefreshConnection	如果為 true，則在載入頁面時總是重新整理架構，且永遠不會相依於本機儲存。	假的
f-顯示頁面標題	如果為 true，則顯示包含 Azure 數據總管標題和設定的頁面標頭	是
f-隱藏連接窗格	如果為 true，則不會顯示左連接窗格	假的
f-SkipMonacoFocusOnInit	修正在 iframe 上裝載時的焦點問題	假的
首頁	啟用首頁並將新使用者重新導向至首頁	是
f-顯示導航	如果為 true，則顯示左側的瀏覽窗格	是
f-DisableDashboardTopBar	如果為 true，則會隱藏儀錶板中的頂端列	假的
f-禁用新儀表板	如果為 true，則會隱藏新增儀錶板的選項	假的
f-DisableDashboardEditMenu	如果為 true，則會隱藏編輯儀錶板的選項	假的
f-停用儀表板檔案選單	如果為 true，則會隱藏儀錶板中的 [檔案] 功能表按鈕	假的
禁用儀表板分享菜單	如果為 true，則會隱藏儀錶板中的共用功能表按鈕	假的
f-停用儀表板刪除	如果為 true，則會隱藏儀錶板刪除按鈕	假的
f-DisableTileRefresh	如果為 true，則會停用儀錶板中的圖塊重新整理按鈕	假的
f-DisableDashboardAutoRefresh	如果為 true，則會停用儀錶板中的圖塊自動更新	假的
f-停用探索查詢	當為 true 時，停用圖塊的探索查詢按鈕	假的
停用交叉篩選	如果為 true，則會停用儀錶板中的交叉篩選功能	假的
隱藏儀表板參數欄	如果為 true，則會隱藏儀錶板中的參數列	假的

共用方式為

在 iframe 中內嵌 Azure 數據總管 Web UI

如何在 iframe 中內嵌 Web UI

處理身份驗證

內嵌儀表板

功能旗幟

相關內容

意見反應

其他資源