Instrukcja deklaracji parametrów zapytania

  • Artykuł

Zapytania wysyłane do usługi Kusto mogą zawierać zestaw par nazw lub wartości. Pary są nazywane parametrami zapytania wraz z samym tekstem zapytania. Zapytanie może odwoływać się do co najmniej jednej wartości, określając nazwy i typ w instrukcji deklaracji parametrów zapytania.

Parametry zapytania mają dwa główne zastosowania:

  • Jako mechanizm ochrony przed atakami polegającymi na wstrzyknięciu.
  • W celu sparametryzowania zapytań.

W szczególności aplikacje klienckie, które łączą dane wejściowe udostępniane przez użytkownika w zapytaniach, które następnie wysyłają do usługi Kusto, powinny używać mechanizmu ochrony przed atakami polegającymi na wstrzyknięciu kodu SQL kusto.

Deklarowanie parametrów zapytania

Aby odwołać się do parametrów zapytania, tekstu zapytania lub używanych przez nią funkcji, należy najpierw zadeklarować, którego parametru zapytania używa. Dla każdego parametru deklaracja zawiera nazwę i typ skalarny. Opcjonalnie parametr może również mieć wartość domyślną. Wartość domyślna jest używana, jeśli żądanie nie dostarcza konkretnej wartości parametru. Następnie usługa Kusto analizuje wartość parametru zapytania zgodnie z normalnymi regułami analizowania dla tego typu.

Składnia

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

Dowiedz się więcej o konwencjach składniowych.

Parametry

Nazwa Typ Wymagane Opis
Nazwa1 string ✔️ Nazwa parametru zapytania używanego w zapytaniu.
Typ1 string ✔️ Odpowiedni typ, taki jak string lub datetime. Wartości udostępniane przez użytkownika są kodowane jako ciągi. Odpowiednia metoda analizy jest stosowana do parametru zapytania w celu uzyskania silnie typizowanej wartości.
DefaultValue1 string Wartość domyślna parametru. Ta wartość musi być literałem odpowiedniego typu skalarnego.

Uwaga

  • Podobnie jak w przypadku funkcji zdefiniowanych przez użytkownika, parametry zapytania typu dynamic nie mogą mieć wartości domyślnych.
  • Instrukcje let, set i tabular są nawleczone razem/oddzielone średnikiem, w przeciwnym razie nie będą traktowane jako część tego samego zapytania.

Przykład

Uruchamianie zapytania

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

Dane wyjściowe

EpisodeId Typ zdarzenia łączna liczba urazów
12459 Pogoda zimowa 137
10477 Nadmierne ciepło 200
10391 Ciepło 187
10217 Nadmierne ciepło 422
10217 Nadmierne ciepło 519

Określanie parametrów zapytania w aplikacji klienckiej

Nazwy i wartości parametrów zapytania są podawane jako string wartości przez aplikację tworzącą zapytanie. Żadna nazwa nie może być powtarzana.

Interpretacja wartości jest wykonywana zgodnie z instrukcją deklaracji parametrów zapytania. Każda wartość jest analizowana tak, jakby była literałem w treści zapytania. Analizowanie odbywa się zgodnie z typem określonym przez instrukcję deklaracji parametrów zapytania.

Interfejs API REST

Parametry zapytania są dostarczane przez aplikacje klienckie za pośrednictwem properties miejsca obiektu JSON treści żądania w zagnieżdżonej torbie właściwości o nazwie Parameters. Na przykład poniżej znajduje się treść wywołania interfejsu API REST do usługi Kusto, która oblicza wiek niektórych użytkowników, prawdopodobnie przez wyświetlenie aplikacji pytania o urodziny użytkownika.

{
    "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++'])\"}}"
}

Zestawy SDK kusto

Aby dowiedzieć się, jak podać nazwy i wartości parametrów zapytania podczas korzystania z bibliotek klienckich usługi Kusto, zobacz Używanie parametrów zapytania w celu ochrony danych wejściowych użytkownika.

Kusto.Explorer

Aby ustawić parametry zapytania wysyłane podczas wysyłania żądania do usługi, użyj ikony "klucz" parametrów zapytania (ALT + P).

Ta funkcja nie jest obsługiwana w usłudze Azure Monitor