UI 深层链接UI deep links

REST API 提供了一个深层链接功能,该功能允许 HTTP GET 请求将调用方重定向到某个 UI 工具。The REST API provides a deep link functionality that allows HTTP GET requests to redirect the caller to a UI tool. 例如,你可以创建一个用于打开 Kusto.Explorer 工具的 URI,为特定群集和数据库自动配置该工具,运行特定查询并向用户显示其结果。For example, you can craft a URI that opens the Kusto.Explorer tool, auto-configures it for a specific cluster and database, runs a specific query and displays its results to the user.

UI 深层链接 REST API:The UI deep links REST API:

  • 群集(必需)通常隐式定义为实现了 REST API 的服务,但可通过指定 URI 查询参数 uri 来替代群集。Cluster (mandatory) is commonly defined implicitly, as the service that implements the REST API, but can be overridden by specifying the URI query parameter uri.

  • 数据库(可选)指定为 URI 路径的第一个且唯一一个片段。The database (optional) is specified as the first and only fragment of the URI path. 数据库对于查询来说是必需的,对于控制命令来说则是可选的。The database is mandatory for queries and optional for control commands.

  • 查询或控制命令(可选)是使用 URI 查询参数 queryquerysrc(指向保存查询的 Web 资源)指定的。The query or control command (optional) is specified by using the URI query parameter query, or the URI query parameter querysrc (which points at a web resource that holds the query). query 可以在查询或控制命令本身的文本(使用 HTTP 查询参数编码方式进行编码)中使用。query can be used in the text of the query or control command itself (encoded using the HTTP query parameter encoding). 此外,它还可以在查询或控制命令文本的 gzip 的 base64 编码中使用(可以压缩长查询,使其适合默认的浏览器 URI 长度限制)。Alternatively, it can be used in the base64 encoding of the gzip of the query or control command text (making it possible to compress long queries so that they fit the default browser URI length limits).

  • 群集连接的名称(可选)是使用 URI 查询参数 name 指定的。The name of the cluster connection (optional) is specified by using the URI query parameter name.

  • UI 工具是使用 web 可选 URI 查询参数指定的。The UI tool is specified by using the web optional URI query parameter. web=0 表示桌面应用程序 Kusto.Explorer。web=0 indicates the desktop application Kusto.Explorer. web=1 表示 Kusto.WebExplorer Web 应用程序。web=1 indicates the Kusto.WebExplorer web application. web=2 是旧版 Kusto.WebExplorer(基于 Application Insights Analytics)。web=2 is the old version of Kusto.WebExplorer (based in Application Insights Analytics). web=3 是包含空配置文件的 Kusto.WebExplorer(之前打开的选项卡或群集都不可用)。web=3 is the Kusto.WebExplorer with an empty profile (no previously-open tabs or clusters will be available). 最后,可以将 web 查询参数替换为 saw=1,以指示 Kusto.Explorer 的 SAW 版本。Last, the web query parameter can be replaced by saw=1 in order to indicate the SAW version of Kusto.Explorer.

下面是一些链接示例:Here are a few examples for links:

  • https://help.kusto.chinacloudapi.cn/:当用户代理(如浏览器)发出 GET / 请求时,该请求会被重定向到已配置的用来查询 help 群集的默认 UI 工具。https://help.kusto.chinacloudapi.cn/: When a user agent (such as a browser) issues a GET / request it'll be redirected to the default UI tool configured to query the help cluster.
  • https://help.kusto.chinacloudapi.cn/Samples:当用户代理(如浏览器)发出 GET /Samples 请求时,该请求会被重定向到已配置的用来查询 help 群集 Samples 数据库的默认 UI 工具。https://help.kusto.chinacloudapi.cn/Samples: When a user agent (such as a browser) issues a GET /Samples request it'll be redirected to the default UI tool configured to query the help cluster Samples database.
  • http://help.kusto.chinacloudapi.cn/Samples?query=StormEvents:当用户(如浏览器)发出 GET /Samples?query=StormEvents 请求时,该请求会被重定向到已配置的用来查询 help 群集 Samples 数据库的默认 UI 工具,并发出 StormEvents 查询。http://help.kusto.chinacloudapi.cn/Samples?query=StormEvents: When a user (such as a browser) issues a GET /Samples?query=StormEvents request it'll be redirected to the default UI tool configured to query the help cluster Samples database, and issue the StormEvents query.

备注

深层链接 URI 不需要进行身份验证,因为身份验证由用于重定向的 UI 工具执行。The deep link URIs don't require authentication since authentication is performed by the UI tool used for redirection. 任何 Authorization HTTP 标头(如果已提供)都会被忽略。Any Authorization HTTP header, if provided, is ignored.

重要

出于安全原因,UI 工具不会自动执行控制命令,即使在深层链接中指定了 queryquerysrc 也是如此。For security reasons, UI tools do not automatically execute control commands, even if query or querysrc are specified in the deep link.

到 Kusto.Explorer 的深层链接Deep linking to Kusto.Explorer

此 REST API 会执行重定向操作,该操作使用专门设计的启动参数(这些参数可打开与特定 Kusto 引擎群集的连接并对该群集执行查询)来安装和运行 Kusto.Explorer 桌面客户端工具。This REST API performs redirection that installs and runs the Kusto.Explorer desktop client tool with specially-crafted startup parameters that open a connection to a specific Kusto engine cluster and execute a query against that cluster.

  • 路径:/ [ DatabaseName `]Path: / [ DatabaseName `]
  • 谓词:GETVerb: GET
  • 查询字符串:web=0Query string: web=0

备注

有关用于启动 Kusto.Explorer 的重定向 URI 语法的说明,请参阅与 Kusto.Explorer 的深层链接See Deep-linking with Kusto.Explorer for a description of the redirect URI syntax for starting up Kusto.Explorer.

到 Kusto.WebExplorer 的深层链接Deep linking to Kusto.WebExplorer

此 REST API 执行到 Kusto.WebExplorer(一个 Web 应用程序)的重定向。This REST API performs redirection to Kusto.WebExplorer, a web application.

  • 路径:/ [ DatabaseName `]Path: / [ DatabaseName `]
  • 谓词:GETVerb: GET
  • 查询字符串:web=1Query string: web=1

在 URI 中指定查询或控制命令Specifying the query or control command in the URI

当指定了 URI 查询字符串参数 query 时,必须根据 URI 查询字符串编码 HTML 规则对其进行编码。When the URI query string parameter query is specified, it must be encoded according to the URI query string encoding HTML rules. 也可通过 gzip 压缩查询或控制命令的文本,然后通过 base64 编码对其进行编码。Alternatively, the text of the query or control command can be compressed by gzip, and then encoded via base64 encoding. 这样就可以发送更长的查询或控制命令(因为后一种编码方法会生成较短的 URI)。This allows you to send longer queries or control commands (since the latter encoding method results in shorter URIs).

通过间接寻址指定查询或控制命令Specifying the query or control command by indirection

如果查询或控制命令非常长,即使使用 gzip/base64 对其进行编码也会超过用户代理的最大 URI 长度,那么,If the query or control command is very long, even encoding it using gzip/base64 will exceed the maximum URI length of the user agent. 也可提供 URI 查询字符串参数 querysrc,其值是一个短 URI,指向保存查询或控制命令文本的 Web 资源。Alternatively, the URI query string parameter querysrc is provided, and its value is a short URI pointing at a web resource that holds the query or control command text.

例如,它可以是 Azure Blob 存储所承载的文件的 URI。For example, this can be the URI for a file hosted by Azure Blob Storage.

备注

如果深层链接指向 Web 应用程序 UI 工具,则必须将提供查询或控制命令的 Web 服务(即提供 querysrc URI 的服务)配置为支持将 CORS 用于 dataexplorer.azure.cnIf the deep link is to the web application UI tool, the web service providing the query or control command (that is, the service providing the querysrc URI) must be configured to support CORS for dataexplorer.azure.cn.

此外,如果该服务需要身份验证/授权信息,则必须将其作为 URI 本身的一部分提供。Additionally, if authentication/authorization information is required by that service, it must be provided as part of the URI itself.

例如,如果 querysrc 指向 Azure Blob 存储中的 blob,则必须将存储帐户配置为支持 CORS,并使 blob 本身成为公共的(这样就可以在没有安全声明的情况下下载它),或将相应的 Azure 存储 SAS 添加到 URI。For example, if querysrc points at a blob in Azure Blob Storage, one must configure the storage account to support CORS, and either make the blob itself public (so it can be downloaded without security claims) or add an appropriate Azure Storage SAS to the URI. 可通过 Azure 门户Azure 存储资源管理器执行 CORS 配置。CORS configuration can be done from the Azure portal or from Azure Storage Explorer. 请参阅 Azure 存储中的 CORS 支持See CORS support in Azure Storage.