示例工程数据库教程后端【免费下载链接】sql-server-samplesAzure 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/manage/sql-assessment-api。本篇文章围绕其自定义机制的核心概念——**规则Rule展开规则以 JSON 对象表示既可定义definition全新的检查项也可覆盖override**一个或多个既有检查。读完本文你将掌握规则的全部属性语义、target 匹配模式、消息模板语法、probe 引用方式并能够基于仓库中的示例文件独立编写、加载和调试属于自己的规则集。规则结构图一个规则对象由 itemType、id、target/targetFilter、tags、displayName、message、condition、probes 及任意自定义参数组成。规则在 SQL Assessment API 中的角色在深入了解规则属性之前先明确规则在整个评估流程中的位置。SQL Assessment API 通过两阶段流程给出针对性的最佳实践建议详见 Understanding rules and probes为给定目标构建检查清单根据目标服务器或数据库的类型、版本、平台等特征生成一份完整的检查项集合逐项执行检查并报告违规对清单中的每项检查验证目标是否满足最佳实践不满足时产生提示消息。规则就是构建检查清单的原材料。每条规则要么定义一个全新的检查要么修改一个或多个既有检查。规则存放在规则集ruleset中每个规则集拥有独立的name与version详见 Ruleset file structure。多个规则集可以按顺序逐个加载进评估引擎引擎构建清单时按加载顺序依次应用规则——后加载的规则可以覆盖先前规则设定的值这是理解规则叠加效果的关键。一个检查可以被多条规则影响第一条规则必须负责定义该检查并分配唯一的字符串 ID后续规则则通过 ID 或标签tags引用该检查进行覆盖这也使覆盖操作能够一次性作用于多个检查。规则Rule的 JSON 结构总览规则是一个 JSON 对象其核心结构如下摘自 Rule 结构定义{ itemType: definition | override, id: Check ID(s) or tags, target?: { type: Server | Database, version: Version pattern, ...: ... }, targetFilter?: { type: Server | Database, version: Version pattern, ...: ... }, tags?: [Tag 1, Tag 2, ...], displayName?: Short descriptive name, description?: Long description, message?: Message template, level?: Information | Low | Medium | High, helpLink?: Hyperlink to an article, probes?: [ Probe ref 1, Probe ref 2, ... ], condition?: Condition expression, parameter 1: param 1 value }其中带?的属性均为可选除上述标准属性外规则还可以携带任意自定义参数见下文parameters一节这些参数会被传递给条件表达式、消息模板、probe 参数与数据转换。规则属性详解itemType定义还是覆盖itemType是规则最核心的属性取值仅允许definition或overridedefinition定义一个新检查。该规则中的目标模式target、显示名、消息、条件、级别等属性共同组装出一个全新的检查项override修改一个或多个既有检查。覆盖规则通过id或标签定位既有检查仅需给出要修改的属性即可未给出的属性保持不变。一个检查可以被多条覆盖规则依次修改最终生效值取决于规则应用顺序。id定义或修改的检查标识id用于指定本规则定义或修改的检查。它有两种形态单个字符串被定义/修改的检查的唯一 ID字符串数组由检查 ID 或标签tags组成的列表规则将一次性修改多个检查。当列表中含多个标签时只要检查拥有其中任意一个标签就会被该规则影响OR 语义。这一点在批量覆盖场景中非常实用例如《Understanding rules and probes》中的示例——一条规则同时禁用MaxMemory检查与所有带Performance标签的检查{ id: [ MaxMemory, Performance ], itemType: override, targetFilter: { platform: Linux }, enabled: false }tags检查分类标签tags是一个短字符串数组用于给检查分类方便按组批量管理。例如带 Memory 标签的检查来自内存相关的最佳实践带 Performance 标签的检查来自性能优化建议。单个单词的标签效果最佳便于被覆盖规则通过id数组引用。target规则适用的目标模式target是一个 JSON 对象用于筛选规则适用的对象。只有被评估对象匹配target模式时规则才会被应用。目标模式的完整语法见 Target pattern其核心属性包括typeServer或Database可逗号分隔组合version版本范围模式例如[13.0,)表示 SQL Server 2016 及以上platformWindows、LinuxengineEditionPersonalOrDesktopEngine、Standard、Enterprise、Express、AzureDatabase、DataWarehouse、StretchDatabase、ManagedInstance并支持两个快捷别名Azure云上四种版本与SqlServer四种本地版本name/serverName/machineType按名称、实例名或机器类型Physical、AzureVm、Hypervisor、Other筛选。所有属性均为可选省略的属性意味着匹配任意值。字符串匹配支持精确字符串、/.../包裹的 .NET 正则表达式默认忽略大小写c选项开启大小写敏感以及{ not: ... }否定模式版本匹配支持开闭区间组合如[10.0, 13.0)、(,11.0)格式遵循 NuGet 版本区间规范。例如下面的target只匹配非系统库target: { type: Database, version: [13.0,), platform: Windows, Linux, engineEdition: OnPremises, ManagedInstance, name: { not: /^(master|tempdb|model)$/ } }targetFilter覆盖专用的目标筛选targetFilter与target语法完全相同但仅用于override类型的规则。它的作用是在覆盖规则内部进一步限定哪些目标上的检查要被修改使同一覆盖规则可以针对不同版本/版本的服务器差异化地修改参数。典型用法见 RulesandProbes.md 中的示例同一个MaxMemory覆盖规则通过targetFilter.engineEdition分别给 Standard131072与 Express1410设置不同的内存上限参数。displayName清单中展示的短名称displayName是检查在清单checklist中展示的简短名称。可以把它类比为规则如果单独存成文件时的文件名——通常言简意赅地说明该检查在检查什么例如 Query Store should be active。message面向用户的提示消息模板message是字符串形式的模板用于生成展示给用户的建议消息。当检查发现配置不符合最佳实践即条件求值为 false时该消息会被输出。模板语法仿照 C# 字符串插值用花括号包裹前缀的变量名即可插入 probe 返回的数据或检查计算出的值。完整的模板语法详见 Message templatemessage: Drop hypothetical {IndexName} index for {Schema}.{Object}消息模板还支持 .NET 格式说明符变量名后跟:分隔的格式串message: Current fragmentation level is {fragmentation:P2}输出示例Current fragmentation level is 37.20%。对于字符串类型的值格式串还有特殊扩展语义当值为非空时格式串中的#占位符会被字符串值本身替换值为空时整段格式串不输出。这在拼接有则补充、无则省略的句子片段时非常有用message: Create index on {Table} with key columns {KeyCols}{IncludedCols: and included columns: #}description检查背后的长说明description用较长篇幅解释为什么这个检查关注该问题简要讨论检测到的问题所带来的影响。它帮助评估报告阅读者理解检查的来龙去脉。helpLink最佳实践参考链接helpLink指向解释最佳实践建议与修复方案的参考文章的超链接。在自定义规则中可填入指向内部知识库或官方文档的 URL例如helpLink: https://learn.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-storelevel问题严重级别level表示检查所发现问题一旦触发的严重级别取值仅限Information、Low、Medium、High四档。注意如果规则未显式指定level默认行为以内置规则集为准Information是常见的默认档位。probes获取检查所需数据的探针引用probes数组包含本检查所需的探针probe引用。检查本身不直接向目标服务器或数据库取数而是委托给探针探针负责通过 T-SQL 查询、WMI、注册表、Azure 元数据服务乃至自定义 .NET 代码等手段采集数据。详见 Probe reference 与 Probe。最简单的引用形式是直接写探针 ID 字符串probes: [ Custom_DatabaseConfiguration ]完整形式是 JSON 对象可携带alias别名、params参数与transform数据转换多次调用同一探针当检查需要对不同参数各调用一次探针时可用不同alias区分结果并通过Alias::OutputVar语法引用各次调用的输出例如分别用FirstDisk、SecondDisk别名探测 C: 盘与 D: 盘的剩余空间然后比较探针间数据传递一个探针的输出可以作为另一个探针的参数参数表达式写成db_files::volume_id这样的形式即可。当一个检查引用多个探针时最终数据集由各探针返回行的全部组合构成类似 T-SQL 的CROSS JOIN条件表达式会对每一行组合分别求值产生多少个 false 就输出多少条消息。condition最佳实践的形式化表达condition是一个 JSON 对象树形式的表达式引用检查参数与探针数据。表达式返回true表示最佳实践已被实现若求值为false则向用户展示message。条件表达式支持算术与逻辑运算例如condition: { equal: [ query_store_state, 2 ] }上述条件检查探针返回的query_store_state是否等于 2即 Query Store 处于 Read Write 模式。完整的运算符清单参见 Operators。条件求值按行执行若某探针产出 2 行、另一探针产出 3 行条件将被求值 2×36 次其中 2 次为 false 时检查会产出 2 条消息——这保证了诸如多磁盘空间不足这类逐磁盘判断的场景能够分别报告。parameters任意自定义参数除标准属性外规则可以携带任意自定义属性作为参数。它们会被传递给条件表达式、消息模板、探针参数以及数据转换与探针返回的数据一同参与计算。这也是覆盖规则修改检查阈值的主要手段。例如 RulesandProbes.md 中的示例通过limit参数修改MaxMemory检查的阈值{ id: MaxMemory, itemType: definition, target: { type: Server, version: [11.0,) }, limit: 2147483647 }随后用一条覆盖规则将同一检查的limit改为2000000000{ id: MaxMemory, itemType: override, limit: 2000000000 }完整实战从零定义一条检查含探针仓库根目录下的 MakingCustomChecks_sample.json 提供了一个可直接加载的完整规则集。它以QueryStoreOn检查为例展示了规则 探针如何协同工作{ schemaVersion: 1.0, version: 0.2, name: Custom Checks Ruleset, rules: [ { 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://learn.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store, probes: [ Custom_DatabaseConfiguration ], condition: { equal: [ query_store_state, 2 ] } } ], probes: { Custom_DatabaseConfiguration: [ { type: SQL, target: { type: Database, version: [13.0,) }, 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, ... FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]TargetName } } ] } }这个示例揭示了几个关键设计规则集三层结构schemaVersion文件格式版本当前为 1.0、name/version规则集身份标识、rules数组与probes对象详见 Ruleset file structure。rules与probes都是可选的——因为一个规则集可以复用另一个规则集中定义的探针探针可以有多套实现同一个Custom_DatabaseConfiguration探针针对不同 SQL Server 版本如(,12.0)、[12.0, 13.0)、[13.0,)各有一份 T-SQL 实现因为不同版本的动态管理视图并不一致。引擎会为目标选择第一个匹配 target 模式的实现因此实现数组中的顺序很重要详见 Probe数据转换探针实现内可以内嵌transform对输出做后处理例如Custom_EnabledGlobalTraceFlags探针用aggregate转换把TraceFlag聚合成数组供in条件使用版本兼容的优雅降级SQL Server 2016 之前的版本没有 Query Store探针实现直接返回0 AS query_store_state条件自然不满足消息照样输出——这就是多版本兼容检查的标准写法。同文件还演示了Custom_TF834检查定义 覆盖成对出现先以definition定义TF 834 启用大页分配检查并设定level: Information再用override针对 SQL Server 2012 之前的版本targetFilter.version: (,11.0)替换其description、message与helpLink因为旧版本上该跟踪标志的适用场景不同。实战按 ID 或标签批量禁用内置检查仓库根目录下的 DisablingBuiltInChecks_sample.json 展示了最常用的覆盖场景——禁用内置检查{ schemaVersion: 1.0, version: 0.2, name: Custom Overrides, rules: [ { id: LatestCU, itemType: override, enabled: false }, { id: [TraceFlag], itemType: override, enabled: false }, { id: [DefaultRuleset], itemType: override, targetFilter: { type: Database, name: /^(DBName1|DBName2)$/ }, enabled: false } ] }要点解读每个检查都有enabled属性默认true当所有规则应用完毕后该属性为 false引擎就会跳过此检查见 RulesandProbes.md按单个 IDLatestCU、单个标签TraceFlag或正则匹配的数据库名DefaultRuleset标签 targetFilter限定DBName1/DBName2都能实现精准禁用检查进入清单并不等于会被执行enabled属性是最终裁决开关。规则与检查的完整生命周期综合本文内容一条规则的生效路径可以总结为加载规则集按顺序加载进评估引擎nameversion标识规则集身份schemaVersion校验文件格式匹配引擎用目标对象的类型、版本、平台、版本类型、名称等属性与规则的target模式比对决定规则是否应用于当前目标组装definition规则创建检查后续override规则按 ID/标签命中并逐条修改同一检查的最终属性是定义值 各覆盖值叠加的结果取数检查通过probes引用探针取数探针多实现时按 target 匹配选择第一个命中实现无检查需要时探针根本不会被调用探针被设计为无副作用函数调用顺序不固定引擎可能为降低目标负载而重排调用判定condition对探针数据的每一行组合求值false 即输出由message模板渲染出的建议消息并按level标注严重程度。延伸阅读Understanding rules and probes规则与探针的协同机制、检查生命周期Target patterntarget / targetFilter 的完整匹配语法字符串模式、正则、版本区间Probe reference探针引用的alias、params、transform及探针间传参Probe探针定义与多实现选择规则、各探针类型说明Message template消息模板插值与格式说明符Ruleset file structure规则集文件的三层 JSON 结构Customization 目录本地变量、数据转换等进阶主题官方示例MakingCustomChecks_sample.json、DisablingBuiltInChecks_sample.json入门快速上手QuickStart 与 Tutorials创建自定义规则、禁用内置规则、覆盖默认阈值等分步教程赞分享示例工程数据库教程后端【免费下载链接】sql-server-samplesAzure 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 Assessment API 定制化指南创建自定义规则、禁用内置检查与覆盖默认阈值 SQL Assessment API 是微软官方提供的一套基于最佳示例工程数据库教程后端SQL Assessment API 实战禁用内置检查规则的自定义规则集配置指南SQL Assessment API 实战禁用内置检查规则的自定义规则集配置指南 SQL Assessment API 是官方开源的 SQL Server 最示例工程数据库教程后端SQL Assessment API 自定义规则之 RoleRequirement角色需求完全指南SQL Assessment API 自定义规则之 RoleRequirement角色需求完全指南 导读 RoleRequirement.md 是 SQL示例工程数据库教程后端上一篇推荐开源项目Pedis — 并行Redis数据库下一篇WebSocket长连接技术终极指南构建实时通信应用的10个关键步骤创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考