在 iframe 中內嵌 Azure Data Explorer Web UI

發行項
01/10/2024

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

Azure Data Explorer 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.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 範圍。使用下表決定如何對應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]
        }
    }

從範圍的 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 入口網站，並確定您已登入正確的租使用者。在右上角，確認用來登入入口網站的身分識別。
在 [資源] 窗格中，選取 [Microsoft Entra 標識符>應用程式註冊。
找出使用代理者流程 的應用程式 ，並加以開啟。
選取 [指令清單]。
選取 requiredResourceAccess。
在指令清單中，新增下列專案：
```
  {
    "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
    "resourceAccess": [
        {
            "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
            "type": "Scope"
        }
    ]
  }
```
- 35e917a9-4d95-4062-9d97-5781291353b9是 Azure Data Explorer 儀錶板服務的應用程式識別碼。
- 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c 是user_impersonation許可權。
在 指令清單中，儲存您的變更。
選取 [API 許可權 ]，並驗證您有新的專案： RTD 元數據服務。
在 [Microsoft Graph] 下，新增、 User.ReadBasic.All和 Group.Read.All的許可權People.Read。
在 Azure PowerShell 中，為應用程式新增下列新的服務主體：
```
New-MgServicePrincipal -AppId 35e917a9-4d95-4062-9d97-5781291353b9
```
如果您遇到 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 必須有旗標才能運作。其他旗標是選擇性的。

裝載應用程式可能會想要控制用戶體驗的某些層面。例如，隱藏連線窗格，或停用與其他叢集之間的連線。在此案例中，Web Explorer 可支援功能旗標。

功能旗標可用於 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	瀏覽器通常會保存在卸除事件中。不過，在 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

如何在 iframe 中內嵌 Web UI

處理驗證

內嵌儀表板

功能旗標

意見反應

意見反應

其他資源

共用方式為

在 iframe 中內嵌 Azure Data Explorer Web UI

如何在 iframe 中內嵌 Web UI

處理驗證

內嵌儀表板

功能旗標

相關內容

意見反應

意見反應

其他資源