Verwenden von Token in Auftragsschritten
Gilt für: 
SQL Server Azure SQL Managed Instance
Wichtig
In Azure SQL Managed Instance werden derzeit die meisten, aber nicht alle, SQL Server-Agent-Features unterstützt. Details dazu finden Sie unter T-SQL-Unterschiede zwischen Azure SQL Managed Instance und SQL Server.
Der SQL Server-Agent ermöglicht die Verwendung von Token in Transact-SQL-Auftragsschrittskripts. Durch die Verwendung von Token verfügen Sie beim Schreiben von Auftragsschritten über dieselbe Flexibilität, die die Verwendung von Variablen beim Schreiben von Softwareprogrammen bietet. Die von Ihnen in ein Auftragsschrittskript eingefügten Token werden vom SQL Server-Agent zur Laufzeit ersetzt, bevor der Auftragsschritt vom Transact-SQL-Subsystem ausgeführt wird.
Grundlegendes zum Verwenden von Token
Wichtig
Jeder Windows-Benutzer mit Schreibberechtigungen für das Windows-Ereignisprotokoll kann auf Auftragsschritte zugreifen, die durch SQL Server -Agent-Warnungen oder WMI-Warnungen aktiviert werden. Zur Vermeidung dieses Sicherheitsrisikos sind SQL Server -Agent-Tokens, die in von Warnungen aktivierten Aufträgen verwendet werden können, standardmäßig deaktiviert. Dabei handelt es sich um folgende Token: A-DBN, A-SVR, A-ERR, A-SEV, A-MSGund WMI(Eigenschaft). In dieser Version ist die Verwendung von Token auf alle Warnungen ausgeweitet.
Wenn Sie diese Token verwenden müssen, stellen Sie zuvor sicher, dass ausschließlich Mitglieder von vertrauenswürdigen Windows-Sicherheitsgruppen, wie der Administratorengruppe, über Schreibberechtigungen für das Ereignisprotokoll des Computers verfügen, auf dem SQL Server ausgeführt wird. Klicken Sie dann zum Aktivieren dieser Token im Objekt-Explorer mit der rechten Maustaste auf SQL Server-Agent , wählen Sie Eigenschaften, und wählen Sie anschließend auf der Seite Warnungssystem die Option Token für alle Auftragsantworten auf Warnungen ersetzen aus.
SQL Server Agent-Token können einfach und effizient ersetzt werden: Der SQL Server -Agent ersetzt das Token durch ein genaues Zeichenfolgenliteral. Die Groß- und Kleinschreibung ist bei Token grundsätzlich zu beachten. Dies muss in den Auftragsschritten berücksichtigt werden, damit die verwendeten Token richtig angegeben werden oder die Ersatzzeichenfolge in den richtigen Datentyp konvertiert wird.
Mit der folgenden Anweisung können Sie z. B. den Namen der Datenbank in einem Auftragsschritt drucken:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
In diesem Beispiel wird das Makro ESCAPE_SQUOTE mit dem Token A-DBN eingefügt. Zur Laufzeit ersetzt das Token A-DBN durch den entsprechenden Datenbanknamen. Das Escapemakro umgeht alle einfachen Anführungszeichen, die möglicherweise unbeabsichtigt in der Zeichenfolge, durch die das Token ersetzt werden soll, übergeben werden. SQL Server Agent ersetzt in der endgültigen Zeichenfolge jedes einfache Anführungszeichen durch zwei einfache Anführungszeichen.
Wenn beispielsweise als Ersatz für das Token die Zeichenfolge AdventureWorks2022'SELECT @@VERSION --übergeben wird, wird im SQL Server -Agent-Auftragsschritt der folgende Befehl ausgeführt:
PRINT N'Current database name is AdventureWorks2022''SELECT @@VERSION --' ;
In diesem Fall wird die eingefügte Anweisung SELECT @@VERSION nicht ausgeführt. Stattdessen wird durch das überzählige einfache Anführungszeichen der Server veranlasst, die eingefügte Anweisung als Zeichenfolge zu analysieren. Wenn die Zeichenfolge, durch die das Token ersetzt werden soll, keine einfachen Anführungszeichen enthält, werden keine Zeichen umgangen, und der Auftragsschritt mit dem Token wird wie beabsichtigt ausgeführt.
Verwenden Sie zum Debuggen der Tokenverwendung in Auftragsschritten Druckanweisungen, wie z. B. PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' , und speichern Sie die Auftragsschrittausgabe in einer Datei oder Tabelle. Auf der Seite Erweitert des Dialogfelds Auftragsschritt-Eigenschaften können Sie eine Datei oder Tabelle für die Auftragsschrittausgabe angeben.
SQL Server-Agent-Token und -Makros
In der folgenden Tabelle sind die vom SQL Server -Agent unterstützten Token und Makros aufgelistet und beschrieben.
SQL Server-Agent-Token
| Token | BESCHREIBUNG |
|---|---|
| (A-DBN) | Datenbankname. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert des Datenbanknamens dieses Token im Auftragsschritt automatisch. |
| (A-SVR) | Servername. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert des Servernamens dieses Token im Auftragsschritt automatisch. |
| (A-ERR) | Fehlernummer. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert der Fehlernummer dieses Token im Auftragsschritt automatisch. |
| (A-SEV) | Fehlerschweregrad. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert des Fehlerschweregrads dieses Token im Auftragsschritt automatisch. |
| (A-MSG) | Meldungstext. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert des Meldungstexts dieses Token im Auftragsschritt automatisch. |
| (JOBNAME) | Der Name des Auftrags. Dieses Token ist nur in SQL Server 2016 und höher verfügbar. |
| (STEPNAME) | Der Name des Schritts. Dieses Token ist nur in SQL Server 2016 und höher verfügbar. |
| (DATE) | Das aktuelle Datum (im Format YYYYMMDD). |
| (INST) | Der Instanzname. Für eine Standardinstanz erhält dieses Token den Standardinstanznamen: MSSQLSERVER. |
| (JOBID) | Auftrags-ID. |
| (MACH) | Name des Computers |
| (MSSA) | Name des Master-SQLServerAgent-Diensts. |
| (OSCMD) | Das Präfix des Programms, das zur Ausführung der CmdExec -Auftragsschritte verwendet wird. |
| (SQLDIR) | Verzeichnis, in dem SQL Server installiert ist. Der Standardwert lautet "C:\Programme\Microsoft SQL Server\MSSQL". |
| (SQLLOGDIR) | Ersetzungstoken für den Pfad des SQL Server-Fehlerprotokollordners, beispielsweise $(ESCAPE_SQUOTE(SQLLOGDIR)). Dieses Token ist nur in SQL Server 2014 und höher verfügbar. |
| (STEPCT) | Die Angabe, wie oft dieser Schritt ausgeführt wurde (ohne Abbrüche). Mit diesem Token kann der Schrittbefehl den Abbruch einer aus mehreren Schritten bestehenden Schleife erzwingen. |
| (STEPID) | Schritt-ID. |
| (SRVR) | Name des Computers, auf dem SQL Serverausgeführt wird. Wenn es sich bei der SQL Server -Instanz um eine benannte Instanz handelt, ist auch der Name der Instanz angegeben. |
| (TIME) | Die aktuelle Zeit (im Format HHMMSS). |
| (STRTTM) | Uhrzeit (im Format HHMMSS), zu der die Ausführung des Auftrags begonnen hat. |
| (STRTDT) | Datum (im Format YYYYMMDD), an dem die Ausführung des Auftrags begonnen hat. |
| (WMI(Eigenschaft)) | Bei Aufträgen, die als Antwort auf WMI-Warnungen ausgeführt werden, ist dies der Wert der durch propertyangegebenen Eigenschaft. In $(WMI(DatabaseName)) ist beispielsweise der Wert der DatabaseName -Eigenschaft für das WMI-Ereignis angegeben, das die Ausführung der Warnung verursacht hat. |
SQL Server-Agent-Escapemakros
| Escapemakros | BESCHREIBUNG |
|---|---|
| $(ESCAPE_SQUOTE(token_name)) | Umgeht einfache Anführungszeichen (') in der Token-Ersetzungszeichenfolge. Ein einfaches Anführungszeichen wird durch zwei einfache Anführungszeichen ersetzt. |
| $(ESCAPE_DQUOTE(token_name)) | Umgeht doppelte Anführungszeichen (") in der Token-Ersetzungszeichenfolge. Ein doppeltes Anführungszeichen wird durch zwei doppelte Anführungszeichen ersetzt. |
| $(ESCAPE_RBRACKET(token_name)) | Umgeht rechte eckige Klammern (]) in der Token-Ersetzungszeichenfolge. Ersetzt jede rechte eckige Klammer durch zwei rechte eckige Klammern. |
| $(ESCAPE_NONE(token_name)) | Ersetzt Token, ohne irgendein Zeichen in der Zeichenfolge zu umgehen. Dieses Makro wird zur Unterstützung der Abwärtskompatibilität in Umgebungen bereitgestellt, in denen Token-Ersetzungszeichenfolgen nur von vertrauenswürdigen Benutzern erwartet werden. Weitere Informationen finden Sie weiter unten im Abschnitt zum Aktualisieren von Auftragsschritten für die Verwendung von Makros. |
Aktualisieren von Auftragsschritten für die Verwendung von Makros
Die folgende Tabelle beschreibt, wie die symbolische Ersetzung von SQL Server -Agent behandelt wird. Um die Tokenersetzung durch Warnungen ein- oder auszuschalten, klicken Sie im Objekt-Explorer mit der rechten Maustaste auf SQL Server-Agent , wählen Sie Eigenschaften, und aktivieren bzw. deaktivieren Sie anschließend auf der Seite Warnungssystem das Kontrollkästchen Token für alle Auftragsantworten auf Warnungen ersetzen .
| Tokensyntax | Tokenersetzung durch Warnungen aktiviert | Tokenersetzung durch Warnungen deaktiviert |
|---|---|---|
| ESCAPE-Makro verwendet | Alle Token in Auftragsschritten werden erfolgreich ersetzt. | Durch Warnungen aktivierte Token werden nicht ersetzt. Dabei handelt es sich um folgende Token: A-DBN, A-SVR, A-ERR, A-SEV, A-MSGund WMI(Eigenschaft) . Andere, statische Token werden erfolgreich ersetzt. |
| Kein ESCAPE-Makro verwendet | Alle Auftragsschritte mit Token werden nicht ausgeführt. | Alle Auftragsschritte mit Token werden nicht ausgeführt. |
Beispiele für Updates der Tokensyntax
Im Folgenden finden Sie Beispiele für die Tokensyntax, um zu veranschaulichen, wie diese Befehle verwendet werden.
A. Verwenden von Token in nicht geschachtelten Zeichenfolgen
Im folgenden Beispiel wird gezeigt, wie Sie ein einfaches, nicht geschachteltes Skript mit dem entsprechenden Escapemakro aktualisieren. Vor dem Ausführen des Updateskripts verwendet das folgende Auftragsschrittskript ein Auftragsschritttoken, um den entsprechenden Datenbanknamen zu drucken:
PRINT N'Current database name is $(A-DBN)' ;
Nach dem Ausführen des Updateskripts wird vor dem ESCAPE_NONE -Token ein A-DBN -Makro eingefügt. Da die Druckzeichenfolge durch einfache Anführungszeichen begrenzt wird, müssen Sie den Auftragsschritt aktualisieren, indem Sie das ESCAPE_SQUOTE -Makro folgendermaßen einfügen:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
B. Verwenden von Token in geschachtelten Zeichenfolgen
In Auftragsschritten, in denen Token in geschachtelten Zeichenfolgen oder Anweisungen verwendet werden, sollten die geschachtelten Anweisungen als Einzelanweisungen neu geschrieben werden, bevor die entsprechenden Escapemakros eingefügt werden.
Betrachten Sie z. B. den folgenden Auftragsschritt, der das Token A-MSG verwendet und nicht mit einem Escapemakro aktualisiert wurde:
PRINT N'Print ''$(A-MSG)''' ;
Nach dem Ausführen des Updateskripts wird mit dem Token ein ESCAPE_NONE -Makro eingefügt. In diesem Fall müssten Sie das Skript jedoch ohne Verwenden von Schachtelungen folgendermaßen neu schreiben und das ESCAPE_SQUOTE -Makro einfügen, damit die in der Token-Ersetzungszeichenfolge möglicherweise übergebenen Begrenzungszeichen richtig umgangen werden:
DECLARE @msgString nvarchar(max);
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))';
SET @msgString = QUOTENAME(@msgString,'''');
PRINT N'Print ' + @msgString;
Hinweis
In diesem Beispiel wird mit der Funktion QUOTENAME das Anführungszeichen festgelegt.
C. Verwenden von Token mit dem ESCAPE_NONE-Makro
Das folgende Beispiel ist Teil eines Skripts, mit dem die Auftrags-ID (job_id) aus der sysjobs-Tabelle abgerufen wird und mithilfe des JOBID-Tokens die zuvor im Skript als binärer Datentyp deklarierte @JobID-Variable aufgefüllt wird.
Hinweis
Mit dem JOBID -Token wird das ESCAPE_NONE-Makro verwendet, da für binäre Datentypen keine Begrenzungszeichen erforderlich sind. In diesem Fall muss der Auftragsschritt nach Ausführen des Updateskripts nicht aktualisiert werden.
DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))
Dadurch wird der Wert aus dem JOBID-Token direkt @JobID zugewiesen, wodurch unnötige Datenbankabfragen und implizite Konvertierungen beseitigt werden, wobei die in Abschnitt C angesprochenen Bedenken behandelt werden.