Оператор Pattern

Применимо: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Шаблон — это конструкция, которая сопоставляет кортежи строк с табличными выражениями.

Каждый шаблон должен объявить имя шаблона и при необходимости определить сопоставление шаблонов. Шаблоны, определяющие сопоставление, возвращают табличное выражение при вызове. Разделите все два оператора точкой с запятой.

Пустые шаблоны — это шаблоны, объявленные, но не определяющие сопоставление. При вызове они возвращают ошибку SEM0036 вместе с сведениями о отсутствующих определениях шаблонов в заголовке HTTP.

Приложения среднего уровня, предоставляющие интерфейс языка запросов Kusto (KQL), могут использовать возвращаемые сведения в рамках процесса для обогащения результатов запроса KQL. Дополнительные сведения см. в разделе Работа с приложениями среднего уровня.

Синтаксис

• Объявите пустой шаблон:

  declare pattern PatternName;

• Объявите и определите шаблон:

  declare pattern PatternName = (ArgName:ArgType [, ... ]) [[PathName:PathArgType]]

  {

         ( ArgValue1_1 [,ArgValue2_1, ... ] ) [ .[PathValue_1] ] ={expression1};

      [ (ArgValue1_2 [,ArgValue2_2, ... ] ) [ .[PathValue_2] ] ={expression2}; ... ]

  } ;

• Вызов шаблона:

  • PatternName(ArgValue1 [,ArgValue2 ...] ).PathValue
  • PatternName(ArgValue1 [,ArgValue2 ...] ).["PathValue"]

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

Параметры

Примеры

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

Определение простого шаблона

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

declare pattern country = (name:string)[state:string]
{
  ("USA").["New York"] = { print Capital = "Albany" };
  ("USA").["Washington"] = { print Capital = "Olympia" };
  ("Canada").["Alberta"] = { print Capital = "Edmonton" };
};
country("Canada").Alberta

выходных

Определение шаблона с областью действия

В этом примере определяется шаблон для области данных и метрик приложения. Шаблон вызывается для возврата объединения данных.

declare pattern App = (applicationId:string)[scope:string]
{
    ('a1').['Data']    = { range x from 1 to 5 step 1 | project App = "App #1", Data    = x };
    ('a1').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #1", Metrics = rand() };
    ('a2').['Data']    = { range x from 1 to 5 step 1 | project App = "App #2", Data    = 10 - x };
    ('a3').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #3", Metrics = rand() };
};
union App('a2').Data, App('a1').Metrics

выходных

Нормализация

Существуют варианты синтаксиса для вызова шаблонов. Например, следующий союз возвращает одно выражение шаблона, так как все вызовы имеют одинаковый шаблон.

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union
  app("ApplicationX").StartEvents,
  app('ApplicationX').StartEvents,
  app("ApplicationX").['StartEvents'],
  app("ApplicationX").["StartEvents"]

Подстановочные знаки отсутствуют

В шаблоне нет специального лечения. Например, следующий запрос возвращает один отсутствующий вызов шаблона.

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union app("ApplicationX").["*"]
| count

семантическая ошибка вывода

Один или несколько ссылок на шаблоны не объявлялись. Обнаруженные ссылки на шаблоны: ["app('ApplicationX').[' *']"]

Работа с приложениями среднего уровня

Приложение среднего уровня предоставляет своим пользователям возможность использовать KQL и хочет улучшить взаимодействие, обогатив результаты запроса дополненными данными из внутренней службы.

Для этого приложение предоставляет пользователям инструкцию шаблона, которая возвращает табличные данные, которые их пользователи могут использовать в своих запросах. Аргументы шаблона — это ключи, которые приложение будет использовать для получения данных обогащения.

Когда пользователь запускает запрос, приложение не анализирует сам запрос, но вместо этого использует ошибку, возвращаемую пустым шаблоном, чтобы получить необходимые ключи. Поэтому он добавляет запрос с пустым объявлением шаблона, отправляет его в кластер для обработки, а затем анализирует возвращаемый заголовок HTTP, чтобы получить значения отсутствующих аргументов шаблона. Приложение использует эти значения для поиска данных обогащения и создания нового объявления, определяющего соответствующее сопоставление данных обогащения.

Наконец, приложение предопределяет новое определение запроса, повторно отправляет его для обработки и возвращает результат, полученный пользователю.

Пример

В примерах шаблон объявляется, определяется и вызывается.

Объявление пустого шаблона

В этом примере приложение среднего уровня расширяет запросы с расположениями долготы и широты. Приложение использует внутреннюю службу для сопоставления IP-адресов с расположениями долготы и широты и предоставляет шаблон, называемый map_ip_to_longlat. При выполнении запроса возвращается ошибка с отсутствующими определениями шаблонов:

map_ip_to_longlat("10.10.10.10")

Объявление и определение шаблона

Приложение не анализирует этот запрос и поэтому не знает, какой IP-адрес (10.10.10.10.10) передан в шаблон. Поэтому он добавляет запрос пользователя с пустым объявлением шаблона map_ip_to_longlat и отправляет его для обработки:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

Приложение получает следующую ошибку в ответе.

Один или несколько ссылок на шаблоны не объявлялись. Обнаруженные ссылки на шаблоны: ["map_ip_to_longlat('10.10.10.10')"]

Вызов шаблона

Приложение проверяет ошибку, определяет, что ошибка указывает на отсутствующую ссылку на шаблон и извлекает отсутствующий IP-адрес (10.10.10.10.10). Он использует IP-адрес для поиска данных обогащения во внутренней службе и создает новый шаблон, определяющий сопоставление IP-адреса с соответствующими данными долготы и широты. Новый шаблон предопределен к запросу пользователя и снова запустите его.

На этот раз запрос завершается успешно, так как данные обогащения теперь объявлены в запросе, а результат отправляется пользователю.

declare pattern map_ip_to_longlat = (address:string)
{
  ("10.10.10.10") = { print Lat=37.405992, Long=-122.078515 };
};
map_ip_to_longlat("10.10.10.10")

выходных