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

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

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

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

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

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

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

Синтаксис

declarequery_parameters(Имя1:Type1 [=DefaultValue1] [,...] );

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

Параметры

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

Примечание

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

Пример

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 Тепла 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

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

Эта возможность не поддерживается в Azure Monitor