查询参数声明语句Query parameters declaration statement

发送到 Kusto 的查询可以包含一组名称或值对。Queries sent to Kusto may include a set of name or value pairs. 这些对与查询文本自身一起被称为查询参数。The pairs are called query parameters, together with the query text itself. 查询可以通过在查询参数声明语句中指定名称和类型来引用一个或多个值。The query may reference one or more values, by specifying names and type, in a query parameters declaration statement.

查询参数有两个主要用途:Query parameters have two main uses:

  • 用作防范注入攻击的保护机制。As a protection mechanism against injection attacks.
  • 用作对查询进行参数化的方式。As a way to parameterize queries.

具体而言,如果客户端应用程序在查询中组合了用户提供的输入,然后将查询发送到 Kusto,则客户端应用程序应使用该机制来防止与 SQL 注入攻击相当的 Kusto 攻击。In particular, client applications that combine user-provided input in queries that they then send to Kusto should use the mechanism to protect against the Kusto equivalent of SQL Injection attacks.

声明查询参数Declaring query parameters

若要引用查询参数、查询文本或它使用的函数,必须首先声明它使用哪个查询参数。To reference query parameters, the query text, or functions it uses, must first declare which query parameter it uses. 对于每个参数,声明都提供名称和标量类型。For each parameter, the declaration provides the name and scalar type. 此外,参数还可以具有默认值。Optionally, the parameter can also have a default value. 如果请求未提供参数的具体值,则会使用默认值。The default is used if the request doesn't provide a concrete value for the parameter. 然后,Kusto 根据该类型的常规分析规则来分析查询参数的值。Kusto then parses the query parameter's value, according to its normal parsing rules for that type.

语法Syntax

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

  • Name1:查询中使用的查询参数的名称。Name1: The name of a query parameter used in the query.
  • Type1:对应的类型,例如 stringdatetimeType1: The corresponding type, such as string or datetime. 用户提供的值将编码为字符串,Kusto 会将相应的分析方法应用于查询参数以获取强类型值。The values provided by the user are encoded as strings, to Kusto will apply the appropriate parse method to the query parameter to get a strongly-typed value.
  • DefaultValue1:参数的可选默认值。DefaultValue1: An optional default value for the parameter. 此值必须是合适标量类型的文本。This value must be a literal of the appropriate scalar type.

备注

用户定义的函数一样,dynamic 类型的查询参数不能具有默认值。Like user defined functions, query parameters of type dynamic cannot have default values.

示例Examples

declare query_parameters(UserName:string, Password:string);
print n=UserName, p=hash(Password)
declare query_parameters(percentage:long = 90);
T | where Likelihood > percentage

在客户端应用程序中指定查询参数Specifying query parameters in a client application

查询参数的名称和值由进行查询的应用程序作为 string 值提供。The names and values of query parameters are provided as string values by the application making the query. 名称不可以重复。No name may repeat.

值的解释根据查询参数声明语句来完成。The interpretation of the values is done according to the query parameters declaration statement. 每个值都作为查询正文中的文本进行分析。Every value is parsed as if it were a literal in the body of a query. 分析根据查询参数声明语句指定的类型来完成。The parsing is done according to the type specified by the query parameters declaration statement.

REST APIREST API

查询参数由客户端应用程序通过请求正文的 JSON 对象的 properties 槽在名为 Parameters 的嵌套属性包中提供。Query parameters are provided by client applications through the properties slot of the request body's JSON object, in a nested property bag called Parameters. 例如,下面是对 Kusto 的一个 REST API 调用的正文,该调用会计算某个用户的年龄(可能是采用让应用程序询问用户的生日的方式)。For example, here's the body of a REST API call to Kusto that calculates the age of some user, presumably by having the application ask for the user's birthday.

{
    "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 .NET SDKKusto .NET SDK

若要在使用 Kusto .NET 客户端库时提供查询参数的名称和值,可以创建 ClientRequestProperties 对象的一个新实例,然后使用 HasParameterSetParameterClearParameter 方法来操作查询参数。To provide the names and values of query parameters when using the Kusto .NET client library, one creates a new instance of the ClientRequestProperties object and then uses the HasParameter, SetParameter, and ClearParameter methods to manipulate query parameters. 此类为 SetParameter 提供了许多强类型的重载;在内部,它们会生成相应的查询语言文本,并通过 REST API 将其作为 string 发送,如上所述。This class provides a number of strongly-typed overloads for SetParameter; internally, they generate the appropriate literal of the query language and send it as a string through the REST API, as described above. 查询文本自身仍需声明查询参数The query text itself must still declare the query parameters.

Kusto.ExplorerKusto.Explorer

若要设置向服务发出请求时发送的查询参数,请使用查询参数“扳手”图标 (ALT + P)。To set the query parameters sent when making a request to the service, use the Query parameters "wrench" icon (ALT + P).

Azure Monitor 不支持此功能This capability isn't supported in Azure Monitor