在 iframe 中嵌入 Azure 数据资源管理器 Web UI

适用于：✅Azure 数据资源管理器

可以在 iframe 中嵌入 Azure 数据资源管理器 Web UI，并将其托管在第三方网站中。 本文介绍如何在 iframe 中嵌入 Azure 数据资源管理器 Web UI。

所有功能都针对辅助功能进行了测试，并且支持深色和浅色屏幕主题。

如何在 iframe 中嵌入 Web UI

将以下代码添加到网站：

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

f-IFrameAuth 查询参数告知 Web UI 不要重定向以获取身份验证令牌，f-UseMeControl=false 参数告知 Web UI 不要显示用户帐户信息弹出窗口。 这些操作是必需的，因为托管网站负责身份验证。

workspace=<guid> 查询参数为嵌入的 iframe 创建单独的工作区。 工作区是一个包含选项卡、查询、设置和连接的逻辑单元。 通过将其设置为唯一值，可以防止在 https://dataexplorer.azure.cn 的嵌入式和非嵌入式版本之间共享数据。

处理身份验证

嵌入 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 范围
   群集	query	https://{your_cluster}.{your_region}.kusto.chinacloudapi.cn/.default
   Graph	People.Read	People.Read, User.ReadBasic.All, Group.Read.All
   仪表板	https://rtd-metadata.chinacloudsites.cn/user_impersonation	https://rtd-metadata.chinacloudsites.cn/user_impersonation

   例如，以下函数根据表中的信息映射范围。

       function mapScope(scope) {
           switch(scope) {
               case "query": return ["https://your_cluster.your_region.kusto.chinacloudapi.cn/.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 Entra ID”>“应用注册”。

4. 找到使用代理流的应用并将其打开。

5. 选择“清单”。

6. 选择“requiredResourceAccess”。

7. 在清单中添加以下条目：

     {
       "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
       "resourceAccess": [
           {
               "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
               "type": "Scope"
           }
       ]
     }
   

   • 35e917a9-4d95-4062-9d97-5781291353b9 是 Azure 数据资源管理器仪表板服务的应用程序 ID。
   • 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c 是 user_impersonation 权限。

8. 在“清单”中保存更改。

9. 选择“API 权限”，验证你是否有一个新条目“RTD 元数据服务”。

10. 在“Microsoft Graph”下，添加 People.Read、User.ReadBasic.All 和 Group.Read.All 的权限。

11. 在 Azure PowerShell 中，为应用添加以下新服务主体：

    New-MgServicePrincipal -AppId 35e917a9-4d95-4062-9d97-5781291353b9
    

    如果遇到 Request_MultipleObjectsWithSameKeyValue 错误，则表示该应用已在租户中，这表明已成功添加该应用。

12. 在“API 权限”页中，选择“授予管理员同意”以同意所有用户。

 <iframe src="https://dataexplorer.azure.cn/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.cn/?f-ShowConnectionButtons=false。

相关内容

• Kusto 查询语言 (KQL) 概述
• 编写 Kusto 查询
• 嵌入示例