API Оценки SQLSQL Assessment API

Оценка SQL API предоставляет механизм для вычисления конфигурации SQL Server для получения рекомендаций.SQL Assessment API provides a mechanism to evaluate the configuration of your SQL Server for best practices. API поставляется с набором правил, содержащим рекомендации, предлагаемые командой разработчиков SQL Server.The API is delivered with a ruleset containing best practice rules suggested by SQL Server Team. Этот набор правил совершенствуется по мере выпуска новых версий, но в то же время API-интерфейс создается с целью предоставления решения с широкими возможностями настройки и расширяемости.This ruleset is enhanced with the release of new versions but at the same time, the API is built with the intent to give a highly customizable and extensible solution. Таким образом, пользователи могут настраивать правила по умолчанию и создавать собственные.So, users can tune the default rules and create their own.

Оценка SQL API полезна, если вы хотите убедиться в том, что конфигурация SQL Server согласуется с рекомендуемыми лучшими методиками.SQL Assessment API is useful when you want to make sure your SQL Server configuration is in line with recommended best practices. После первоначальной оценки стабильность конфигурации отслеживается при помощи регулярных запланированных оценок.After an initial assessment, configuration stability can be tracked by regularly scheduled assessments.

API можно использовать для оценки:The API can be used to assess:

  • Управляемого экземпляра Базы данных SQL Azure и SQL Server версии 2012 и выше;Azure SQL Database Managed Instance and SQL Server versions 2012 and higher.

  • SQL в системах на базе Linux;SQL on Linux-based systems.

API также используется расширением Оценки SQL Server для Azure Data Studio (ADS).The API is also used by SQL Server Assessment Extension for Azure Data Studio (ADS).

ПравилаRules

Правила, иногда называемые проверками, определяются в файлах в формате JSON.Rules (sometimes referred to as checks) are defined in JSON formatted files. Для набора правил требуется указать имя и версию набора правил.The ruleset format requires a ruleset name and version to be specified. При использовании пользовательских наборов правил можно легко узнать, какие рекомендации исходят из какого набора правил.When you use custom rulesets, you can easily know which recommendations from what ruleset come.

Поставляемый Майкрософт набор правил доступен на сайте GitHub.Microsoft's shipped ruleset is available on GitHub. Дополнительные сведения можно найти в репозитории примеров.You can visit the samples repository for more details.

Командлеты Оценки SQL и связанные расширенияSQL Assessment cmdlets and associated extensions

API Оценки SQL является частью:The SQL Assessment API is part of:

Прежде чем приступить к работе с API Оценки SQL, убедитесь в том, что выполнено следующее:Before you start using the SQL Assessment API, make sure to:

Модуль SqlServer получил два новых командлета для работы с API Оценки SQL:The SqlServer module is getting two new cmdlets to work with SQL Assessment API:

  • Get-SqlAssessmentItem — предоставляет список доступных проверок оценки для объекта SQL Server;Get-SqlAssessmentItem – Provides a list of available assessment checks for a SQL Server object

  • Invoke-SqlAssessment — предоставляет результаты оценки.Invoke-SqlAssessment – Provides results of an assessment

Платформа SMO дополняется расширением для API оценки SQL, которое предоставляет следующие методы:SMO Framework is supplemented by the SQL Assessment API extension that provides the following methods:

  • GetAssessmentItems — возвращает доступные проверки для конкретного объекта SQL (IEnumerable<…>);GetAssessmentItems – Returns available checks for a particular SQL object (IEnumerable<…>)

  • GetAssessmentResults — синхронно оценивает оценку и возвращает результаты и ошибки, если таковые имеются (IEnumerable<…>);GetAssessmentResults – Synchronously evaluates assessment and returns results and errors if any (IEnumerable<…>)

  • GetAssessmentResultsList — асинхронно оценивает оценку и возвращает результаты и ошибки, если таковые имеются (Task<…>).GetAssessmentResultsList – Asynchronously evaluates assessment and returns results and errors if any (Task<…>)

Начало работы с командлетами оценки SQLGet started using SQL Assessment cmdlets

Оценка выполняется для выбранного объекта SQL Server.An assessment is performed against a chosen SQL Server object. В наборе правил по умолчанию существуют проверки только двух видов объектов: Server и Database (в дополнение к ним API-интерфейс поддерживает два других типа: Filegroup и AvailabilityGroup).In the default ruleset, there are checks for two kinds of objects only: Server and Database (in addition to them, the API supports two more kinds: Filegroup and AvailabilityGroup). Если вы хотите оценить экземпляр SQL и все его базы данных, следует запускать командлеты оценки SQL для каждого объекта отдельно.If you want to assess a SQL instance and all its databases, you should run the SQL Assessment cmdlets for each object separately. Или можно передать объекты для оценки в командлеты оценки SQL в переменной или конвейере.Or you can pass objects for assessment to the SQL Assessment cmdlets in a variable or the pipeline.

Объекты SqlServer и RegisteredServer взаимозаменяемы, поэтому можно передавать в командлеты оценки SQL любой из них.SqlServer and RegisteredServer objects are interchangeable, so you can pass any to the SQL Assessment cmdlets.

Чтобы приступить к работе, ознакомьтесь с приведенными ниже примерами.Go through the examples below to get started.

  1. Получите список доступных проверок для локального экземпляра по умолчанию, чтобы познакомиться с проверками.Get a list of available checks for a local default instance to familiarize yourself with the checks. В этом примере выходные данные командлета Get-SqlInstance передаются по конвейеру в командлет Get-SqlAssessmentItem, чтобы передать в него объект экземпляра.In this example, we're piping the output of the Get-SqlInstance cmdlet to the Get-SqlAssessmentItem cmdlet to pass the instance object to it.

    Get-SqlInstance -ServerInstance 'localhost' | Get-SqlAssessmentItem
    
  2. Получите список доступных проверок для всех баз данных экземпляра.Get a list of available checks for all databases of the instance. Здесь мы используем командлет Get-Item и путь, реализованный в поставщике SQL Server для Windows PowerShell, чтобы получить список баз данных, а затем передать его по конвейеру в командлет Get-SqlDatabase.Here, we're using the Get-Item cmdlet and a path implemented with the Windows PowerShell SQL Server provider to get a list of the databases, and then piping it to the Get-SqlDatabase cmdlet.

    Get-Item SQLSERVER:\SQL\localhost\default | Get-SqlAssessmentItem
    

    Кроме того, для этих же целей можно использовать командлет Get-SqlDatabase.Also, you can use the Get-SqlDatabase cmdlet to do the same.

    Get-SqlDatabase -ServerInstance 'localhost' | Get-SqlAssessmentItem
    
  3. Получите список доступных проверок для всех баз данных экземпляра.Get a list of available checks for all databases of the instance. Здесь мы используем командлет Get-Item и путь, реализованный в поставщике SQL Server для Windows PowerShell, чтобы получить список баз данных, а затем передать его по конвейеру в командлет Get-SqlDatabase.Here, we're using the Get-Item cmdlet and a path implemented with the Windows PowerShell SQL Server provider to get a list of the databases, and then piping it to the Get-SqlDatabase cmdlet.

    Get-Item SQLSERVER:\SQL\localhost\default | Get-SqlAssessmentItem
    

    Кроме того, для этих же целей можно использовать командлет Get-SqlDatabase.Also, you can use the Get-SqlDatabase cmdlet to do the same.

    Get-SqlDatabase -ServerInstance 'localhost' | Get-SqlAssessmentItem
    
  4. Вызовите оценку для экземпляра и сохраните результаты в таблицу SQL.Invoke assessment for the instance and save the results to a SQL table. В этом примере выходные данные командлета Get-SqlInstance передаются по конвейеру в командлет Invoke-SqlAssessment, результаты которого передаются в командлет Write-SqlTableData.In this example, we're piping the output of the Get-SqlInstance cmdlet to the Invoke-SqlAssessment cmdlet, which results are piped to the Write-SqlTableData cmdlet. Командлет Invoke-Assessment в этом примере выполняется с параметром -FlattenOutput.The Invoke-Assessment cmdlet is run with the -FlattenOutput parameter in this example. Этот параметр делает выходные данные подходящими для командлета Write-SqlTableData.This parameter makes the output suitable for the Write-SqlTableData cmdlet. Если опустить этот параметр, то в последнем случае будет выдано сообщение об ошибке.The latter raises an error if you omit the parameter.

    Get-SqlInstance -ServerInstance 'localhost' |
    Invoke-SqlAssessment -FlattenOutput |
    Write-SqlTableData -ServerInstance 'localhost' -DatabaseName SQLAssessmentDemo -SchemaName Assessment -TableName Results -Force
    

    Теперь давайте вызовем оценку всех баз данных экземпляра и добавим результаты в ту же таблицу.Now let's invoke an assessment for all databases of the instance and add the results to the same table.

    Get-SqlDatabase -ServerInstance 'localhost' |
    Invoke-SqlAssessment -FlattenOutput |
    Write-SqlTableData -ServerInstance 'localhost' -DatabaseName SQLAssessmentDemo -SchemaName Assessment -TableName Results -Force
    
  5. Для дальнейшего анализа рекомендаций следуйте описанию и ссылкам в таблице.Follow descriptions and links in the table to further understand the recommendations.

  6. Настройте правила в соответствии со средой и требованиями организации (см. ниже).Customize the rules based on your environment and organizational requirements (see below).

  7. Запланируйте задачу или задание для регулярного выполнения оценки или оценки по запросу для измерения хода выполнения.Schedule a task or a job to run the assessment regularly or on-demand to measure progress.

Настройка правилCustomizing rules

Правила предназначены для повышения возможностей настройки и расширения.Rules are designed to be customizable and extensible. Набор правил Майкрософт подходит для работы в большинстве сред.Microsoft's ruleset is designed to work for most environments. Однако невозможно иметь один набор правил, который будет работать для каждой отдельной среды.However, it's impossible to have one ruleset that works for every single environment. Пользователи могут создавать собственные файлы JSON и настраивать существующие правила или добавлять новые.Users can write their own JSON files and customize existing rules or add new ones. Примеры настройки и полный набор правил Майкрософт доступны в репозитории примеров.Examples of customization and complete Microsoft released ruleset are available in the samples repository. Дополнительные сведения о запуске командлетов оценки SQL с пользовательскими файлами JSON можно получить с помощью командлета Get-Help.For more details on how to run the SQL Assessment cmdlets with custom JSON files, use the Get-Help cmdlet.

Доступные параметры для настройки правилOptions available with rule customization feature

Включение и отключение определенных правил или групп правил (с помощью тегов)Enabling/disabling certain rules or groups of rules (using tags)

Вы можете отключить сообщения отдельных правил, если они не применяются к среде или пока не будут выполнены запланированные действия по устранению проблемы.You can silence specific rules when they aren't applied to your environment or until scheduled work is done to rectify the issue.

Изменение пороговых значенийChanging threshold parameters

Отдельные правила имеют пороговые значения, которые сравниваются с текущим значением метрики для выявления проблем.Specific rules have thresholds that are compared against the current value of a metric to find out an issue. Если пороговые значения по умолчанию не подходят, их можно изменить.If the default thresholds don't fit, you can change them.

Добавление правил, написанных вами или сторонними разработчикамиAdding more rules written by you or third parties

Вы можете объединить наборы правил, добавив один или несколько JSON-файлов в качестве параметров вызова API оценки SQL.You can string together rulesets by adding one or more JSON files as parameters to your SQL Assessment API call. Ваша организация может написать эти файлы самостоятельно или получить их от третьей стороны.Your organization might write those files or obtain them from a third party. Например, можно использовать файл JSON, который отключает определенные правила из набора Майкрософт, затем файл JSON, написанный экспертом отрасли, который будет включать правила, полезные для вашей среды, и, наконец, третий файл JSON, который будет изменять некоторые пороговые значения второго файла.For example, you can have your JSON file that disables specific rules from the Microsoft ruleset, and another JSON file by an industry expert that include rules you find useful for your environment, followed by another JSON file that changes some threshold values in that JSON file.

Важно!

Мы настоятельно рекомендуем не использовать наборы правил из ненадежных источников, пока тщательно не проверите их и не убедитесь в их безопасности.We urge you not to use rulesets that come from untrusted sources until you thoroughly review them to make sure they are safe.

Дальнейшие действияNext steps