在 iframe 中嵌入 Web UIEmbed Web UI in an iframe

可以在 iframe 中嵌入 Azure 数据资源管理器 Web UI,并将其承载在第三方网站中。The Azure Data Explorer Web UI can be embedded in an iframe and hosted in third-party websites.

Azure 数据资源管理器 Web UI

在网站中嵌入 Azure 数据资源管理器 Web UX 后,你的用户就可以执行以下操作:Embedding the Azure Data Explorer Web UX in your website enables your users to:

  • 编辑查询(包括所有语言功能,例如着色和 intellisense)Edit queries (includes all language features such as colorization and intellisense)
  • 直观地浏览表架构Explore table schemas visually
  • 向 Azure AD 进行身份验证Authenticate to Azure AD
  • 执行查询Execute queries
  • 显示查询执行结果Display query execution results
  • 创建多个选项卡Create multiple tabs
  • 在本地保存查询Save queries locally
  • 通过电子邮件共享查询Share queries by email

所有功能都针对辅助功能进行了测试,并且支持深色和浅色屏幕主题。All functionality is tested for accessibility and supports dark and light on-screen themes.

使用 Monaco-Kusto 还是嵌入 Web UI?Use Monaco-Kusto or embed the Web UI?

Monaco-Kusto 提供编辑体验,例如完成、着色、重构、重命名和“转到定义”。Monaco-Kusto offers you an editing experience such as completion, colorization, refactoring, renaming, and go-to-definition. 它要求你针对身份验证、查询执行、结果显示和架构探索来构建解决方案,但你可以十分灵活地根据自己的需要改变用户体验。It requires you to build a solution for authentication, query execution, result display, and schema exploration, but offers you full flexibility to fashion the user experience that fits your needs.

通过嵌入 Azure 数据资源管理器 Web UI,可以很轻松地实现丰富的功能,但针对用户体验提供的灵活性有限。Embedding the Azure Data Explorer Web UI offers you extensive functionality with little effort, but contains limited flexibility for the user experience. 可以通过一组固定的查询参数对系统的外观和行为进行有限的控制。There's a fixed set of query parameters that enable limited control over the system's look and behavior.

如何在 iframe 中嵌入 Web UIHow to embed the Web UI in an iframe

将网站承载在 iframe 中Host the website in an iframe

将以下代码添加到网站:Add the following code to your website:

<iframe
  src="https://dataexplorer.azure.cn/clusters/<cluster>?ibizaPortal=true"
></iframe>

ibizaPortal 查询参数告知 Azure 数据资源管理器 Web UI 不要通过重定向来获取身份验证令牌。The ibizaPortal query parameter tells the Azure Data Explorer Web UI not to redirect to get an authentication token. 此操作是必需的,因为承载网站负责为嵌入的 iframe 提供身份验证令牌。This action is necessary, since the hosting website is responsible for providing an authentication token to the embedded iframe.

<cluster> 替换为要加载到连接窗格中的群集的主机名,例如 help.kusto.chinacloudapi.cnReplace <cluster> with the hostname of the cluster you want to load into the connection pane, such as help.kusto.chinacloudapi.cn. 默认情况下,iframe 嵌入模式不提供从 UI 添加群集的方法,因为假定承载网站知道所需的群集。By default, iframe-embedded mode doesn't provide a way to add clusters from the UI, since the assumption is that the hosting website is aware of the required cluster.

处理身份验证Handle authentication

  1. 如果设置为“iframe 模式”(ibizaPortal=true),则 Azure 数据资源管理器 Web UI 不会尝试通过重定向进行身份验证。When set to 'iframe mode' (ibizaPortal=true), The Azure Data Explorer Web UI won't try to redirect for authentication. Web UI 将使用浏览器所用的消息发布机制来请求和接收令牌。The Web UI will use the message posting mechanism that browsers use, to request and receive a token. 在页面加载过程中,以下消息将发布到父窗口:During page loading, the following message will be posted to the parent window:

    window.parent.postMessage(
      {
        signature: "queryExplorer",
        type: "getToken"
      },
      "*"
    );
    window.addEventListener(
      "message",
      event => this.handleIncomingMessage(event),
      false
    );
    
  2. 然后,它将侦听具有以下结构的消息:Then, it will listen for a message with the following structure:

    {
      "type": "postToken",
      "message": "${the actual authentication token}"
    }
    
  3. 提供的令牌应该是从 [AAD 身份验证终结点]获取的 JWT 令牌The provided token should be a JWT token obtained from the [AAD authentication endpoint].

重要

承载窗口必须在过期之前刷新令牌,并使用同一机制为应用程序提供更新的令牌。The hosting window must refresh the token before expiration and use the same mechanism to provide the updated token to the application. 否则,在令牌过期后,服务调用将失败。Otherwise, once the token expires, service calls will fail.

功能标志Feature flags

承载应用程序可能希望控制用户体验的某些方面。The hosting application may want to control certain aspects of the user experience. 例如,隐藏连接窗格或禁止连接到其他群集。For example, hide the connection pane, or disable connecting to other clusters. 针对这种情况,Web 浏览器支持功能标志。For this scenario, the web explorer supports feature flags.

功能标志可在 URL 中用作查询参数。A feature flag can be used in the url as a query parameter. 如果承载应用程序希望禁止添加其他群集,它应使用 https://dataexplorer.azure.cn/?ShowConnectionButtons=falseIf the hosting application wants to disable adding other clusters, it should use https://dataexplorer.azure.cn/?ShowConnectionButtons=false

设置setting 说明Description 默认值Default Value
ShowShareMenuShowShareMenu 显示“共享”菜单项Show the share menu item true
ShowConnectionButtonsShowConnectionButtons 显示用于添加新群集的“添加连接”按钮Show the add connection button to add a new cluster true
ShowOpenNewWindowButtonShowOpenNewWindowButton 显示“在 Web 中打开”UI 按钮,该按钮打开一个新的浏览器窗口,并指向在作用域中具有适当群集和数据库的 https://dataexplorer.azure.cnShow the open in web UI button, that opens a new browser window and point to https://dataexplorer.azure.cn with the right cluster and database in scope falsefalse
ShowFileMenuShowFileMenu 显示文件菜单(“下载”、“选项卡”、“内容”等)Show the file menu (download, tab, content, and so on) true
ShowToSShowToS 在设置对话框中显示“链接到 Azure 数据资源管理器的服务条款”Show link to the terms of service for Azure Data Explorer from the settings dialog true
ShowPersonaShowPersona 在右上角的设置菜单中显示用户名Show the user name from the settings menu, in the top-right corner true
IFrameAuthIFrameAuth 如果为 true,则 Web 浏览器将指望 iframe 来处理身份验证并通过消息来提供令牌。If true, the web explorer will expect the iframe to handle authentication and provide a token via a message. 对于 iframe 方案,此过程将始终为 trueThis process will always be true for iframe scenarios falsefalse
PersistAfterEachRunPersistAfterEachRun 通常,Web 浏览器在卸载事件中会持久保留。Usually the web explorer will persist in the unload event. 当承载在 iframe 中时,它并不总是激发。When hosting in iframes, it doesn't always fire. 此标志会在每次运行查询后触发“保留本地状态”。This flag will then trigger persisting local state after each query run. 因此,数据丢失只会影响从未运行过的文本,因而其影响有限As a result, any data loss that occurs, will only affect text that had never been run, thus limiting its impact falsefalse
ShowSmoothIngestionShowSmoothIngestion 如果为 true,则在右键单击数据库时显示一键式引入体验If true, show the 1-click ingestion experience when right-clicking on a database true
RefreshConnectionRefreshConnection 如果为 true,则在加载页面时始终刷新架构,而不依赖于本地存储If true, always refreshes the schema when loading the page and never depends on local storage falsefalse
ShowPageHeaderShowPageHeader 如果为 true,则显示包含 Azure 数据资源管理器标题和设置的页眉If true, shows the page header that includes the Azure Data Explorer title and settings true
HideConnectionPaneHideConnectionPane 如果为 true,则左侧的连接窗格不会显示If true, the left connection pane doesn't display falsefalse
SkipMonacoFocusOnInitSkipMonacoFocusOnInit 修复了承载在 iframe 上时的焦点问题Fixes the focus issue when hosting on iframe falsefalse

功能标志预设Feature flag presets

预设可一次性设置一组功能标志。Presets will set a bunch of feature flags at once. 目前只有一个预设。Currently, there's only a single preset.

IbizaPortal - 在默认设置中更改以下标志。IbizaPortal - Changes the following flags from the defaults.

ShowOpenNewWindowButton: true,
PersistAfterEachRun: true,
IFrameAuth: true,
ShowPageHeader: false,                                 |

警告

如果使用预设,将无法在其基础上添加其他功能标志。If you use a preset, you won't be able to add additional feature flags on top of it. 如果你需要能够灵活地添加其他功能标志,则应使用单独的功能标志。If you need that flexibility, you should use individual feature flags.