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

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

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

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 时,托管页面负责身份验证。 下图描述了身份验证流。

显示嵌入式 Web UI iframe 身份验证流的示意图。

显示嵌入 Web UI iframe 时所需的范围的示意图。

使用以下步骤处理身份验证:

  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.ReadUser.ReadBasic.AllGroup.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]" />

其中,[feature-flags] 为:

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

功能标志

重要

必须指定 f-IFrameAuth=true 标志才能使 iframe 正常工作。 其他标志是可选项。

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

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

设置 说明 默认值
f-ShowShareMenu 显示“共享”菜单项
f-ShowConnectionButtons 显示用于添加新群集的“添加连接”按钮
f-ShowOpenNewWindowButton 显示“在 Web 中打开”UI 按钮,该按钮打开一个新的浏览器窗口,并指向在作用域中具有适当群集和数据库的 https://dataexplorer.azure.cn false
f-ShowFileMenu 显示文件菜单(“下载”、“选项卡”、“内容”等)
f-ShowToS 在设置对话框中显示“链接到 Azure 数据资源管理器的服务条款”
f-ShowPersona 在右上角的设置菜单中显示用户名。 true
f-UseMeControl 显示用户的帐户信息
f-IFrameAuth 如果为 true,则 Web 浏览器将需要 iframe 来处理身份验证并通过消息来提供令牌。 此参数对于 iframe 方案是必需的。 false
f-PersistAfterEachRun 通常,浏览器在卸载事件中会持久保留。 但是,在 iframe 中托管时并非始终触发卸载事件。 此标志会在每次查询运行之后触发持久保留本地状态事件。 这限制了可能发生的任何数据丢失,以便仅影响从未运行的新查询文本。 false
f-ShowSmoothIngestion 如果为 true,则会在右键单击数据库时显示引入向导体验
f-RefreshConnection 如果为 true,则在加载页面时始终刷新架构,而不依赖于本地存储 false
f-ShowPageHeader 如果为 true,则显示包含 Azure 数据资源管理器标题和设置的页眉
f-HideConnectionPane 如果为 true,则左侧的连接窗格不会显示 false
f-SkipMonacoFocusOnInit 修复了承载在 iframe 上时的焦点问题 false
f-Homepage 启用主页并将新用户重定向到该页面
f-ShowNavigation 如果为 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