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

適用於： ✅Microsoft網狀架構✅Azure 數據總管

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

所有功能都會測試輔助功能，並支援螢幕主題的深色和淺色。

如何在 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 時，主控頁面會負責驗證。 下圖描述驗證流程。

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

1. 在您的應用程式中，接 聽 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
      }
   })    
   

2. 定義函式，以將 對應 event.data.scope 至 Microsoft Entra 範圍。 使用下表來決定如何對應 event.data.scope 至 Microsoft Entra 範圍：

   資源	event.data.scope	Microsoft Entra 範圍
   Cluster	query	https://{your_cluster}.{your_region}.kusto.windows.net/.default
   圖表	People.Read	People.Read、 、 User.ReadBasic.AllGroup.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]
           }
       }
   

3. 從範圍執行單頁應用程式 （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） 進行驗證，不支援服務主體。

4. 使用 存取令牌張貼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 數據總管儀錶板服務 （RTD 元數據服務） 之間建立信任關係。

1. 請遵循執行單頁應用程式 （SPA） 驗證中的步驟。

2. 開啟 Azure 入口網站，並確定您已登入正確的租使用者。 在右上角，確認用來登入入口網站的身分識別。

3. 在 [資源] 窗格中，選取 [Microsoft [項目標識符> 應用程式註冊]。

4. 找出使用 代理 者流程的應用程式，並加以開啟。

5. 選取 [ 指令清單]。

6. 選取 requiredResourceAccess。

7. 在指令清單中，新增下列專案：

     {
       "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許可權。

8. 在指令清單中，儲存您的變更。

9. 選取 [API 許可權 ]，並驗證您有新的專案： RTD 元數據服務。

10. 在 [Microsoft Graph] 下，新增 、 User.ReadBasic.All和 Group.Read.All的許可權People.Read。

11. 在 Azure PowerShell 中，為應用程式新增下列新的服務主體：

    New-MgServicePrincipal -AppId 00001111-aaaa-2222-bbbb-3333cccc4444
    

    如果您遇到 Request_MultipleObjectsWithSameKeyValue 錯誤，這表示應用程式已經在租使用者中，指出已成功新增應用程式。

12. 在 [ API 許可權] 頁面中，選取 [ 授與管理員同意 以同意所有使用者]。

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

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

功能旗幟

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

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

相關內容

• Kusto 查詢語言 (KQL) 概觀
• 撰寫 Kusto 查詢
• 內嵌範例