SQL-Bewertungs-APISQL Assessment API

Die API für die SQL-Bewertung bietet einen Mechanismus, um die Konfiguration Ihrer SQL Server-Instanz nach Best Practices zu bewerten.SQL Assessment API provides a mechanism to evaluate the configuration of your SQL Server for best practices. Die API umfasst einen vordefinierten Regelsatz, der vom SQL Server Team vorgeschlagene Best Practice-Regeln enthält.The API is delivered with a ruleset containing best practice rules suggested by SQL Server Team. Dieser Regelsatz wird mit der Veröffentlichung neuer Versionen erweitert, aber gleichzeitig wurde die API mit der Absicht konzipiert, eine hochgradig anpassbare und erweiterbare Lösung bereitzustellen.This ruleset is enhancing 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. Benutzer können deshalb die Standardregeln optimieren und eigene Regeln erstellen.So, users can tune the default rules and create their own ones.

Die API für die SQL-Bewertung ist nützlich, wenn Sie sicherstellen möchten, dass Ihre SQL Server-Konfiguration den empfohlenen Best Practices entspricht.SQL Assessment API is useful when you want to make sure your SQL Server configuration is in line with recommended best practices. Nach einer anfänglichen Bewertung kann die Konfigurationsstabilität durch regelmäßig durchgeführte Bewertungen nachverfolgt werden.After an initial assessment, configuration stability can be tracked by regularly scheduled assessments.

Die API kann verwendet werden, um verwaltete Azure SQL-Datenbank-Instanzen und SQL Server 2012-Instanzen oder höher zu bewerten.The API can be used to assess Azure SQL Database Managed Instance and SQL Server versions 2012 and higher. SQL unter Linux wird ebenfalls unterstützt.SQL on Linux is supported.

RegelnRules

Regeln, die gelegentlich auch als Überprüfungen bezeichnet werden, werden in JSON-formatierten Dateien definiert.Rules sometimes referred to as checks, are defined in JSON formatted files. Das Regelsatzformat erfordert, dass ein Regelsatzname und eine Version angegeben werden.Ruleset format requires a ruleset name and version to be specified. Wenn Sie benutzerdefinierte Regelsätze verwenden, können Sie so leicht erkennen, welche Empfehlungen aus welchem Regelsatz stammen.So when you use custom rulesets, you can easily know which recommendations from what ruleset come.

Der von Microsoft bereitgestellte Regelsatz ist auf GitHub verfügbar.Microsoft's shipped ruleset is available on GitHub. Weitere Informationen finden Sie im Repository mit Beispielen.You can visit the samples repository for more details.

Cmdlets für SQL-Bewertung und SMO-ErweiterungSQL Assessment cmdlets and SMO extension

Die API für die SQL-Bewertung ist Bestandteil von SQL Server Management Objects (SMO) (Version von Juli 2019 und höher) und dem SQL Server PowerShell-Modul (Version von Juli 2019 und höher).SQL Assessment API is part of the SQL Server Management Objects (SMO) July 2019 release version and higher and the SQL Server PowerShell module July 2019 release version and higher.

Das SqlServer-Modul enthält zwei neue Cmdlets für die Arbeit mit der API für die SQL-Bewertung:SqlServer module is getting two new cmdlets to work with SQL Assessment API:

  • Get-SqlAssessmentItem: Stellt eine Liste der verfügbaren Bewertungsüberprüfungen für ein SQL Server-Objekt bereit.Get-SqlAssessmentItem – Provides a list of available assessment checks for a SQL Server object

  • Invoke-SqlAssessment: Stellt die Ergebnisse einer Bewertung bereit.Invoke-SqlAssessment – Provides results of an assessment

Das SMO-Framework wird um die API-Erweiterung für die SQL-Bewertung ergänzt, die folgende Methoden bereitstellt:SMO Framework is supplemented by the SQL Assessment API extension that provides the following methods:

  • GetAssessmentItems : Gibt verfügbare Überprüfungen für ein bestimmtes SQL-Objekt zurück (IEnumerable<…>).GetAssessmentItems – Returns available checks for a particular SQL object (IEnumerable<…>)

  • GetAssessmentResults : Führt eine synchrone Auswertung der Bewertung durch und gibt Fehler zurück, sofern vorhanden (IEnumerable<…>).GetAssessmentResults – Synchronously evaluates assessment and returns results and errors if any (IEnumerable<…>)

  • GetAssessmentResultsList : Führt eine asynchrone Auswertung der Bewertung durch und gibt Fehler zurück, sofern vorhanden (Task<…>).GetAssessmentResultsList – Asynchronously evaluates assessment and returns results and errors if any (Task<…>)

Erste Schritte mit den Cmdlets für die SQL-BewertungGet started using SQL Assessment cmdlets

Eine Bewertung wird für ein ausgewähltes SQL Server-Objekt durchgeführt.An assessment is performed against a chosen SQL Server object. Im Standardregelsatz sind nur Überprüfungen für zwei Arten von Objekten enthalten: Server und Datenbank (zusätzlich dazu unterstützt die API zwei weitere Typen: Dateigruppe und Verfügbarkeitsgruppe).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). Wenn Sie eine SQL-Instanz und alle zugehörigen Datenbanken bewerten möchten, müssen Sie die Cmdlets für die SQL-Bewertung für jedes Objekt separat ausführen.If you want to assess a SQL instance and all its databases, you should run the SQL Assessment cmdlets for each object separately. Alternativ können Sie die zu bewertenden Objekte in einer Variablen oder der Pipeline an die Cmdlets für die SQL-Bewertung übergeben.Or you can pass objects for assessment to the SQL Assessment cmdlets in a variable or the pipeline.

SqlServer- und RegisteredServer-Objekte sind austauschbar, deshalb können Sie ein beliebiges dieser Objekte an die Cmdlets für die SQL-Bewertung übergeben.SqlServer and RegisteredServer objects are interchangeable, so you can pass any to the SQL Assessment cmdlets.

Gehen Sie zum Einstieg die folgenden Beispiele durch.Go through the examples below to get started.

  1. Rufen Sie eine Liste der verfügbaren Überprüfungen für eine lokale Standardinstanz ab, um sich mit den Überprüfungen vertraut zu machen.Get a list of available checks for a local default instance to familiarize yourself with the checks. In diesem Beispiel wird die Ausgabe des Get-SqlInstance-Cmdlets per Pipe an das Get-SqlAssessmentItem-Cmdlet übergeben, um das Instanzobjekt zu übergeben.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. Rufen Sie eine Liste der verfügbaren Überprüfungen für alle Datenbanken der Instanz ab.Get a list of available checks for all databases of the instance. Hier verwenden wir das Get-Item-Cmdlet und einen mit dem Windows PowerShell-SQL Server-Anbieter implementierten Pfad, um eine Liste der Datenbanken abzurufen. Anschließend wird die Liste per Pipe an das Get-SqlDatabase-Cmdlet übergeben.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
    

    Sie können hierzu auch das Get-SqlDatabase-Cmdlet verwenden.Also, you can use the Get-SqlDatabase cmdlet to do the same.

    Get-SqlDatabase -ServerInstance 'localhost' | Get-SqlAssessmentItem
    
  3. Rufen Sie eine Liste der verfügbaren Überprüfungen für alle Datenbanken der Instanz ab.Get a list of available checks for all databases of the instance. Hier verwenden wir das Get-Item-Cmdlet und einen mit dem Windows PowerShell-SQL Server-Anbieter implementierten Pfad, um eine Liste der Datenbanken abzurufen. Anschließend wird die Liste per Pipe an das Get-SqlDatabase-Cmdlet übergeben.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
    

    Sie können hierzu auch das Get-SqlDatabase-Cmdlet verwenden.Also, you can use the Get-SqlDatabase cmdlet to do the same.

    Get-SqlDatabase -ServerInstance 'localhost' | Get-SqlAssessmentItem
    
  4. Rufen Sie die Bewertung für die Instanz auf, und speichern Sie die Ergebnisse in einer SQL-Tabelle.Invoke assessment for the instance and save the results to a SQL table. In diesem Beispiel wird die Ausgabe des Get-SqlInstance-Cmdlets per Pipe an das Invoke-SqlAssessment-Cmdlet übergeben, dessen Ergebnisse per Pipe an das Write-SqlTableData-Cmdlet übergeben werden.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. Das Invoke-Assessment-Cmdlet wird in diesem Beispiel mit dem -FlattenOutput-Parameter ausgeführt.The Invoke-Assessment cmdlet is run with the -FlattenOutput parameter in this example. Durch diesen Parameter ist die Ausgabe für das Write-SqlTableData-Cmdlet geeignet.This parameter makes the output suitable for the Write-SqlTableData cmdlet. Fehlt der Parameter, löst das Cmdlet einen Fehler aus.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
    

    Rufen wir jetzt eine Bewertung für alle Datenbanken der Instanz auf und fügen die Ergebnisse in dieselbe Tabelle ein.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. Folgen Sie den Beschreibungen und Links in der Tabelle, um die Empfehlungen besser zu verstehen.Follow descriptions and links in the table to further understand the recommendations.

  6. Passen Sie die Regeln basierend auf Ihrer Umgebung und den Organisationsanforderungen an (siehe unten).Customize the rules based on your environment and organizational requirements (see below).

  7. Planen Sie eine Aufgabe oder einen Auftrag, um die Bewertung regelmäßig oder bei Bedarf auszuführen, um den Fortschritt zu messen.Schedule a task or a job to run the assessment regularly or on-demand to measure progress.

Anpassen von RegelnCustomizing rules

Regeln sind so entworfen, dass sie angepasst und erweitert werden können.Rules are designed to be customizable and extensible. Der Regelsatz von Microsoft ist so konzipiert, dass er für die meisten Umgebungen geeignet ist.Microsoft's ruleset is designed to work for most environments. Es gibt jedoch keinen Regelsatz, der für jede einzelne Umgebung funktioniert.However, it's impossible to have one ruleset that works for every single environment. Benutzer können eigene JSON-Dateien schreiben und vorhandene Regeln anpassen oder neue Regeln erstellen.Users can write their own JSON files and customize existing rules or add new ones. Im Repository mit Beispielen finden Sie Beispiele für Anpassungen und den vollständigen von Microsoft veröffentlichten Regelsatz.Examples of customization and complete Microsoft released ruleset are available in the samples repository. Weitere Informationen zum Ausführen der Cmdlets für die SQL-Bewertung mit benutzerdefinierten JSON-Dateien finden Sie im Get-Help-Cmdlet.For more details on how to run the SQL Assessment cmdlets with custom JSON files, use the Get-Help cmdlet.

Verfügbare Optionen für die RegelanpassungOptions available with rule customization feature

Aktivieren/Deaktivieren bestimmter Regeln oder Regelgruppen (mithilfe von Tags)Enabling/disabling certain rules or groups of rules (using tags)

Sie können bestimmte Regeln unterdrücken, wenn sie nicht auf Ihre Umgebung anwendbar sind oder bis geplante Arbeiten zur Behebung des Problems abgeschlossen sind.You can silence specific rules when they aren't applied to your environment or until scheduled work is done to rectify the issue.

Ändern von SchwellenwertparameternChanging threshold parameters

Bestimmte Regeln verfügen über Schwellenwerte, die mit dem aktuellen Wert einer Metrik verglichen werden, um Probleme zu ermitteln.Specific rules have thresholds that are compared against the current value of a metric to find out an issue. Wenn die Standardschwellenwerte nicht geeignet sind, können Sie sie ändern.If the default thresholds don't fit, you can change them.

Hinzufügen weiterer Regeln, die von Ihnen oder Drittanbietern geschrieben wurdenAdding more rules written by you or third parties

Sie können Regelsätze bündeln, indem Sie dem Aufruf der API für die SQL-Bewertung mindestens eine JSON-Datei als Parameter hinzufügen.You can string together rulesets by adding one or more JSON files as parameters to your SQL Assessment API call. Ihre Organisation kann solche Dateien schreiben oder von einem Drittanbieter erwerben.Your organization might write those files or obtain them from a third party. So können Sie beispielsweise Ihre JSON-Datei, die bestimmte Regeln aus dem Microsoft-Regelsatz deaktiviert, eine weitere JSON-Datei mit nützlichen Regeln für Ihre Umgebung von einem Branchenexperten und danach eine weitere JSON-Datei verwenden, die einige Schwellenwerte in dieser JSON-Datei ändert.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.

Wichtig

Es wird dringend davon abgeraten, Regelsätze aus nicht vertrauenswürdigen Quellen zu verwenden. Setzen Sie diese erst ein, wenn Sie sie gründlich untersucht und sich davon überzeugt haben, dass ihre Verwendung sicher ist.We urge you not to use rulesets that come from untrusted sources until you thoroughly review them to make sure they are safe.

Nächste SchritteNext steps

Sehen Sie sich SQL Server Management Objects (SMO) und PowerShell an.Take a look at SQL Server Management Objects (SMO) and PowerShell.