查询参数声明语句

项目
10/03/2024

适用于：✅Azure 数据资源管理器✅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 语句用分号串在一起/分隔，否则它们将不被视为同一查询的一部分。

示例

运行查询

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

输出

EpisodeId	EventType	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)。

通过