sp_add_jobstep (Transact-SQL)

Artikel
06/06/2023

Gilt für:SQL Server Azure SQL Managed Instance

Fügt einem SQL Server-Agent Auftrag einen Schritt (Vorgang) hinzu.

Wichtig

Auf Azure SQL Managed Instance werden die meisten, aber nicht alle SQL Server-Agent Auftragstypen unterstützt. Details dazu finden Sie unter T-SQL-Unterschiede zwischen Azure SQL Managed Instance und SQL Server.

Syntax

sp_add_jobstep
    [ @job_id = ] job_id
        | [ @job_name = ] 'job_name'
    [ , [ @step_id = ] step_id ]
    { , [ @step_name = ] 'step_name' }
    [ , [ @subsystem = ] N'subsystem' ]
    [ , [ @command = ] N'command' ]
    [ , [ @additional_parameters = ] N'parameters' ]
    [ , [ @cmdexec_success_code = ] code ]
    [ , [ @on_success_action = ] success_action ]
    [ , [ @on_success_step_id = ] success_step_id ]
    [ , [ @on_fail_action = ] fail_action ]
    [ , [ @on_fail_step_id = ] fail_step_id ]
    [ , [ @server = ] N'server' ]
    [ , [ @database_name = ] 'database' ]
    [ , [ @database_user_name = ] 'user' ]
    [ , [ @retry_attempts = ] retry_attempts ]
    [ , [ @retry_interval = ] retry_interval ]
    [ , [ @os_run_priority = ] run_priority ]
    [ , [ @output_file_name = ] N'file_name' ]
    [ , [ @flags = ] flags ]
    [ , { [ @proxy_id = ] proxy_id
        | [ @proxy_name = ] 'proxy_name' } ]
[ ; ]

Argumente

[ @job_id = ] job_id

Die ID des Auftrags, dem der Schritt hinzugefügt werden soll. @job_id ist uniqueidentifier mit dem Standardwert NULL.

Es müssen entweder @job_id oder @job_name angegeben werden, aber beide können nicht angegeben werden.

[ @job_name = ] 'job_name'

Der Name des Auftrags, dem der Schritt hinzugefügt werden soll. @job_name ist sysname mit dem Standardwert NULL.

Es müssen entweder @job_id oder @job_name angegeben werden, aber beide können nicht angegeben werden.

[ @step_id = ] step_id

Die Sequenz-ID des Auftragsschritts. Schrittidentifikationsnummern beginnen bei 1 und inkrementieren ohne Lücken. Wenn ein Schritt in eine vorhandene Sequenz eingefügt wird, werden die Sequenznummern automatisch angepasst. Ein Wert wird angegeben, wenn @step_id nicht angegeben ist. @step_id ist int mit dem Standardwert NULL.

[ @step_name = ] 'step_name'

Der Name des Schritts. @step_name ist sysname ohne Standardwert.

[ @subsystem = ] N'Subsystem'

Das Subsystem, das vom SQL Server-Agent-Dienst verwendet wird, um @command auszuführen. @subsystem ist nvarchar(40) und kann einer dieser Werte sein.

Wert	BESCHREIBUNG
`'ActiveScripting'`	Active Script Wichtig: Dieses Feature wird in einer zukünftigen Version von Microsoft SQL Server entfernt. Nutzen Sie diese Funktionen bei Neuentwicklungen nicht mehr, und planen Sie die Änderung von Anwendungen, die diese Funktion zurzeit verwenden.
`'CmdExec'`	Betriebssystembefehl oder ausführbares Programm
`'Distribution'`	Auftrag des Replikationsverteilungs-Agents
`'Snapshot'`	Auftrag des Replikationsmomentaufnahme-Agents
`'LogReader'`	Auftrag des Replikationsprotokolllese-Agents
`'Merge'`	Auftrag des Replikationsmerge-Agents
`'QueueReader'`	Warteschlangenlese-Agent-Auftrag der Replikation
`'ANALYSISQUERY'`	Analysis Services-Abfrage (MDX, DMX)
`'ANALYSISCOMMAND'`	Analysis Services-Befehl (XMLA)
`'SSIS'`	Ausführung des Integration Services-Pakets
`'PowerShell'`	PowerShell-Skript
`'TSQL'` (Standard)	Transact-SQL-Anweisung

[ @command = ] N'command'

Die Befehle, die vom SQL Server-Agent-Dienst über @subsystem ausgeführt werden sollen. @command ist nvarchar(max) mit dem Standardwert NULL. SQL Server-Agent bietet Tokenersetzung, die Ihnen die gleiche Flexibilität bietet, die Variablen beim Schreiben von Softwareprogrammen bieten.

Ein Escapemakro muss alle Token begleiten, die in Auftragsschritten verwendet werden, andernfalls schlagen diese Auftragsschritte fehl. Darüber hinaus müssen Sie Tokennamen nun in runde Klammern einschließen und ein Dollarzeichen ($) an den Anfang der Tokensyntax setzen. Beispiel: $(ESCAPE_Makroname(DATE)).

Weitere Informationen zu diesen Token und zum Aktualisieren Ihrer Auftragsschritte zur Verwendung der neuen Tokensyntax finden Sie unter Verwenden von Token in Auftragsschritten.

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. Diese Token sind : A-DBN, A-SVR, A-ERR, A-SEV, A-MSGund WMI(<property>). In dieser Version wird 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.

[ @additional_parameters = ] N'parameters'

Nur für Informationszwecke identifiziert. Wird nicht unterstützt. Zukünftige Kompatibilität wird nicht sichergestellt. @additional_parameters ist ntext mit dem Standardwert NULL.

[ @cmdexec_success_code = ] Code

Der von einem CmdExec Subsystembefehl zurückgegebene Wert, um anzugeben, dass @command erfolgreich ausgeführt wurde. @cmdexec_success_code ist int mit dem Standardwert 0.

[ @on_success_action = ] success_action

Die Aktion, die ausgeführt werden soll, wenn der Schritt erfolgreich ausgeführt wird. @on_success_action ist tinyint und kann einer dieser Werte sein.

Wert	Beschreibung (Aktion)
`1` (Standardwert)	Erfolgreich beenden
`2`	Beenden mit Fehler
`3`	Zum nächsten Schritt wechseln
`4`	Wechseln Sie zu Schritt @on_success_step_id

[ @on_success_step_id = ] success_step_id

Die ID des Schritts in diesem Auftrag, der ausgeführt werden soll, wenn der Schritt erfolgreich ist und @on_success_action ist 4. @on_success_step_id ist int mit dem Standardwert 0.

[ @on_fail_action = ] fail_action

Die Aktion, die ausgeführt werden soll, wenn der Schritt fehlschlägt. @on_fail_action ist tinyint und kann einer dieser Werte sein.

Wert	Beschreibung (Aktion)
`1`	Erfolgreich beenden
`2` (Standardwert)	Beenden mit Fehler
`3`	Zum nächsten Schritt wechseln
`4`	Wechseln Sie zu Schritt on_fail_step_id

[ @on_fail_step_id = ] fail_step_id

Die ID des Schritts in diesem Auftrag, der ausgeführt werden soll, wenn der Schritt fehlschlägt und @on_fail_action ist 4. @on_fail_step_id ist int mit dem Standardwert 0.

[ @server = ] N'server'

Nur für Informationszwecke identifiziert. Wird nicht unterstützt. Zukünftige Kompatibilität wird nicht sichergestellt. @server ist nvarchar(30) mit dem Standardwert NULL.

[ @database_name = ] 'Database'

Der Name der Datenbank, in der ein Transact-SQL-Schritt ausgeführt werden soll. @database_name ist sysname, wobei der Standardwert NULL ist. In diesem Fall wird die master Datenbank verwendet. Namen, die in Klammern ([ ]) eingeschlossen sind, sind nicht zulässig. Bei einem ActiveX-Auftragsschritt ist der @database_name der Name der Skriptsprache, die der Schritt verwendet.

[ @database_user_name = ] 'Benutzer'

Der Name des Benutzerkontos, das beim Ausführen eines Transact-SQL-Schritts verwendet werden soll. @database_user_name ist sysname mit dem Standardwert NULL. Wenn @database_user_name NULL ist, wird der Schritt im Benutzerkontext des Auftragsbesitzers auf @database_name ausgeführt. SQL Server-Agent enthält diesen Parameter nur, wenn der Auftragsbesitzer ein SQL Server sysadmin ist. Wenn ja, wird der angegebene Transact-SQL-Schritt im Kontext des angegebenen SQL Server Benutzernamens ausgeführt. Wenn der Auftragsbesitzer kein SQL Server Sysadmin ist, wird der Transact-SQL-Schritt immer im Kontext des Anmeldenamens ausgeführt, der diesen Auftrag besitzt, und der parameter @database_user_name wird ignoriert.

[ @retry_attempts = ] retry_attempts

Die Anzahl der Wiederholungsversuche für den Fall, dass dieser Schritt fehlschlägt. @retry_attempts ist "int", wobei der Standardwert von 0ist. Dies bedeutet, dass es keine Wiederholungsversuche gibt.

[ @retry_interval = ] retry_interval

Der Zeitraum in Minuten zwischen zwei Wiederholungsversuchen. @retry_interval ist int mit dem Standardwert , 0der ein 0Minutenintervall angibt.

[ @os_run_priority = ] run_priority

Reserviert.

[ @output_file_name = ] N'file_name'

Der Name der Datei, in der die Ausgabe dieses Schritts gespeichert wird. @output_file_name ist nvarchar(200) mit dem Standardwert NULL. @output_file_name können eines oder mehrere der unter @command aufgeführten Token enthalten. Dieser Parameter ist nur für Befehle gültig, die in den Subsystemen Transact-SQL, CmdExec, PowerShellIntegration Services oder Analysis Services ausgeführt werden.

[ @flags = ] Flags

Eine Option, die das Verhalten steuert. @flags ist int und kann einer dieser Werte sein.

Wert	Beschreibung
`0` (Standardwert)	Ausgabedatei überschreiben
`2`	An Ausgabedatei anfügen
`4`	Ausgabe des Transact-SQL-Auftragsschrittes in Schrittverlauf schreiben
`8`	Protokoll in Tabelle schreiben (vorhandenen Verlauf überschreiben)
`16`	Protokoll in Tabelle schreiben (an vorhandenen Verlauf anfügen)
`32`	Schreiben der gesamten Ausgabe in den Auftragsverlauf
`64`	Erstellen eines Windows-Ereignisses, das als Signal für den Abbruch des `cmd` Auftragsschritts verwendet werden soll

[ @proxy_id = ] proxy_id

Die ID des Proxys, als der der Auftragsschritt ausgeführt wird. @proxy_id ist der Typ int mit dem Standardwert NULL. Wenn kein @proxy_id angegeben ist, kein @proxy_name angegeben und kein @database_user_name angegeben ist, wird der Auftragsschritt als Dienstkonto für SQL Server-Agent ausgeführt.

[ @proxy_name = ] 'proxy_name'

Der Name des Proxys, als der der Auftragsschritt ausgeführt wird. @proxy_name ist der Typ sysname mit dem Standardwert NULL. Wenn kein @proxy_id angegeben ist, kein @proxy_name angegeben und kein @database_user_name angegeben ist, wird der Auftragsschritt als Dienstkonto für SQL Server-Agent ausgeführt.

Rückgabecodewerte

0 (Erfolg) oder 1 (Fehler).

Resultsets

Keine.

Bemerkungen

sp_add_jobstep muss aus der msdb Datenbank ausgeführt werden.

SQL Server Management Studio bietet eine einfache grafische Möglichkeit zum Verwalten von Aufträgen. Es handelt sich hierbei um die empfohlene Art und Weise zum Erstellen und Verwalten der Auftragsinfrastruktur.

Standardmäßig wird ein Auftragsschritt als Dienstkonto für SQL Server-Agent ausgeführt, es sei denn, es wird ein anderer Proxy angegeben. Eine Anforderung dieses Kontos ist, ein Mitglied der festen Sicherheitsrolle sysadmin zu sein.

Ein Proxy kann durch @proxy_name oder @proxy_id identifiziert werden.

Berechtigungen

Diese gespeicherte Prozedur gehört der rolle db_owner . Sie können jedem Benutzer EXECUTE-Berechtigungen erteilen, aber diese Berechtigungen können während eines SQL Server-Upgrades überschrieben werden.

Anderen Benutzern muss eine der folgenden SQL Server-Agent festen Datenbankrollen in der msdb Datenbank gewährt werden:

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

Weitere Informationen zu den Berechtigungen dieser Rollen finden Sie unter Feste Datenbankrollen des SQL Server-Agents.

Der Ersteller des Auftragsschritts muss Zugriff auf den für den Auftragsschritt verwendeten Proxy haben. Mitglieder der festen Serverrolle sysadmin haben Zugriff auf alle Proxys. Anderen Benutzern muss der Zugriff auf einen Proxy explizit erteilt werden.

Beispiele

Im folgenden Beispiel wird ein Auftragsschritt erstellt, der für die Sales-Datenbank den Schreibschutz aktiviert. Darüber hinaus gibt dieses Beispiel fünf Wiederholungsversuche an, wobei jeder Wiederholungsversuch nach einer 5-minütigen Wartezeit erfolgen soll.

Hinweis

In diesem Beispiel wird davon ausgegangen, dass der Weekly Sales Data Backup Auftrag bereits vorhanden ist.

USE msdb;
GO
EXEC sp_add_jobstep
    @job_name = N'Weekly Sales Data Backup',
    @step_name = N'Set database to read only',
    @subsystem = N'TSQL',
    @command = N'ALTER DATABASE SALES SET READ_ONLY',
    @retry_attempts = 5,
    @retry_interval = 5;
GO