Instrukcja deklaracji parametrów zapytania

Artykuł
07/03/2024

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 kusto równoważnymi atakami polegającymi na wstrzyknięciu kodu SQL.

Deklarowanie parametrów zapytania

Aby odwoływać się do parametrów zapytania, tekstu zapytania lub używanych przez nią funkcji, należy najpierw zadeklarować, który parametr 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 podaje konkretnej wartości parametru. Następnie narzędzie Kusto analizuje wartość parametru zapytania, zgodnie z normalnymi regułami analizowania dla tego typu.

Składnia

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

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko	Type	Wymagania	opis
Nazwa1	`string`	✔️	Nazwa parametru zapytania używanego w zapytaniu.
Typ1	`string`	✔️	Odpowiedni typ, taki jak `string` lub `datetime`. Wartości podane 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 funkcje zdefiniowane przez użytkownika, parametry zapytania typu dynamic nie mogą mieć wartości domyślnych.
Niech, zestaw i instrukcje tabelaryczne 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

Wyjście

EpisodeId	EventType	łączna liczba urazów
12459	Zimowa pogoda	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 odbywa się 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 zwrócenie się do aplikacji 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 do 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 ( + ALTP).

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

Udostępnij za pośrednictwem