Declaração de parâmetros de consulta

  • Artigo

As consultas enviadas para o Kusto podem incluir um conjunto de pares de nomes ou valores. Os pares são denominados parâmetros de consulta, juntamente com o próprio texto da consulta. A consulta pode referenciar um ou mais valores, ao especificar nomes e tipo, numa declaração de declaração de parâmetros de consulta.

Os parâmetros de consulta têm duas utilizações principais:

  • Como mecanismo de proteção contra ataques de injeção.
  • Como forma de parametrizar as consultas.

Em particular, as aplicações cliente que combinam entradas fornecidas pelo utilizador em consultas que enviam para o Kusto devem utilizar o mecanismo para proteger contra o equivalente kusto de ataques de Injeção de SQL .

Declarar parâmetros de consulta

Para referenciar parâmetros de consulta, o texto da consulta ou as funções que utiliza têm primeiro de declarar o parâmetro de consulta que utiliza. Para cada parâmetro, a declaração fornece o nome e o tipo escalar. Opcionalmente, o parâmetro também pode ter um valor predefinido. A predefinição é utilizada se o pedido não fornecer um valor concreto para o parâmetro. Em seguida, o Kusto analisa o valor do parâmetro de consulta, de acordo com as regras normais de análise desse tipo.

Syntax

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Tipo Necessário Descrição
Nome1 string ✔️ O nome de um parâmetro de consulta utilizado na consulta.
Tipo1 string ✔️ O tipo correspondente, como string ou datetime. Os valores fornecidos pelo utilizador são codificados como cadeias de carateres. O método de análise adequado é aplicado ao parâmetro de consulta para obter um valor fortemente escrito.
DefaultValue1 string Um valor predefinido para o parâmetro. Este valor tem de ser literal do tipo escalar adequado.

Nota

  • Tal como as funções definidas pelo utilizador, os parâmetros de consulta do tipo dynamic não podem ter valores predefinidos.
  • As instruções let, set e tabular são colocadas juntas/separadas por um 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 totalInjuries
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 numa aplicação cliente

Os nomes e valores dos parâmetros de consulta são fornecidos como string valores pela aplicação que faz a consulta. Não é possível repetir nenhum nome.

A interpretação dos valores é feita de acordo com a 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 pelas aplicações cliente através do properties bloco do objeto JSON do corpo do pedido, num saco de propriedades aninhado denominado Parameters. Por exemplo, eis o corpo de uma chamada à API REST para o Kusto que calcula a idade de algum utilizador, presumivelmente fazendo com que a aplicação peça o aniversário do utilizador.

{
    "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 utilizar bibliotecas de cliente kusto, veja Utilizar parâmetros de consulta para proteger a entrada do utilizador.

Kusto.Explorer

Para definir os parâmetros de consulta enviados ao fazer um pedido para o serviço, utilize o ícone "wrench" dos parâmetros de consulta (ALT + P).

Esta capacidade não é suportada no Azure Monitor