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

Переключайте службы с помощью раскрывающегося списка Версия. Дополнительные сведения о навигации.
Область применения: ✅ Microsoft Fabric ✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

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

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

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

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

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

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

Syntax

declare query_parameters ( Name1:Тип1 [=DefaultValue1] [,...] );

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

Parameters

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

Note

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

Example

В примерах этого раздела показано, как использовать синтаксис для начала работы.

Примеры, приведенные в этой статье, используют общедоступные таблицы в кластере справки, например StormEvents таблицу в базе данных Samples .

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

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

Этот запрос извлекает события storm из таблицы StormEvents , где общее количество прямых и косвенных травм превышает указанное пороговое значение (по умолчанию — 90). Затем он проектит Имя эпизода, EventType и общее количество травм для каждого из этих событий.

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

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

Output

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).

  • Last updated on