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

Соглашения синтаксиса для справочной документации

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

В этой статье описаны соглашения о синтаксисе, приведенные в справочной документации по языку запросов Kusto (KQL) и командам управления .

Хорошее место, чтобы начать обучение языка запросов Kusto, заключается в том, чтобы понять общую структуру запросов. Первое, что вы заметите при просмотре запроса Kusto, — использование символа канала (|). Структура запроса Kusto начинается с получения данных из источника данных, а затем передачи данных по конвейеру, и каждый шаг обеспечивает некоторый уровень обработки, а затем передает данные на следующий шаг. В конце конвейера вы получите окончательный результат. В действительности это наш конвейер:

Get Data | Filter | Summarize | Sort | Select

Эта концепция передачи данных вниз конвейера делает интуитивно понятной структурой, так как легко создать ментальную картину данных на каждом шаге.

Чтобы проиллюстрировать это, давайте рассмотрим следующий запрос, который смотрит на журналы входа в Microsoft Entra. При чтении каждой строки вы увидите ключевые слова, которые указывают на то, что происходит с данными. Мы включили соответствующий этап в конвейер в качестве комментария в каждой строке.

Замечание

Вы можете добавить примечания к любой строке запроса, выполнив перед ними двойную косую черту (//).

SigninLogs                              // Get data
| evaluate bag_unpack(LocationDetails)  // Ignore this line for now; we'll come back to it at the end.
| where RiskLevelDuringSignIn == 'none' // Filter
   and TimeGenerated >= ago(7d)         // Filter
| summarize Count = count() by city     // Summarize
| sort by Count desc                    // Sort
| take 5                                // Select

Так как выходные данные каждого шага служат входными данными для следующего шага, порядок шагов может определить результаты запроса и повлиять на его производительность. Важно упорядочить шаги в соответствии с тем, что вы хотите выйти из запроса.

Подсказка

  • Хорошим правилом является фильтрация данных рано, поэтому вы передаете только соответствующие данные по конвейеру. Это значительно повышает производительность и гарантирует, что вы не случайно включаете неуместные данные в инструкции сводки.
  • В этой статье приводятся некоторые другие рекомендации, которые следует учитывать. Более полный список см. в рекомендациях по запросу.

Соглашения о синтаксисе

Конвенция Description
Block Строковые литералы, введенные точно так же, как показано.
Italic Параметры, предоставляемые при использовании функции или команды.
[ ] Указывает, что заключенный элемент является необязательным.
( ) Указывает, что требуется по крайней мере один из вложенных элементов.
| (канал) Используется в квадратных или круглых скобках, чтобы указать один из элементов, разделенных символом канала. В этой форме канал эквивалентен логическому оператору OR. При использовании блока (|) канал является частью синтаксиса запроса KQL.
[, ...] Указывает, что предыдущий параметр может повторяться несколько раз, разделенных запятыми.
; Терминатор инструкции запроса.

Примеры

Скалярная функция

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

Синтаксис

hash( source [,mod])

Пример использования

hash("World")
  • Имя функции hashи открываемая скобка вводятся точно так же, как показано.
  • "World" передается в качестве аргумента для требуемого исходного параметра.
  • Аргумент не передается для параметра mod , который является необязательным, как указано квадратными скобками.
  • Закрывающая скобка вводится точно так же, как показано.

Табличный оператор

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

Синтаксис

T| sort bycolumn [] [asc | descnulls first | nulls last] [, ...]

Пример использования

StormEvents
| sort by State asc, StartTime desc
  • Таблица StormEvents передается в качестве аргумента для требуемого параметра T .
  • | sort by вводится точно так же, как показано. В этом случае символ канала является частью синтаксиса инструкции табличного выражения , представленного текстом блока. Дополнительные сведения см. в разделе "Что такое оператор запроса".
  • Столбец state передается в качестве аргумента для обязательного параметра столбца с необязательным asc флагом.
  • После запятой передается другой набор аргументов: столбец StartTime с необязательным desc флагом. Синтаксис [, ...] указывает, что больше наборов аргументов может быть передано, но не требуется.

Работа с необязательными параметрами

Чтобы указать аргумент для необязательного параметра, который поступает после другого необязательного параметра, необходимо указать аргумент для предыдущего параметра. Это требование обусловлено тем, что аргументы должны соответствовать порядку, указанному в синтаксисе. Если для параметра нет определенного значения, используйте пустое значение того же типа.

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

Рассмотрим синтаксис подключаемого модуля http_request:

evaluate http_request ( URI [, [,Параметры]])

RequestHeaders и Options — это необязательные параметры динамического типа. Чтобы указать аргумент параметра Options , необходимо также указать аргумент для параметра RequestHeaders . В следующем примере показано, как указать пустое значение для первого необязательного параметра RequestHeaders, чтобы указать значение второго необязательного параметра Options.

evaluate http_request ( "https://contoso.com/", dynamic({}), dynamic({ EmployeeName: Nicole }) )

Связанный контент

  • Last updated on