在 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.origin === "https://dataexplorer.azure.cn" && 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. 从 Perform Single Page Application (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
        }, 'https://dataexplorer.azure.cn'); 
      }
   

   重要

   托管窗口必须在过期之前通过发送包含更新令牌的新 postToken 消息来刷新令牌。 否则，令牌过期后，服务调用将失败。

嵌入仪表板

若要嵌入仪表板，必须在主机的Microsoft Entra 应用与 Azure 数据资源管理器仪表板服务（RTD 元数据服务）之间建立信任关系。

1. 执行执行单页应用程序 (SPA) 身份验证中的步骤。

2. 打开 Azure 门户 ，确保登录到正确的租户。 在右上角，验证用于登录的身份。

3. 在资源窗格中，选择Microsoft Entra ID>应用注册。

4. 找到使用On-Behalf-Of流的应用并将其打开。

5. 选择“清单”。

6. 选择requiredResourceAccess。

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

   重要

   将 <RTD Metadata Service - Application ID> 替换为 RTD 元数据服务 的应用程序 ID。 若要获取此服务的应用程序 ID，请执行以下步骤：

   • 登录到 Azure 门户。
   • 在搜索栏中，输入 RTD 元数据服务，然后选择 服务主体： RTD 元数据服务。
   • 在 RTD 元数据服务的“企业应用程序”页上，记下应用程序 ID 的值。

     {
       "resourceAppId": "<RTD Metadata Service - Application ID>",
       "resourceAccess": [
           {
               "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
               "type": "Scope"
           }
       ]
     }
   

   在上述代码中，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中，为应用添加以下新服务主体：

    重要

    替换为 <RTD Metadata Service - Application ID> 之前获取的 RTD 元数据服务 的应用程序 ID。

    New-MgServicePrincipal -AppId <RTD Metadata Service - Application ID>
    

    如果您遇到 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,

嵌入 Azure Maps 渲染

为了呈现 Azure Maps 视觉对象，宿主应用程序通过 postMessage 提供 Azure Maps 共享访问签名（SAS）令牌。 这与Microsoft Entra身份验证分开;保留现有getToken处理程序。

1. 创建Azure Maps帐户和生成短生存期 SAS 令牌的后端终结点。

2. 扩展消息处理程序以接受带有 signature: "queryExplorer" 和字符串 requestId 的 getMapsToken 消息。 在获取令牌之前，请验证 event.origin 是否为 event.source，并且 https://dataexplorer.azure.cn 是你的 iframe 的 contentWindow。

3. 在带有相同请求 ID 的 postMapsToken 消息中返回 SAS 令牌。 在此示例中，iframeWindow 是 iframe 的 contentWindow，mapsSasToken 是从您的后端获取的令牌：

   iframeWindow.postMessage({
     signature: "queryExplorer",
     type: "postMapsToken",
     requestId: event.data.requestId,
     token: mapsSasToken
   }, "https://dataexplorer.azure.cn");
   

在 10 秒内响应。 失败时，发送 error: "mapsTokenUnavailable" 而不是 token。 Web UI 在需要时请求新令牌，因此请保持该处理程序处于注册状态，并通过后端续订令牌。

若要在截止时间之前测试新行为，请将f-IFrameAuth=true与f-enableAzureMapsSecureToken=true一起添加到 iframe URL 中。 2026 年 11 月 1 日， f-enableAzureMapsSecureToken 默认启用。

使用这些资源设置和测试 SAS 身份验证：

• 将数据引入视图控件 - Azure Maps Web SDK 示例 - 使用 SAS 令牌身份验证的示例。
• Azure函数代码 - 仅包含令牌生成逻辑；在将其用于嵌入式 Web UI 之前，请将其匿名触发器和示例站点Referer检查替换为主机应用程序的身份验证和来源检查。

功能标志

托管应用可能想要控制用户体验的某些方面。 例如，隐藏连接窗格或禁止连接到其他群集。 针对这种情况，Web 浏览器支持功能标志。

功能标志可在 URL 中用作查询参数。 若要禁用添加其他群集，请在托管应用中使用 https://dataexplorer.azure.cn/?f-ShowConnectionButtons=false。

相关内容

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