Оператор объявления параметров запроса

Статья
11/23/2024

Область применения: ✅Microsoft Fabric ✅Azure Data Explorer✅Azure Monitor ✅Microsoft Sentinel

Запросы, отправленные в Kusto, могут включать набор пар "имя" или "значение". Пары называются параметрами запроса вместе с текстом запроса. Запрос может ссылать на одно или несколько значений, указав имена и тип в инструкции объявления параметров запроса.

Параметры запроса имеют два основных использования:

В качестве механизма защиты от атак на внедрение.
Как способ параметризации запросов.

В частности, клиентские приложения, которые объединяют входные данные, предоставленные пользователем, в запросах, которые затем отправляются в Kusto, должны использовать механизм защиты от атак на внедрение Kusto.

Объявление параметров запроса

Чтобы ссылаться на параметры запроса, текст запроса или используемые функции, сначала необходимо объявить, какой параметр запроса он использует. Для каждого параметра объявление предоставляет имя и скалярный тип. При необходимости параметр также может иметь значение по умолчанию. Значение по умолчанию используется, если запрос не предоставляет конкретное значение параметра. Затем Kusto анализирует значение параметра запроса в соответствии с его обычными правилами синтаксического анализа для этого типа.

Синтаксис

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

Дополнительные сведения о соглашениях синтаксиса.

Параметры

Имя (название)	Type	Обязательно	Описание
Name1	`string`	✔️	Имя параметра запроса, используемого в запросе.
Тип1	`string`	✔️	Соответствующий тип, например `string` или `datetime`. Значения, предоставленные пользователем, кодируются в виде строк. Соответствующий метод синтаксического анализа применяется к параметру запроса для получения строго типизированного значения.
DefaultValue1	`string`		Значение по умолчанию для параметра. Это значение должно быть литералом соответствующего скалярного типа.

Примечание.

Как и пользовательские функции, параметры запроса типа dynamic не могут иметь значения по умолчанию.
Пусть, задать и табличные операторы тянутся вместе или разделяются точкой с запятой, в противном случае они не будут считаться частью одного запроса.

Пример

Выполнить запрос

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

Выходные данные

EpisodeId	EventType	totalInjuries
12459	Холод	137
10477	Аномальная жара	200
10391	Heat	187
10217	Аномальная жара	422
10217	Аномальная жара	519

Указание параметров запроса в клиентском приложении

Имена и значения параметров запроса предоставляются в качестве string значений приложением, выполняющего запрос. Имя не может повторяться.

Интерпретация значений выполняется в соответствии с оператором объявления параметров запроса. Каждое значение анализируется, как если бы это был литерал в тексте запроса. Синтаксический анализ выполняется в соответствии с типом, указанным оператором объявления параметров запроса.

REST API

Параметры запроса предоставляются клиентскими приложениями через properties слот объекта JSON текста запроса в контейнере вложенных свойств Parameters. Например, вот текст вызова REST API в Kusto, который вычисляет возраст некоторых пользователей, предположительно запросить у приложения день рождения пользователя.

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

Пакеты SDK Kusto

Сведения о том, как указать имена и значения параметров запроса при использовании клиентских библиотек Kusto, см. в разделе "Использование параметров запроса для защиты входных данных пользователя".

Kusto.Explorer

Чтобы задать параметры запроса, отправленные при выполнении запроса в службу, используйте значок "WRENCH" (ALT + P).

Поделиться через