SQL Assessment API JSON 配置文件格式完全指南：Check、Probe 与表达式语法详解（sql-server-samples）-开发者社区

示例工程
数据库
教程
后端

【免费下载链接】sql-server-samples

Azure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge

项目地址：https://gitcode.com/gh_mirrors/sq/sql-server-samples

点击查看免费下载

SQL Assessment API 是随 sql-server-samples 仓库发布的 SQL Server 配置评估机制，它通过一套可定制、可扩展的 JSON 规则集（Ruleset）来检查 SQL Server 环境是否遵循最佳实践。本文以官方参考文档 JSONConfiguration.md 为骨架，系统讲解规则集 JSON 文件的完整格式——从引擎顶层结构、Check（检查项）、Probe（探测器）及其实现，到 SQL 对象匹配模式、版本区间语法和条件表达式求值规则，并辅以仓库中的真实示例与源码级佐证。读完本文，你将能独立读懂默认规则集 ruleset.json，并能编写出自定义检查项与探测器的 JSON 配置文件。

一、规则集文件与引擎配置（Engine Configuration）

SQL Assessment API 的规则集存储在一个包含 JSON 对象的文本文件中。在深入 Check 与 Probe 之前，先了解规则集的顶层骨架。规则集对象包含三个简单的必填属性：name、version和schemaVersion，其中schemaVersion指定文件格式版本（截至仓库文档写作时文件格式版本为 1.0），name与version共同构成规则集的唯一标识。

规则集中还包含两个可选属性：rules（规则数组，用于构建检查清单）和probes（探测器定义，用于从目标 SQL Server 实例、宿主机器及其他数据源获取真实数据）。rules和probes之所以可选，是因为一个规则集中的规则可以使用另一个规则集中的探测器。完整的顶层结构（参见 RulesetFileStructure.md）如下：

{ "name": "Ruleset name", "version": "Ruleset version", "schemaVersion": "Schema version", "rules":[ { … rule A … }, { … rule B … }, … ], "probes":{ "probe1": [ { … implementation 1 … }, { … implementation 2 … }, … ], "probe2": [ … ], … } }

而 JSONConfiguration.md 从“引擎配置”的角度给出了一组更聚焦的顶层属性定义：

需要说明的是，这两处文档对顶层对象的命名视角不同：RulesetFileStructure.md面向完整的自定义规则集文件（rules+probes），而JSONConfiguration.md是 API 层面“引擎配置”的抽象描述（checks+probes）。在实际仓库示例中，如 MakingCustomChecks_sample.json，使用的是schemaVersion: "1.0"、version、name、rules、probes这套结构，读者在编写自定义规则集时应以后者为准。

二、SQL Assessment API 的两步评估流程

在展开 JSON 语法之前，先理解这些配置元素在引擎中如何被使用。根据 RulesandProbes.md，SQL Assessment API 通过两步流程给出最佳实践建议：

为给定目标构建检查清单（Build a checklist）：清单包含一整套检查项，取决于指定目标（服务器或数据库）；
遍历清单并报告每条最佳实践违规（Report every best practice violation）：引擎逐项验证目标是否满足某项最佳实践。

清单构建过程基于规则。每条规则要么定义一个新检查，要么修改一个或多个已有检查。用户可以按顺序向引擎添加多个规则集，引擎按添加顺序应用规则。单个检查可被多条规则影响：第一条规则必须定义检查并分配唯一字符串 ID，后续规则通过 ID 或标签（tag）引用并覆盖这些检查。检查出现在清单中并不意味着一定会被运行——每个检查都有默认为true的enabled属性，若所有规则应用后该属性变为false，引擎会跳过该检查。

检查本身不直接获取数据，而是引用Probe（探测器）来取数。每个 Probe 返回零行或多行包含命名项的数据；若一个检查从多个 Probe 获取数据，结果数据集将按“行的所有组合”构造（行为类似 T-SQL 中的CROSS JOIN）。检查的条件表达式会针对每一行分别求值——例如某数据库用 3 块磁盘存放文件，那么磁盘可用空间的最佳实践会对每块磁盘独立判断；若两个 Probe 分别产生 2 行和 3 行数据，则条件表达式会被求值 2×3=6 次，其中 2 次返回false就产生 2 条建议消息。

三、Check 检查项详解

Check（检查项）是 JSON 规则集的核心单元，它描述“目标对象应当满足什么样的最佳实践”。JSONConfiguration.md对 Check 的属性定义如下：

| 属性 | 类型 | 说明 | | - | - | - | | name | string | 简短名称。必须唯一。 | | tags | string 数组 | 检查项的标签集合，代表检查分组与类别。在 API 调用中，标签可代替检查名使用。 | | displayName | string | 展示给用户的完整名称。 | | description | string | 解释检查目的的详细描述。 | | enabled? | bool | 指示检查是否启用。被禁用的检查不会对任何对象运行。默认值为true。 | | messge | string | 检查失败时展示给用户的建议文本。建议文本可包含@{variableName}形式的变量引用，此类引用会被替换为变量值的字符串表示；还可用@{variableName:formatString}形式为变量指定可选格式字符串。 | | target? | SQL Object Pattern | 检查可应用于满足该模式的对象。默认匹配任意对象。 | | probes | string 数组 | 该检查所需的 Probe Family 的 ID 列表。 | | condition? | Condition Expression | 目标对象必须满足的条件表达式。若条件表达式返回false，则生成建议。默认值为true。 | | level | string | 严重级别：Information、Warning或Critical。 | | any | Expression | 其他属性都被视为检查参数，可在检查表达式中以带@前缀的变量名访问。参数可以引用变量或其他参数。 |

3.1 从规则到检查：definition 与 override

仓库中规则（Rule）有两种itemType：definition（定义一个新检查）和override（覆盖/修改已有检查）。这与上述Check属性中的name/enabled/condition等概念相呼应。以下是 RulesandProbes.md 中定义MaxMemory检查的示例——注意limit作为检查参数（对应Check属性中的any），在目标版本[11.0,)（即 SQL Server 2012 及更高版本）上生效：

{ "id": "MaxMemory", "itemType": "definition", "target": { "type": "Server", "version": "[11.0,)" }, "limit": 2147483647 }

下面的 override 规则则修改同一检查的参数：

{ "id": "MaxMemory", "itemType": "override", "limit": 2000000000 }

override 还可通过targetFilter针对特定引擎版本做精细化调整——例如对Standard版限制为 131072、对Express版限制为 1410；也可以一次性按 ID 或标签批量禁用检查，如将id设为[ "MaxMemory", "Performance" ]并配合"enabled": false在 Linux 平台上禁用相关检查。这正是enabled属性在真实规则集中的用法。

3.2 检查示例：Query Store 最佳实践

以仓库 MakingCustomChecks_sample.json 中的QueryStoreOn规则为例，对照Check属性逐项理解：

{ "target": { "type": "Database", "version": "[13.0,)", "platform": "Windows, Linux", "engineEdition": "OnPremises, ManagedInstance", "name": { "not": "/^(master|tempdb|model)$/" } }, "id": "QueryStoreOn", "itemType": "definition", "tags": [ "CustomRuleset", "Performance", "QueryStore", "Statistics" ], "displayName": "Query Store should be active", "description": "The Query Store feature provides you with insight on query plan choice and performance…", "message": "Make sure Query Store actual operation mode is 'Read Write' to keep your performance analysis accurate", "helpLink": "https://docs.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store", "probes": [ "Custom_DatabaseConfiguration" ], "condition": { "equal": [ "@query_store_state", 2 ] } }

target：该检查只作用于数据库对象、SQL Server 2016 及以上（[13.0,)）、Windows 与 Linux 平台、本地部署与托管实例，且名称不是master/tempdb/model的数据库；
condition："equal": [ "@query_store_state", 2 ]表示从 Probe 获取的@query_store_state变量必须等于 2（Query Store 实际运行模式为 Read Write 的枚举值）才视为合规，否则触发建议消息；
失败时的用户可见输出即message字段。

四、Probe 探测器与探针实现详解

Probe（探测器）是 JSON 中的一个属性：属性名就是 Check 中使用的探测器族 ID（Probe Family ID），属性值是一个 probe implementation（探针实现）数组。引擎按数组顺序检查各实现的目标模式是否匹配目标对象，第一个匹配的实现会被用来获取数据——因此数组顺序至关重要。一个 Probe 可以由 CLR 与 SQL 实现混合组成。

安全边界：Probe 应被设计为无副作用的函数。调用顺序不确定，引擎可能为优化目标 SQL Server 负载而重排调用；当没有检查需要某 Probe 的数据时，该 Probe 不会被调用。默认规则集中的 Probe 只读取元数据（如更新日志或服务器属性），不会读取表中的用户数据，也不会向数据库或实例写入任何内容，更不会设置任何标志或属性。安全性由使用者负责。

4.1 探针实现（Probe implementation）

探针实现是一个 JSON 对象，其属性定义如下：

除implementation、target、type外，探针实现还可包含requires（显式功能需求，若未满足则该探针不执行、依赖它的检查被跳过并返回警告）和runFor（显式逻辑需求，若未满足则立即返回空结果集），详见 Probe.md。

探针类型与数据来源对照表（见 Probes/README.md）：

4.2 SQL 探针实现

SQL 探针实现的核心属性是query：一段 T-SQL 查询，查询可以按名称引用参数（例如@TargetName）。仓库中的真实探针Custom_DatabaseConfiguration就包含了多个针对不同 SQL Server 版本的实现（参见 MakingCustomChecks_sample.json），例如面向 SQL Server 2016 及以上的实现：

{ "type": "SQL", "target": { "type": "Database", "version": "[13.0,)", "platform": "Windows, Linux", "engineEdition": "OnPremises, ManagedInstance" }, "implementation": { "useDatabase": true, "query": "SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, (SELECT CAST(actual_state AS DECIMAL) FROM [sys].[database_query_store_options]) AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id = 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, db.is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]=@TargetName" } }

注意其中的useDatabase: true键：当查询需要在被评估的数据库上下文中运行时使用它（相当于USE <DATABASENAME>;的替代品）。由于各版本 SQL Server 的 DMV 可能不同，同一个 Probe 往往有多个实现，每个实现都有与规则相同的目标说明，引擎会为每个目标选用最合适的实现。

4.3 External（CLR）探针实现

External 探针实现引用给定程序集中的任意 .NET 类。该类必须实现IProbeImplementation接口：

| 属性 | 类型 | 说明 | | - | - | - | | assembly | string | 指定要加载的程序集。 | | class | string | 类的完整名称（Full class name）。 |

仓库 notebooks/CustomizationSamples 目录下提供了CustomRuleCLRProbe.json、CustomRuleWMIprobe.json、CustomRulePowerShellProbe.json、CustomRuleCmdShellProbe.json、CustomRuleRegistryProbe.json等各类探针的完整示例，并附带了TestsProbeLibrary.dll测试探针程序集，供读者对照学习。

4.4 数据变换（Data Transformation）

探针返回的数据往往不是最终可直接用于条件判断的格式。此时可以在implementation中嵌套transform对象对输出做变换（详见 DataTransformation.md）。例如以下 T-SQL 查询返回形如'10.0.19044.2006'的host_release字符串，用parse变换提取主、次版本号：

"implementation": { "query": "SELECT host_platform, host_release FROM sys.dm_os_host_info", "transform": { "type": "parse", "map": { "host_release": "/^(?<major>\\d+)\\.(?<minor>\\d+)" } } }

变换还可以应用于探针引用（Probe Reference）以提升探针复用性：当某个检查需要某项指标的平均值、而另一个最佳实践涉及同一指标的最大值时，两个检查可以引用同一 Probe 但各自应用自己的变换——不仅代码被复用，数据也被复用（Probe 只会被调用一次）。更多变换类型（aggregate、defaultValue、nameValuePairs、noData、parse、performance、rename、toString）参见 DataTransformation 参考文档。

五、SQL Object Pattern 对象匹配模式

target（规则）与target（探针实现）使用的 SQL Object Pattern 用于过滤规则和探针实现适用的对象：只有匹配该模式的 SQL Server 实例和数据库才会被相应规则应用。借助它，可以针对特定版本、特定版本或特定数据库定制规则。所有属性均为可选——省略某个属性意味着匹配所有值。目标模式可用的属性包括（详见 TargetPattern.md）：

JSONConfiguration.md重点展开的两种模式语法如下。

5.1 正则表达式（Regular expression）

正则表达式用斜杠包裹："/Win*./"。斜杠后可以指定正则选项，例如"/win.*/i"表示不区分大小写的搜索。若字符串不以斜杠开头，则视为精确字符串匹配——字符串"Linux"等价于正则/^Linux$/。

补充（来自 TargetPattern.md）：字符串模式可以是字符串、JSON 对象或字符串模式数组；数组递归匹配“任一元素匹配”。以 JSON 对象表示时只能有一个名为not的属性，其值必须是任意字符串模式，含义为“匹配所有不匹配该值的对象”。另外，SQL Assessment API 基于 .NET 正则表达式，默认不区分大小写，如需区分大小写使用c选项，如"/win.*/c"。

5.2 版本区间列表（Version range list）

版本区间列表是一个版本区间或版本区间数组。单个版本区间等价于只含一个元素的数组。版本区间列表匹配任何与其任一区间匹配的版本：

"version": [ "[10.0.4326,10.0.4371]", "[10.0.5794,10.50)", "[10.50.2806,11.0)", "[11.0.2316,)" ]

5.3 版本区间（Version range）

版本区间由字符串编码：包含一个或两个版本，以逗号分隔，并可选地用圆括号或方括号包裹。若有两个版本，前者必须小于等于后者，它们代表区间边界。版本至少需要以句点分隔的两个数字指定：主版本号和次版本号。该格式遵循 NuGet 版本区间格式。完整对照表如下：

| 版本区间 | 匹配内容 | | - | - | |"10.0"| 精确匹配版本 10.0。 | |"[10.0, 13.0]"| 10.0 与 13.0 之间（含两端）：10.0、10.50、11.0.345、13.0。 | |"(10.0, 13.0)"| 10.0 与 13.0 之间（不含两端）：10.50、11.0.345。不匹配 10.0 或 13.0。 | |"[10.0, 13.1)"| 10.0 与 13.1 之间，不含右边界：10.0、10.50、11.0.345、13.0、13.0.234。不匹配 13.1。 | |"(10.0, 13.1]"| 10.0 与 13.1 之间，不含 10.0。 | |"[10.0,)"| 10.0 及以上（含 10.0）。 | |"(10.0,)"| 10.0 以上，但不含 10.0 本身。 | |"(,10.0]"| 10.0 或以下。 | |"(,10.0)"| 10.0 以下，但不含 10.0。 |

实际示例："version": ["[13.0.5026.0, 14.0)", "[12.0.6024.0, 13.0)", "[15.0)"]匹配 SQL Server 2016 SP2+、2014 SP3+ 以及 2019+。

六、目标模式在探针中的多实现路由

目标模式最典型的应用是让同一个 Probe 族根据目标版本路由到不同实现。以Custom_DatabaseConfiguration探针为例，它针对数据库对象分别提供了三套 SQL 实现：版本(,12.0)（SQL Server 2014 之前）、[12.0, 13.0)（SQL Server 2014）与[13.0,)（SQL Server 2016 及以上）。三套实现的查询几乎相同，差别在于：早期版本无法直接读取 Query Store 状态，因此硬编码0 AS query_store_state；2016 及以上版本则通过useDatabase: true配合子查询(SELECT CAST(actual_state AS DECIMAL) FROM [sys].[database_query_store_options])动态读取。这正是引擎“按顺序选取第一个目标匹配的实现”机制的实战体现。

另一个例子是Custom_EnabledGlobalTraceFlags探针，其实现通过DBCC TRACESTATUS收集全局跟踪标志，并使用transform: { "type": "aggregate", "map": { "TraceFlag": "array" } }将多行跟踪标志聚合成数组，便于检查条件用in操作符判断（如"in": [ 834, "@TraceFlag" ]）：

"Custom_EnabledGlobalTraceFlags": [ { "type": "SQL", "target": { "type": "Server", "engineEdition": "OnPremises, ManagedInstance" }, "implementation": { "query": "DECLARE @tracestatus TABLE (TraceFlag NVARCHAR(40), [Status] tinyint, [Global] tinyint, [Session] tinyint); INSERT INTO @tracestatus EXEC ('DBCC TRACESTATUS WITH NO_INFOMSGS'); IF NOT EXISTS(SELECT * FROM @tracestatus WHERE Global=1) SELECT 0 AS [TraceFlag], 0 AS [Status] ELSE SELECT [TraceFlag], [Status] FROM @tracestatus WHERE Global=1", "transform": { "type": "aggregate", "map": { "TraceFlag": "array" } } } } ]

七、表达式 Expression 与操作符

表达式定义用于决定是否向用户给出建议的计算逻辑。表达式系统是规则集 JSON 中最具表达力的部分。

7.1 字面量与变量

布尔字面量：JSON 值true和false被当作布尔常量。
数字字面量：JSON 数字被当作十进制常量。
字符串字面量：字符串字面量代表字符串，但以"@"字符开头的字符串除外——它们是对变量的引用。
变量：变量由包含其名称、并以"@"前缀开头的字符串表示。变量值由探针设置，被表达式或建议文本消费（如@{variableName}、@{variableName:formatString}）。

7.2 表达式 JSON 对象

只有一个属性的 JSON 对象是按该属性表示的表达式（见下文“属性表达式”）。
具有多个属性的 JSON 对象是AND 运算的简写，其参数是对象的各个属性；结果在可能的情况下转换为布尔类型。因此下面两个表达式等价：

expression1: { "@version": "10.50.0", "@memroySize": 4096 } expression2: { "and": [ {"@version": "10.50.0"}, {"@memroySize": 4096} ] }

7.3 属性表达式（Property Expressions）

任何表达式都可以用 JSON 属性的形式表示：属性名是操作名，属性值是操作参数的数组。参数可以是除条件表达式外的任何表达式。

当属性名以"@"开头时，它不是操作名，而是equal（等于）运算的简写——变量作为第一个参数、唯一属性值作为第二个参数。以下两个表达式等价：

expression1: {"@memorySize": 4096} expression2: { "equal": [ "@memorySize", 4096 ] }

7.4 条件表达式（Condition Expression）

条件表达式可以是任何表达式，也可以是表达式数组。表达式数组是 OR 运算的简写，数组中的各项是操作参数。以下两个表达式等价：

"condition": [ {"@version": "10.50.0"}, {"@memroySize": 4096} ] "condition": { "or": [ {"@version": "10.50.0"}, {"@memroySize": 4096} ] }

注意：OR 的简写形式仅在条件表达式中生效，而 AND 的简写形式在任意位置都生效。例如下面两个表达式等价：

"condition": { "@version": "10.50.0", "@memroySize": 4096 } "condition": { "and": [ {"@version": "10.50.0"}, {"@memroySize": 4096} ] }

7.5 可用操作符参考

表达式中的操作符共分五类（完整参考见 Operators.md）：

逻辑（Logical）

| 操作符 | 参数 | 描述 | | - | :-: | - | | not | (x) | 逻辑非。 | | and | (a..) | 逻辑与。无参数时返回false。 | | or | (a..) | 逻辑或。无参数时返回true。 |

字符串（String）

数学（Math）

| 操作符 | 参数 | 描述 | | - | :-: | - | | ceiling / floor | x | 向上/向下取整。 | | max / min | (a, b) | 取较大/较小值。 | | mul / div / mod | (a..) / (a, b) | 乘 / 除 / 取余。 | | add / sub | (a..) / (a, b) | 加 / 减。 | | bitand / bitor / bitxor | (a..*) | 按位与 / 或 / 异或。 |

集合（Set）

| 操作符 | 参数 | 描述 | | - | :-: | - | | intersect | (a, b) | 集合交集。区分大小写。 | | in | (a, b) | 检查 a 是否在集合 b 中。区分大小写。 | | iin | (a, b) | 同上，不区分大小写。 |

比较（Comparison）

| 操作符 | 同义词 | 参数 | 描述 | | - | - | :-: | - | | lt / gt | less / greater | (a, b) | 小于 / 大于。 | | eq / ieq | equal | (a, b) | 相等，区分/不区分大小写。 | | ge / le | greaterequal / lessequal | (a, b) | 大于等于 / 小于等于。 | | ne / ine | notequal | (a, b) | 不相等，区分/不区分大小写。 | | match / imatch | | (a, b) | 正则表达式匹配，b 视为正则，区分/不区分大小写。 | | interval | | (a, v₁, t₁, …, vₙ, tₙ, d) | 找到第一个大于等于 a 的 tᵢ 并返回对应的 vᵢ；若所有 t 都小于 a 则返回 d。 |

八、综合示例：完整自定义规则集剖析

仓库根目录的 MakingCustomChecks_sample.json 是一个可直接参考的完整自定义规则集，它包含两个自定义检查（QueryStoreOn与Custom_TF834）及两个探针族（Custom_DatabaseConfiguration与Custom_EnabledGlobalTraceFlags），其结构如下：

{ "schemaVersion": "1.0", "version": "0.2", "name": "Custom Checks Ruleset", "rules": [ … ], "probes": { … } }

值得注意的细节：

QueryStoreOn规则同时使用了tags（"CustomRuleset", "Performance", "QueryStore", "Statistics"）、probes（["Custom_DatabaseConfiguration"]）与condition（{"equal": ["@query_store_state", 2]}），完整覆盖了Check属性表中的各字段；
Custom_TF834规则除了definition外，还有一个itemType: "override"的条目，通过targetFilter: { "version": "(,11.0)" }针对 11.0 以下版本提供不同的description、message与helpLink——演示了同一规则 ID 的覆盖机制；
两个探针族各自包含多个按版本路由的 SQL 实现，并演示了transform（aggregate）的用法。

若想禁用内置检查，可以参考 DisablingBuiltInChecks_sample.json：它演示了按规则 ID 禁用指定规则、按TraceFlag标签批量禁用，以及针对名为DBName1、DBName2的数据库禁用默认规则集全部规则（通过DefaultRuleset标签）三种方式。想系统学习自定义规则的读者，还可以查看 CreatingCustomRules.md、DisablingBuiltInRules.md 与 OverridingDefaultThresholds.md 等教程。

九、快速上手与相关资源

编写好规则集后，可通过 PowerShell SqlServer 模块快速发起评估（详见 QuickStart.md）：

Install-Module -Name SqlServer -AllowClobber -Force Get-Module

对本地 SQL Server 实例运行评估：

Get-SqlInstance -ServerInstance 'localhost' | Invoke-SqlAssessment

对本地实例上所有数据库运行评估：

Get-SqlDatabase -ServerInstance 'localhost' | Invoke-SqlAssessment

评估结果中每条规则都带有严重级别（Info / Warning / Critical）、建议文本（Message）、指向官方文档的HelpLink，以及标识来源规则集与版本的Origin属性。

进一步深入可参考的仓库资源：

默认规则集 JSON：ruleset.json
默认规则集可读 CSV 版：DefaultRuleset.csv
自定义规则教程：CreatingCustomRules.md、DisablingBuiltInRules.md、OverridingDefaultThresholds.md
各类探针（T-SQL / WMI / PowerShell / CMD / Registry / External / AzGraph / AzMetadata）参考：Probes 参考目录
自定义规则 Notebook 示例：CustomizationSamples
完整教程 Notebook：SQLAssessmentAPITutorialNotebook.ipynb