Compartilhar via

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

Applies to: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

As consultas enviadas ao Kusto podem incluir um conjunto de pares de nome ou valor. The pairs are called query parameters, together with the query text itself. 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.

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 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. Em seguida, o Kusto analisa o valor do parâmetro de consulta, de acordo com suas regras de análise normais para esse tipo.

Syntax

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

Learn more about syntax conventions.

Parameters

Name Tipo Required Description
Name1 string ✔️ O nome de um parâmetro de consulta usado na consulta.
Type1 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.

Note

  • Assim 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 encadeadas/separadas por um ponto-e-vírgula, caso contrário, elas não serão consideradas parte da mesma consulta.

Example

Os exemplos nesta seção mostram como usar a sintaxe para ajudá-lo a começar.

The examples in this article use publicly available tables in the help cluster, such as the StormEvents table in the Samples database.

The examples in this article use publicly available tables, such as the Weather table in the Weather analytics sample gallery. Talvez seja necessário modificar o nome da tabela na consulta de exemplo para corresponder à tabela em seu workspace.

Declarar parâmetros de consulta

This query retrieves storm events from the StormEvents table where the total number of direct and indirect injuries exceeds a specified threshold (default is 90). It then projects the EpisodeId, EventType, and the total number of injuries for each of these events.

Executar a consulta

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

Output

EpisodeId EventType totalInjuries
12459 Winter Weather 137
10477 Excessive Heat 200
10391 Heat 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 recipiente 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 pergunte 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

To learn how to provide the names and values of query parameters when using Kusto client libraries, see Use query parameters to protect user input.

Kusto.Explorer

To set the query parameters sent when making a request to the service, use the Query parameters "wrench" icon (ALT + P).

  • Last updated on