• Artikel

sp_add_job (Transact-SQL)

Fügt einen neuen Auftrag hinzu, der vom SQLServerAgent-Dienst ausgeführt wird.

Themenlink (Symbol)Transact-SQL-Syntaxkonventionen

Syntax

sp_add_job [ @job_name = ] 'job_name'
     [ , [ @enabled = ] enabled ] 
     [ , [ @description = ] 'description' ] 
     [ , [ @start_step_id = ] step_id ] 
     [ , [ @category_name = ] 'category' ] 
     [ , [ @category_id = ] category_id ] 
     [ , [ @owner_login_name = ] 'login' ] 
     [ , [ @notify_level_eventlog = ] eventlog_level ] 
     [ , [ @notify_level_email = ] email_level ] 
     [ , [ @notify_level_netsend = ] netsend_level ] 
     [ , [ @notify_level_page = ] page_level ] 
     [ , [ @notify_email_operator_name = ] 'email_name' ] 
          [ , [ @notify_netsend_operator_name = ] 'netsend_name' ] 
     [ , [ @notify_page_operator_name = ] 'page_name' ] 
     [ , [ @delete_level = ] delete_level ] 
     [ , [ @job_id = ] job_id OUTPUT ]

Argumente

  • [ @job_name =] 'job_name'
    Der Name des Auftrags. Der Name muss eindeutig sein und darf kein Prozentzeichen (%) enthalten. job_name ist vom Datentyp nvarchar(128) und weist keinen Standardwert auf.

  • [ @enabled = ] enabled
    Bezeichnet den Status des hinzugefügten Auftrags. enabled ist ein Wert vom Datentyp tinyint. Der Standardwert ist 1 (aktiviert). Bei 0 ist der Auftrag nicht aktiviert und wird nicht wie geplant ausgeführt, er kann jedoch manuell ausgeführt werden.

  • [ @description =] 'description'
    Die Beschreibung des Auftrags. description ist vom Datentyp nvarchar(512) und hat den Standardwert NULL. Wenn description nicht angegeben wird, wird "Keine Beschreibung verfügbar" verwendet.

  • [ @start_step_id = ] step_id
    Die ID des ersten Schritts, der für den Auftrag ausgeführt werden soll. step_idist ein Wert vom Datentyp int. Der Standardwert ist 1.

  • [ @category_name = ] 'category'
    Die Kategorie des Auftrags. category hat den Datentyp sysname und den Standardwert NULL.

  • [ @category_id = ] category_id
    Ein sprachunabhängiger Mechanismus zum Angeben einer Auftragskategorie. category_idist ein Wert vom Datentyp int. Der Standardwert ist NULL.

  • [ @owner_login_name = ] 'login'
    Der Anmeldename, der der Besitzer des Auftrags ist. loginist ein Wert vom Datentyp sysname. Der Standardwert ist NULL und wird als aktueller Anmeldename interpretiert. Nur Mitglieder der festen Serverrolle sysadmin können den Wert für @owner_login_name festlegen oder ändern. Wenn Benutzer, die nicht Mitglieder der festen Serverrolle sysadmin sind, den Wert für @owner_login_name festlegen oder ändern, schlägt die Ausführung dieser gespeicherten Prozedur fehl, und es wird ein Fehler zurückgegeben.

  • [ @notify_level_eventlog = ] eventlog_level
    Ein Wert, der angibt, wann für diesen Auftrag ein Eintrag in das Microsoft Windows-Anwendungsprotokoll geschrieben werden soll. eventlog_levelist ein Wert vom Datentyp int. Die folgenden Werte sind möglich.

    Wert

    Beschreibung

    0

    Nie

    1

    Bei Erfolg

    2 (Standardwert)

    Bei Fehler

    3

    Immer

  • [ @notify_level_email = ] email_level
    Ein Wert, der angibt, wann eine E-Mail-Nachricht gesendet werden soll, wenn dieser Auftrag abgeschlossen ist. email_levelist ein Wert vom Datentyp int. Der Standardwert ist 0, was "nie" bedeutet. email_levelverwendet die gleichen Werte wie eventlog_level.

  • [ @notify_level_netsend = ] netsend_level
    Ein Wert, der angibt, wann eine Netzwerknachricht gesendet werden soll, wenn dieser Auftrag abgeschlossen ist. netsend_levelist ein Wert vom Datentyp int. Der Standardwert ist 0, was "nie" bedeutet. netsend_level verwendet die gleichen Werte wie eventlog_level.

  • [ @notify_level_page = ] page_level
    Ein Wert, der angibt, wann eine Seite gesendet werden soll, wenn dieser Auftrag abgeschlossen ist. page_levelist ein Wert vom Datentyp int. Der Standardwert ist 0, was "nie" bedeutet. page_levelverwendet die gleichen Werte wie eventlog_level.

  • [ @notify_email_operator_name = ] 'email_name'
    Der E-Mail-Name der Person, an die die E-Mail-Nachricht gesendet wird, wenn der Wert für email_level erreicht ist. email_name ist ein Wert vom Datentyp sysname. Der Standardwert ist NULL.

  • [ @notify_netsend_operator_name = ] 'netsend_name'
    Der Name des Operators, an den die Netzwerknachricht gesendet wird, wenn dieser Auftrag abgeschlossen ist. netsend_nameist ein Wert vom Datentyp sysname. Der Standardwert ist NULL.

  • [ @notify_page_operator_name = ] 'page_name'
    Der Name der Person, die mithilfe eines Pagers benachrichtigt werden soll, wenn dieser Auftrag abgeschlossen ist. page_nameist ein Wert vom Datentyp sysname. Der Standardwert ist NULL.

  • [ @delete_level = ] delete_level
    Ein Wert, der angibt, wann der Auftrag gelöscht werden soll. delete_valueist ein Wert vom Datentyp int. Der Standardwert ist 0, was "nie" bedeutet. delete_levelverwendet die gleichen Werte wie eventlog_level.

    HinweisHinweis

    Wenn delete_level den Wert 3 hat, wird der Auftrag nur einmal ausgeführt, unabhängig von für den Auftrag definierten Zeitplänen. Darüber hinaus wird, wenn sich ein Auftrag selbst löscht, auch der gesamte Verlauf für diesen Auftrag gelöscht.

  • [ @job_id = ] job_idOUTPUT
    Die Auftrags-ID, die dem Auftrag zugewiesen wird, wenn er erfolgreich erstellt wurde. job_idist eine Ausgabevariable vom Datentyp uniqueidentifier. Der Standardwert ist NULL.

Rückgabecodewerte

0 (Erfolg) oder 1 (Fehler)

Resultsets

Keine

Hinweise

@originating_server gehört ebenfalls zu sp_add_job, wird jedoch nicht unter den Argumenten aufgeführt. @originating_server ist für die interne Verwendung reserviert.

Nachdem Sie mit sp_add_job einen Auftrag hinzugefügt haben, können Sie mithilfe von sp_add_jobstep Schritte hinzufügen, mit denen die Aktivitäten für den Auftrag ausgeführt werden. Mithilfe von sp_add_jobschedule können Sie den Zeitplan erstellen, den der SQL Server-Agent-Dienst zum Ausführen des Auftrags verwendet. Verwenden Sie sp_add_jobserver, um die SQL Server-Instanz für die Auftragsausführung festzulegen, und sp_delete_jobserver, um den Auftrag von der SQL Server-Instanz zu entfernen.

Wenn der Auftrag auf einem oder mehreren Zielservern in einer Multiserverumgebung ausgeführt wird, verwenden Sie sp_apply_job_to_targets, um die Zielserver oder Zielservergruppen für den Auftrag festzulegen. Zum Entfernen von Aufträgen von Zielservern oder Zielservergruppen verwenden Sie sp_remove_job_from_targets.

Mit SQL Server Management Studio können Aufträge problemlos mithilfe einer grafischen Oberfläche verwaltet werden. Dies ist die empfohlene Vorgehensweise, um die Auftragsinfrastruktur zu erstellen und zu verwalten.

Berechtigungen

Zum Ausführen dieser gespeicherten Prozedur müssen Benutzer Mitglieder der festen Serverrolle sysadmin oder Mitglieder einer der folgenden festen SQL Server-Agent-Datenbankrollen sein, die sich in der msdb-Datenbank befinden:

  • SQLAgentUserRole

  • SQLAgentReaderRole

  • SQLAgentOperatorRole

Informationen zu den einzelnen Berechtigungen, die jeder dieser festen Datenbankrollen zugeordnet sind, finden Sie unter Feste Datenbankrollen des SQL Server-Agents.

Nur Mitglieder der festen Serverrolle sysadmin können den Wert für @owner_login_name festlegen oder ändern. Wenn Benutzer, die nicht Mitglieder der festen Serverrolle sysadmin sind, den Wert für @owner_login_name festlegen oder ändern, schlägt die Ausführung dieser gespeicherten Prozedur fehl, und es wird ein Fehler zurückgegeben.

Beispiele

A. Hinzufügen eines Auftrags

Im folgenden Beispiel wird ein neuer Auftrag mit dem Namen NightlyBackups hinzugefügt.

USE msdb ;
GO

EXEC dbo.sp_add_job
    @job_name = N'NightlyBackups' ;
GO

B. Hinzufügen eines Auftrags mit Pager-, E-Mail- und NET SEND-Informationen

Im folgenden Beispiel wird der Auftrag Ad hoc Sales Data Backup erstellt, mit dem François Ajenstat (per Pager, E-Mail oder Netzwerk-Popupnachricht) benachrichtigt wird, falls der Auftrag einen Fehler erzeugt. Wenn der Auftrag erfolgreich ausgeführt wurde, wird er gelöscht.

HinweisHinweis

Im Rahmen dieses Beispiels wird davon ausgegangen, dass der Operator François Ajenstat und der Anmeldename françoisa bereits vorhanden sind.

 
USE msdb ;
GO

EXEC dbo.sp_add_job
    @job_name = N'Ad hoc Sales Data Backup', 
    @enabled = 1,
    @description = N'Ad hoc backup of sales data',
    @owner_login_name = N'françoisa',
    @notify_level_eventlog = 2,
    @notify_level_email = 2,
    @notify_level_netsend = 2,
    @notify_level_page = 2,
    @notify_email_operator_name = N'François Ajenstat',
    @notify_netsend_operator_name = N'François Ajenstat', 
    @notify_page_operator_name = N'François Ajenstat',
    @delete_level = 1 ;
GO