查询参数声明语句

使用 “版本 ”下拉列表切换服务。 了解有关导航的详细信息。
适用于：✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

发送到 Kusto 的查询可以包含一组名称或值对。 这些对与查询文本自身一起被称为查询参数。 查询可以通过在查询参数声明语句中指定名称和类型来引用一个或多个值。

查询参数有两个主要用途：

  • 用作防范注入攻击的保护机制。
  • 用作对查询进行参数化的方式。

具体而言，如果客户端应用程序在查询中组合了用户提供的输入，然后将查询发送到 Kusto，则客户端应用程序应使用该机制来防止与 SQL 注入攻击相当的 Kusto 攻击。

声明查询参数

若要引用查询参数、查询文本或它使用的函数，必须首先声明它使用哪个查询参数。 对于每个参数，声明都提供名称和标量类型。 此外，参数还可以具有默认值。 如果请求未提供参数的具体值，则会使用默认值。 然后，Kusto 根据该类型的常规分析规则来分析查询参数的值。

语法

declare query_parameters ( Name1:Type1 [=DefaultValue1] [,...] );

详细了解语法约定。

参数

客户 类型 必需 说明
Name1 string ✔️ 查询中使用的查询参数的名称。
Type1 string ✔️ 对应的类型，例如 string 或 datetime。 用户提供的值将编码为字符串。 适当的分析方法应用于查询参数以获取强类型值。
DefaultValue1 string 参数的默认值。 此值必须是合适标量类型的文本。

注意

  • 与用户定义的函数一样，dynamic 类型的查询参数不能具有默认值。
  • Let、set 和 tabular 语句用分号串在一起/分隔，否则它们将不被视为同一查询的一部分。

示例

本节中的示例演示如何使用语法来帮助get started。

本文中的示例使用 help 群集中的公开可用的表，例如 Samples 数据库中的 StormEvents 表。

声明查询参数

此查询从 StormEvents 表中检索风暴事件，其中直接和间接伤害总数超过指定的阈值（默认值为 90）。 然后，它投影 EpisodeId、EventType，以及每个事件的伤害总数。

运行查询

declare query_parameters(maxInjured:long = 90);
StormEvents 
| where InjuriesDirect + InjuriesIndirect > maxInjured
| project EpisodeId, EventType, totalInjuries = InjuriesDirect + InjuriesIndirect

输出

EpisodeId 事件类型 totalInjuries
12459 冬季天气 137
10477 极高温 200
10391 热 187
10217 极高温 422
10217 极高温 519

在客户端应用程序中指定查询参数

查询参数的名称和值由进行查询的应用程序作为 string 值提供。 名称不可以重复。

值的解释根据查询参数声明语句来完成。 每个值都作为查询正文中的文本进行分析。 分析根据查询参数声明语句指定的类型来完成。

REST API

查询参数由客户端应用程序通过请求正文的 JSON 对象的 properties 槽在名为 Parameters 的嵌套属性包中提供。 例如，下面是对 Kusto 的一个 REST API 调用的正文，该调用会计算某个用户的年龄（可能是采用让应用程序询问用户的生日的方式）。

{
    "ns": null,
    "db": "myDB",
    "csl": "declare query_parameters(birthday:datetime); print strcat(\"Your age is: \", tostring(now() - birthday))",
    "properties": "{\"Options\":{},\"Parameters\":{\"birthday\":\"datetime(1970-05-11)\",\"courses\":\"dynamic(['Java', 'C++'])\"}}"
}

Kusto SDK

若要了解如何在使用 Kusto 客户端库时提供查询参数的名称和值，请参阅使用查询参数保护用户输入。

Kusto.Explorer

若要设置向服务发出请求时发送的查询参数，请使用查询参数“扳手”图标 (ALT + P)。

  • Last updated on