Instrução de declaração de parâmetros de consulta

Artigo
07/04/2024

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 um mecanismo de proteção contra ataques de injeção.
Como forma de parametrizar consultas.

Em particular, os aplicativos cliente que combinam entrada fornecida pelo usuário em consultas que eles enviam ao Kusto devem usar o mecanismo para se proteger contra o equivalente Kusto de ataques 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 será 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 de análise normais para esse tipo.

Sintaxe

declarequery_parameters ( Nome1 : Tipo1 [= DefaultValue1] [,...]);

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Digitar	Obrigatória	Descrição
Name1	`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 cadeias de caracteres. O método de análise apropriado é aplicado ao parâmetro de consulta 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 as 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/separadas por ponto-e-vírgula, caso contrário, não serão consideradas parte da mesma consulta.

Exemplo

Executar a consulta

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

Saída

EpisodeId	EventType	totalLesões
12459	Clima de Inverno	137
10477	Excessive Heat	200
10391	Calor	187
10217	Excessive Heat	422
10217	Excessive Heat	519

Especificar parâmetros de consulta em um aplicativo cliente

Os nomes e valores dos parâmetros de consulta são fornecidos como string valores pelo aplicativo que faz a consulta. Nenhum nome pode se repetir.

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.

API REST

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 conjunto de propriedades aninhado chamado Parameters. Por exemplo, aqui está o corpo de uma chamada de API REST para o 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 bibliotecas de cliente Kusto, 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 o ícone "chave inglesa" de parâmetros de consulta (ALT + P).

Essa funcionalidade não é compatível com o Azure Monitor

Compartilhar via