sp_add_jobstep (Transact-SQL)

Artikel
12/22/2023

Gilt für:SQL Server Azure SQL Managed Instance

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

Wichtig

In Azure SQL verwaltete Instanz 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 = ] N'job_name' ]
    [ , [ @step_id = ] step_id ]
    , [ @step_name = ] N'step_name'
    [ , [ @subsystem = ] N'subsystem' ]
    [ , [ @command = ] N'command' ]
    [ , [ @additional_parameters = ] N'additional_parameters' ]
    [ , [ @cmdexec_success_code = ] cmdexec_success_code ]
    [ , [ @on_success_action = ] on_success_action ]
    [ , [ @on_success_step_id = ] on_success_step_id ]
    [ , [ @on_fail_action = ] on_fail_action ]
    [ , [ @on_fail_step_id = ] on_fail_step_id ]
    [ , [ @server = ] N'server' ]
    [ , [ @database_name = ] N'database_name' ]
    [ , [ @database_user_name = ] N'database_user_name' ]
    [ , [ @retry_attempts = ] retry_attempts ]
    [ , [ @retry_interval = ] retry_interval ]
    [ , [ @os_run_priority = ] os_run_priority ]
    [ , [ @output_file_name = ] N'output_file_name' ]
    [ , [ @flags = ] flags ]
    [ , [ @proxy_id = ] proxy_id ]
    [ , [ @proxy_name = ] N'proxy_name' ]
    [ , [ @step_uid = ] 'step_uid' OUTPUT ]
[ ; ]

Argumente

[ @job_id = ] 'job_id'

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

Entweder @job_id oder @job_name müssen angegeben werden, beide können jedoch nicht angegeben werden.

[ @job_name = ] N'job_name'

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

Entweder @job_id oder @job_name müssen angegeben werden, beide können jedoch nicht angegeben werden.

[ @step_id = ] step_id

Die Sequenz-ID des Auftragsschritts. @step_id ist int mit einem Standardwert von NULL. Schrittidentifikationsnummern beginnen bei 1 und erhöhen sie ohne Lücken. Wenn ein Schritt in eine vorhandene Sequenz eingefügt wird, werden die Sequenznummern automatisch angepasst. Wenn @step_id nicht angegeben ist, wird ein Wert bereitgestellt.

[ @step_name = ] N'step_name'

Der Name des Schritts. @step_name ist "sysname" ohne Standard.

[ @subsystem = ] N'Subsystem'

Das Subsystem, das vom SQL Server-Agent Dienst zum Ausführen @command verwendet wird. @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 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, UNIVERSE)
`ANALYSISCOMMAND`	Analysis Services-Befehl (XMLA)
`SSIS`	Ausführung des Integration Services-Pakets
`PowerShell`	PowerShell Script
`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 einem Standardwert von NULL. SQL Server-Agent bietet tokenersetzung, was Ihnen die gleiche Flexibilität bietet, die Variablen beim Schreiben von Softwareprogrammen bereitstellen.

Ein Escapemakro muss alle token begleiten, die in Auftragsschritten verwendet werden, oder 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_<macro name>(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 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.

[ @additional_parameters = ] N'additional_parameters'

Nur für Informationszwecke identifiziert. Wird nicht unterstützt. Zukünftige Kompatibilität wird nicht sichergestellt.

[ @cmdexec_success_code = ] cmdexec_success_code

Der von einem CmdExec Subsystembefehl zurückgegebene Wert, der angibt, dass @command erfolgreich ausgeführt wurden. @cmdexec_success_code ist int, mit einem Standardwert von 0.

[ @on_success_action = ] on_success_action

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

Wert	Beschreibung (Aktion)
`1` (Standard)	Beenden mit Erfolg
`2`	Beenden mit Fehler
`3`	Zum nächsten Schritt wechseln
`4`	Wechseln sie zu Schritt @on_success_step_id

[ @on_success_step_id = ] on_success_step_id

Die ID des Auszuführenden Schritts in diesem Auftrag, wenn der Schritt erfolgreich ist und @on_success_action ist 4. @on_success_step_id ist int mit einem Standardwert von 0.

[ @on_fail_action = ] on_fail_action

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

Wert	Beschreibung (Aktion)
`1`	Beenden mit Erfolg
`2` (Standard)	Beenden mit Fehler
`3`	Zum nächsten Schritt wechseln
`4`	Wechseln sie zu Schritt @on_fail_step_id

[ @on_fail_step_id = ] on_fail_step_id

Die ID des Schritts in diesem Auftrag auszuführen, wenn der Schritt fehlschlägt und @on_fail_action ist 4. @on_fail_step_id ist int mit einem Standardwert von 0.

[ @server = ] N'server'

Nur für Informationszwecke identifiziert. Wird nicht unterstützt. Zukünftige Kompatibilität wird nicht sichergestellt.

[ @database_name = ] N'database_name'

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

[ @database_user_name = ] N'database_user_name'

Der Name des Benutzerkontos, das beim Ausführen eines Transact-SQL-Schritts verwendet werden soll. @database_user_name ist "sysname" mit der Standardeinstellung "NULL. Wenn @database_user_name ist NULL, wird der Schritt im Benutzerkontext des Auftragsbesitzers für @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 der Anmeldung ausgeführt, die 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, mit einem Standardwert von 0, der keine Wiederholungsversuche angibt.

[ @retry_interval = ] retry_interval

Der Zeitraum in Minuten zwischen zwei Wiederholungsversuchen. @retry_interval ist int mit einem Standardwert von 0, der ein 0-Minute-Intervall angibt.

[ @os_run_priority = ] os_run_priority

Nur für Informationszwecke identifiziert. Wird nicht unterstützt. Zukünftige Kompatibilität wird nicht sichergestellt.

[ @output_file_name = ] N'output_file_name'

Der Name der Datei, in der die Ausgabe dieses Schritts gespeichert wird. @output_file_name ist nvarchar(200), wobei die Standardeinstellung istNULL. @output_file_name können mindestens ein token enthalten, das unter @command aufgeführt ist. Dieser Parameter ist nur für Befehle gültig, die auf 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 `cmd` Auftragsschritt zum Abbrechen verwendet werden soll

[ @proxy_id = ] proxy_id

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

[ @proxy_name = ] N'proxy_name'

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

[ @step_uid = ] 'step_uid' OUTPUT

@step_uid ist ein OUTPUT-Parameter vom Typ uniqueidentifier.

Rückgabecodewerte

0 (erfolgreich) oder 1 Fehler.

Resultset

Keine.

Hinweise

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, ein anderer Proxy ist angegeben. Eine Anforderung dieses Kontos ist ein Mitglied der festen Sicherheitsrolle "sysadmin ".

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

Diese gespeicherte Prozedur teilt den Namen sp_add_jobstep mit einem ähnlichen Objekt für den Azure Elastic Jobs-Dienst für Azure SQL-Datenbank. Informationen zur Version der elastischen Aufträge finden Sie unter jobs.sp_add_jobstep (Azure Elastic Jobs) (Transact-SQL).

Berechtigungen

Diese gespeicherte Prozedur gehört der db_owner Rolle. Sie können berechtigungen für jeden Benutzer erteilen EXECUTE , diese Berechtigungen können jedoch während eines SQL Server-Upgrades außer Kraft gesetzt 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 Wartezeit von 5 Minuten erfolgt.

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

sp_add_jobstep (Transact-SQL)

Syntax

Argumente

[ @job_id = ] 'job_id'

[ @job_name = ] N'job_name'

[ @step_id = ] step_id

[ @step_name = ] N'step_name'

[ @subsystem = ] N'Subsystem'

[ @command = ] N'command'

[ @additional_parameters = ] N'additional_parameters'

[ @cmdexec_success_code = ] cmdexec_success_code

[ @on_success_action = ] on_success_action

[ @on_success_step_id = ] on_success_step_id

[ @on_fail_action = ] on_fail_action

[ @on_fail_step_id = ] on_fail_step_id

[ @server = ] N'server'

[ @database_name = ] N'database_name'

[ @database_user_name = ] N'database_user_name'

[ @retry_attempts = ] retry_attempts

[ @retry_interval = ] retry_interval

[ @os_run_priority = ] os_run_priority

[ @output_file_name = ] N'output_file_name'

[ @flags = ] Flags

[ @proxy_id = ] proxy_id

[ @proxy_name = ] N'proxy_name'

[ @step_uid = ] 'step_uid' OUTPUT

Rückgabecodewerte

Resultset

Hinweise

Berechtigungen

Beispiele

Feedback

Feedback

Zusätzliche Ressourcen

sp_add_jobstep (Transact-SQL)

Syntax

Argumente

[ @job_id = ] 'job_id'

[ @job_name = ] N'job_name'

[ @step_id = ] step_id

[ @step_name = ] N'step_name'

[ @subsystem = ] N'Subsystem'

[ @command = ] N'command'

[ @additional_parameters = ] N'additional_parameters'

[ @cmdexec_success_code = ] cmdexec_success_code

[ @on_success_action = ] on_success_action

[ @on_success_step_id = ] on_success_step_id

[ @on_fail_action = ] on_fail_action

[ @on_fail_step_id = ] on_fail_step_id

[ @server = ] N'server'

[ @database_name = ] N'database_name'

[ @database_user_name = ] N'database_user_name'

[ @retry_attempts = ] retry_attempts

[ @retry_interval = ] retry_interval

[ @os_run_priority = ] os_run_priority

[ @output_file_name = ] N'output_file_name'

[ @flags = ] Flags

[ @proxy_id = ] proxy_id

[ @proxy_name = ] N'proxy_name'

[ @step_uid = ] 'step_uid' OUTPUT

Rückgabecodewerte

Resultset

Hinweise

Berechtigungen

Beispiele

Zugehöriger Inhalt

Feedback

Feedback

Zusätzliche Ressourcen