Declaração de parâmetros de consulta
Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel
As consultas enviadas ao Kusto podem incluir um conjunto de pares de nomes ou valores. Os pares são chamados de parâmetros de consulta , juntamente com o próprio texto da consulta. A consulta pode fazer referência a um ou mais valores, especificando nomes e tipo, em uma instrução de declaração de parâmetros de consulta .
Os parâmetros de consulta têm dois usos principais:
- Como mecanismo de proteção contra ataques de injeção.
- Como forma de parametrizar consultas.
Em particular, os aplicativos cliente que combinam a entrada fornecida pelo usuário em consultas que eles enviam para o Kusto devem usar o mecanismo para proteger contra o equivalente Kusto de ataques de de injeção de SQL.
Declarando parâmetros de consulta
Para fazer referência a 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. Para cada parâmetro, a declaração fornece o nome e o tipo escalar. Opcionalmente, o parâmetro também pode ter um valor padrão. O padrão é usado se a solicitação não fornecer um valor concreto para o parâmetro. Kusto então analisa o valor do parâmetro de consulta, de acordo com suas regras normais de análise para esse tipo.
Sintaxe
declare
query_parameters
(
Name1:
Type1 [=
DefaultValue1] [,
...] );
Saiba mais sobre convenções de sintaxe.
Parâmetros
Designação | Tipo | Necessário | Descrição |
---|---|---|---|
Nome 1 | string |
✔️ | O nome de um parâmetro de consulta usado na consulta. |
Tipo1 | string |
✔️ | O tipo correspondente, como string ou datetime . Os valores fornecidos pelo usuário são codificados como strings. O método de análise apropriado é aplicado ao parâmetro query para obter um valor fortemente tipado. |
DefaultValue1 | string |
Um valor padrão para o parâmetro. Esse valor deve ser um literal do tipo escalar apropriado. |
Observação
- Como funções definidas pelo usuário, os parâmetros de consulta do tipo
dynamic
não podem ter valores padrão. - As instruções Let, set e tabular são amarradas juntas/separadas por um ponto-e-vírgula, caso contrário, elas não serão consideradas parte da mesma consulta.
Exemplo
Os exemplos nesta seção mostram como usar a sintaxe para ajudá-lo a começar.
Os exemplos neste artigo usam tabelas disponíveis publicamente no de cluster de ajuda, como a tabela
StormEvents
no banco de dados Samples.
Os exemplos neste artigo usam tabelas disponíveis publicamente, como a tabela
StormEvents
na análise do tempo dados de exemplo.
Declarar parâmetros de consulta
Esta consulta recupera eventos de tempestade da tabela StormEvents onde o número total de lesões diretas e indiretas excede um limite especificado (o padrão é 90). Em seguida, projeta o EpisodeId, EventTypee o número total de lesões para cada um desses eventos.
declare query_parameters(maxInjured:long = 90);
StormEvents
| where InjuriesDirect + InjuriesIndirect > maxInjured
| project EpisodeId, EventType, totalInjuries = InjuriesDirect + InjuriesIndirect
Output
EpisodeId | Tipo de Evento | totalLesões |
---|---|---|
12459 | Tempo de inverno | 137 |
10477 | Calor excessivo | 200 |
10391 | Calor | 187 |
10217 | Calor excessivo | 422 |
10217 | Calor excessivo | 519 |
Especificar parâmetros de consulta em um aplicativo cliente
Os nomes e valores dos parâmetros de consulta são fornecidos como valores string
pelo aplicativo que faz a consulta. Nenhum nome pode repetir-se.
A interpretação dos valores é feita de acordo com a instrução de declaração de parâmetros de consulta. Cada valor é analisado como se fosse um literal no corpo de uma consulta. A análise é feita de acordo com o tipo especificado pela instrução de declaração de parâmetros de consulta.
REST API
Os parâmetros de consulta são fornecidos por aplicativos cliente por meio do slot de properties
do objeto JSON do corpo da solicitação, em um pacote de propriedades aninhado chamado Parameters
. Por exemplo, aqui está o corpo de uma chamada de API REST para Kusto que calcula a idade de algum usuário, presumivelmente fazendo com que o aplicativo peça o aniversário do usuário.
{
"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 SDKs
Para saber como fornecer os nomes e valores dos parâmetros de consulta ao usar o Kusto bibliotecas de cliente, consulte Usar parâmetros de consulta para proteger a entrada do usuário.
Kusto.Explorer
Para definir os parâmetros de consulta enviados ao fazer uma solicitação ao serviço, use os parâmetros de consulta ícone "chave inglesa" (ALT
+ P
).