Instrução de declaração de parâmetros de consultaQuery parameters declaration statement

As consultas enviadas para Kusto podem incluir um conjunto de pares de nome ou valor.Queries sent to Kusto may include a set of name or value pairs. Os pares são chamados de parâmetros de consulta, juntamente com o próprio texto de consulta.The pairs are called query parameters, together with the query text itself. A consulta pode referenciar um ou mais valores, especificando nomes e tipo, em uma instrução de declaração de parâmetros de consulta.The query may reference one or more values, by specifying names and type, in a query parameters declaration statement.

Os parâmetros de consulta têm dois usos principais:Query parameters have two main uses:

  • Como um mecanismo de proteção contra ataques de injeção.As a protection mechanism against injection attacks.
  • Como uma maneira de parametrizar consultas.As a way to parameterize queries.

Em particular, os aplicativos cliente que combinam a entrada fornecida pelo usuário em consultas que eles enviam para Kusto devem usar o mecanismo para proteger contra o equivalente Kusto de ataques de injeção de SQL .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.

Declarando parâmetros de consultaDeclaring query parameters

Para referenciar parâmetros de consulta, o texto da consulta ou as funções que ele usa, deve primeiro declarar qual parâmetro de consulta ele usa.To reference query parameters, the query text, or functions it uses, must first declare which query parameter it uses. Para cada parâmetro, a declaração fornece o nome e o tipo escalar.For each parameter, the declaration provides the name and scalar type. Opcionalmente, o parâmetro também pode ter um valor padrão.Optionally, the parameter can also have a default value. O padrão será usado se a solicitação não fornecer um valor concreto para o parâmetro.The default is used if the request doesn't provide a concrete value for the parameter. Em seguida, o Kusto analisa o valor do parâmetro de consulta, de acordo com suas regras de análise normais para esse tipo.Kusto then parses the query parameter's value, according to its normal parsing rules for that type.

SintaxeSyntax

declare``query_parameters ( Nome1 : type1 [ = defaultvalue1] [ , ...]);declare query_parameters ( Name1 : Type1 [= DefaultValue1] [,...] );

  • Nome1: o nome de um parâmetro de consulta usado na consulta.Name1: The name of a query parameter used in the query.
  • Type1: o tipo correspondente, como string ou datetime .Type1: The corresponding type, such as string or datetime. Os valores fornecidos pelo usuário são codificados como cadeias de caracteres, para Kusto aplicará o método de análise apropriado ao parâmetro de consulta para obter um valor fortemente tipado.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: um valor padrão opcional para o parâmetro.DefaultValue1: An optional default value for the parameter. Esse valor deve ser um literal do tipo escalar apropriado.This value must be a literal of the appropriate scalar type.

Observação

Como as funções definidas pelo usuário, os parâmetros de consulta do tipo dynamic não podem ter valores padrão.Like user defined functions, query parameters of type dynamic cannot have default values.

ExemplosExamples

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

Especificando parâmetros de consulta em um aplicativo clienteSpecifying query parameters in a client application

Os nomes e valores dos parâmetros de consulta são fornecidos como string valores pelo aplicativo que faz a consulta.The names and values of query parameters are provided as string values by the application making the query. Nenhum nome pode ser repetido.No name may repeat.

A interpretação dos valores é feita de acordo com a instrução de declaração de parâmetros de consulta.The interpretation of the values is done according to the query parameters declaration statement. Cada valor é analisado como se fosse um literal no corpo de uma consulta.Every value is parsed as if it were a literal in the body of a query. A análise é feita de acordo com o tipo especificado pela instrução de declaração de parâmetros de consulta.The parsing is done according to the type specified by the query parameters declaration statement.

API RESTREST API

Os parâmetros de consulta são fornecidos por aplicativos cliente por meio do properties slot do objeto JSON do corpo da solicitação, em um recipiente de propriedades aninhado chamado 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. Por exemplo, aqui está o corpo de uma chamada à API REST para Kusto que calcula a idade de algum usuário, presumivelmente, fazendo com que o aplicativo solicite o aniversário do usuário.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++'])\"}}"
}

SDK do .NET do KustoKusto .NET SDK

Para fornecer os nomes e valores dos parâmetros de consulta ao usar a biblioteca de cliente do Kusto .NET, um cria uma nova instância do ClientRequestProperties objeto e, em seguida, usa os HasParameter SetParameter métodos, e ClearParameter para manipular parâmetros de consulta.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. Essa classe fornece várias sobrecargas fortemente tipadas para SetParameter ; internamente, elas geram o literal apropriado da linguagem de consulta e as enviam como string por meio da API REST, conforme descrito acima.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. O texto de consulta em si ainda deve declarar os parâmetros de consulta.The query text itself must still declare the query parameters.

Kusto.ExplorerKusto.Explorer

Para definir os parâmetros de consulta enviados ao fazer uma solicitação para o serviço, use o ícone "chave inglesa" dos parâmetros de consulta ( ALT + P ).To set the query parameters sent when making a request to the service, use the Query parameters "wrench" icon (ALT + P).

Esse recurso não tem suporte no Azure MonitorThis capability isn't supported in Azure Monitor