通过

参考文档的语法约定

  • 项目

适用于：✅Azure 数据资源管理器✅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

由于每个步骤的输出都作为下一步的输入，因此步骤的顺序可以确定查询的结果并影响其性能。 必须根据要退出查询的内容对步骤进行排序。

小提示

  • 一个很好的经验法则是尽早筛选数据，因此你只会在管道中传递相关数据。 这极大地提高了性能，并确保不会意外地在汇总步骤中包含不相关的数据。
  • 本文指出了一些要记住的其他最佳做法。 有关更完整的列表，请参阅 查询最佳做法。

语法约定

约定 说明
Block 要完全按照所示内容输入的字符串字面量。
斜体 在使用函数或命令时要为参数提供值。
【 】 表示括住的项是可选的。
（ ） 表示至少需要一个括住的项。
|（竖线） 在方括号或圆括号内使用，表示可以指定由管道字符分隔的项之一。 在此形式中，管道等效于逻辑 OR 运算符。 在块 (|) 中时，管道是 KQL 查询语法的一部分。
【, ...】 表示前面的参数可以重复多次（用逗号分隔）。
; 查询语句终止符。

示例

标量函数

此示例显示了 hash 函数的语法和示例用法，接下来解释了每个语法组成部分如何解译为示例用法。

语法

hash( source [,mod])

用法示例

hash("World")
  • 函数 hash 的名称，完全按照所示内容输入左括号。
  • “World”作为必需的 source 参数的自变量传递。
  • 没有为 mod 参数传递自变量，该参数是可选的，如方括号所示。
  • 完全按照所示内容输入右括号。

表格运算符

此示例显示了 sort 运算符的语法和示例用法，接下来解释了每个语法组成部分如何解译为示例用法。

语法

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

用法示例

StormEvents
| sort by State asc, StartTime desc
  • StormEvents 表作为自变量传递给必需的 T 参数。
  • 完全按照所示内容输入 | sort by。 在本例中，竖线字符是表格表达式语句语法的一部分，由块文本表示。 有关详细信息，请参阅什么是查询语句。
  • State 列作为自变量传递给必需的 column 参数，该参数附带可选的 标志。
  • 在逗号后面传递了另一个自变量集：附带可选 desc 标志的 StartTime 列。 [, ...] 语法表示可以传递更多自变量集，但它们不是必需的。

使用可选参数

若要为一个可选参数后面的另一个可选参数提供自变量，必须为前一个参数提供自变量。 之所以提出此要求，是因为自变量必须遵循语法中指定的顺序。 如果没有可为参数传递的特定值，请使用相同类型的空值。

顺序可选参数的示例

考虑 http_request 插件的语法：

evaluate http_request ( Uri [,RequestHeaders [,Options]] )

RequestHeaders 和 Options 是动态类型的可选参数。 若要为 Options 参数提供自变量，还必须为 RequestHeaders 参数提供自变量。 以下示例演示如何为第一个可选参数 RequestHeaders 提供空值，以便能够为第二个可选参数 Options 指定值。

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

相关内容