sp_add_jobstep (Transact-SQL)

  • Articolo

Si applica a:SQL ServerIstanza gestita di SQL di Azure

Aggiunge un passaggio (operazione) a un processo di SQL Server Agent.

Convenzioni di sintassi Transact-SQL

Importante

Nella maggior parte dei Istanza gestita di SQL di Azure, ma non tutti i tipi di processo di SQL Server Agent sono supportati. Per informazioni dettagliate, vedere Differenze T-SQL tra Istanza gestita di SQL di Azure e SQL Server.

Sintassi

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 ]
[ ; ]

Argomenti

[ @job_id = ] 'job_id'

Numero di identificazione del processo a cui aggiungere il passaggio. @job_id è uniqueidentifier, con un valore predefinito .NULL

È necessario specificare @job_id o @job_name , ma non è possibile specificare entrambi.

[ @job_name = ] N'job_name'

Nome del processo a cui aggiungere il passaggio. @job_name è sysname, con il valore predefinito NULL.

È necessario specificare @job_id o @job_name , ma non è possibile specificare entrambi.

[ @step_id = ] step_id

Numero di identificazione sequenziale per il passaggio del processo. @step_id è int, con il valore predefinito NULL. I numeri di identificazione dei passaggi iniziano in corrispondenza 1 e aumentano senza lacune. Se viene inserito un passaggio nella sequenza esistente, i numeri di sequenza vengono automaticamente adeguati. Se non viene specificato @step_id, viene specificato un valore.

[ @step_name = ] N'step_name'

Nome del passaggio. @step_name è sysname, senza impostazione predefinita.

[ @subsystem = ] N'subsystem'

Sottosistema usato dal servizio SQL Server Agent per eseguire @command. @subsystem è nvarchar(40)e può essere uno di questi valori.

Valore Descrizione
ActiveScripting Script ActiveX

Importante: questa funzionalità verrà rimossa in una versione futura di SQL Server. Evitare di usare questa funzionalità in un nuovo progetto di sviluppo e prevedere interventi di modifica nelle applicazioni in cui è attualmente implementata.
CmdExec Comando del sistema operativo o programma eseguibile
Distribution Processo di Agente distribuzione repliche
Snapshot Processo di Agente snapshot repliche
LogReader Processo di Agente lettura log repliche
Merge Processo di Agente merge repliche
QueueReader Processo di Agente di lettura coda repliche
ANALYSISQUERY Analysis Services query (MDX, DMX)
ANALYSISCOMMAND Comando Analysis Services (XMLA)
SSIS Esecuzione di pacchetti di Integration Services
PowerShell Script di PowerShell
TSQL (predefinito) Istruzione Transact-SQL

[ @command = ] N'command'

Comandi da eseguire dal servizio SQL Server Agent tramite @subsystem. @command è nvarchar(max), con un valore predefinito .NULL SQL Server Agent offre la sostituzione dei token, che offre la stessa flessibilità offerta dalle variabili durante la scrittura di programmi software.

Una macro di escape deve accompagnare tutti i token usati nei passaggi del processo oppure i passaggi di processo hanno esito negativo. È ora necessario inoltre racchiudere tra parentesi i nomi dei token e inserire il simbolo di dollaro ($) all'inizio della sintassi del token, Ad esempio: $(ESCAPE_<macro name>(DATE)).

Per altre informazioni su questi token e sull'aggiornamento dei passaggi del processo per usare la nuova sintassi del token, vedere Use Tokens in Job Steps.For more information about these tokens and updating your job steps to use the new token syntax, see Use Tokens in Job Steps.For more information about these tokens and updating your job steps to use the new token syntax, see Use Tokens in Job

Qualsiasi utente di Windows con autorizzazioni di scrittura per il registro eventi di Windows può accedere ai passaggi di processo attivati dagli avvisi di SQL Server Agent o di WMI. Per evitare rischi per la sicurezza, i token di SQL Server Agent che possono essere usati in processi attivati dagli avvisi sono disabilitati per impostazione predefinita. Questi token sono: A-DBN, A-SVR, A-ERRA-SEV, , A-MSGe WMI(<property>). In questa versione, l'uso dei token viene esteso a tutti gli avvisi.

Se è necessario usare questi token, verificare innanzitutto che solo i membri di gruppi di sicurezza di Windows attendibili, ad esempio il gruppo Administrators, dispongano delle autorizzazioni di scrittura per il registro eventi del computer in cui è installato SQL Server. A questo punto, fare clic con il pulsante destro del mouse su SQL Server Agent in Esplora oggetti, scegliere Proprietàe nella pagina Sistema avvisi selezionare Sostituisci token per tutte le risposte del processo ad avvisi per abilitare questi token.

[ @additional_parameters = ] N'additional_parameters'

Identificato solo a scopo informativo. Non supportato. Non è garantita la compatibilità con le versioni future.

[ @cmdexec_success_code = ] cmdexec_success_code

Valore restituito da un CmdExec comando del sottosistema per indicare che @command eseguito correttamente. @cmdexec_success_code è int, con il valore predefinito 0.

[ @on_success_action = ] on_success_action

Azione da eseguire se il passaggio ha esito positivo. @on_success_action è tinyint e può essere uno di questi valori.

Valore Descrizione (azione)
1 (predefinito) Uscita in caso di esito positivo
2 Uscita in caso di esito negativo
3 Esecuzione del passaggio successivo
4 Andare al passaggio @on_success_step_id

[ @on_success_step_id = ] on_success_step_id

ID del passaggio di questo processo da eseguire se il passaggio ha esito positivo e @on_success_action è 4. @on_success_step_id è int, con il valore predefinito .0

[ @on_fail_action = ] on_fail_action

Azione da eseguire se il passaggio non viene completato correttamente. @on_fail_action è tinyint e può essere uno di questi valori.

Valore Descrizione (azione)
1 Uscita in caso di esito positivo
2 (predefinito) Uscita in caso di esito negativo
3 Esecuzione del passaggio successivo
4 Andare al passaggio @on_fail_step_id

[ @on_fail_step_id = ] on_fail_step_id

ID del passaggio da eseguire se il passaggio ha esito negativo e @on_fail_action è 4. @on_fail_step_id è int, con il valore predefinito 0.

[ @server = ] N'server'

Identificato solo a scopo informativo. Non supportato. Non è garantita la compatibilità con le versioni future.

[ @database_name = ] N'database_name'

Nome del database in cui eseguire un passaggio Transact-SQL. @database_name è sysname, con un valore predefinito , NULLnel qual caso viene usato il master database. I nomi racchiusi tra parentesi quadre ([]) non sono consentiti. Per un passaggio del processo ActiveX, il @database_name è il nome del linguaggio di scripting usato dal passaggio.

[ @database_user_name = ] N'database_user_name'

Nome dell'account utente da usare durante l'esecuzione di un passaggio Transact-SQL. @database_user_name è sysname, con un valore predefinito .NULL Quando @database_user_name è NULL, il passaggio viene eseguito nel contesto utente del proprietario del processo in @database_name. SQL Server Agent include questo parametro solo se il proprietario del processo è un sysadmin di SQL Server. In tal caso, il passaggio Transact-SQL specificato viene eseguito nel contesto del nome utente di SQL Server specificato. Se il proprietario del processo non è un sysadmin di SQL Server, il passaggio Transact-SQL viene sempre eseguito nel contesto dell'account di accesso proprietario di questo processo e il parametro @database_user_name viene ignorato.

[ @retry_attempts = ] retry_attempts

Numero di tentativi da eseguire in caso di esecuzione errata del passaggio. @retry_attempts è int, con un valore predefinito 0, che indica che non viene eseguito alcun tentativo.

[ @retry_interval = ] retry_interval

Numero di minuti che devono trascorrere tra i tentativi. @retry_interval è int, con un valore predefinito 0, che indica un 0intervallo di minuti.

[ @os_run_priority = ] os_run_priority

Identificato solo a scopo informativo. Non supportato. Non è garantita la compatibilità con le versioni future.

[ @output_file_name = ] N'output_file_name'

Nome del file in cui salvare l'output del passaggio. @output_file_name è nvarchar(200), con il valore predefinito NULL. @output_file_name può includere uno o più token elencati in @command. Questo parametro è valido solo con i comandi in esecuzione nei sottosistemi Transact-SQL, CmdExec, , PowerShellIntegration Services o Analysis Services.

[ @flags = ] flag

Opzione che consente di controllare il comportamento. @flags è int e può essere uno di questi valori.

Valore Descrizione
0 (predefinito) Il file di output viene sovrascritto
2 L'output viene aggiunto alla fine del file di output.
4 L'output del passaggio del processo Transact-SQL viene scritto nella cronologia dei passaggi
8 Il log viene scritto nella tabella. La cronologia esistente viene sovrascritta
16 Il log viene scritto nella tabella in aggiunta alla cronologia esistente
32 Tutto l'output viene scritto nella cronologia processo
64 Creare un evento di Windows da usare come segnale per il passaggio del processo per interrompere l'interruzione cmd

[ @proxy_id = ] proxy_id

ID del proxy in base al quale viene eseguito il passaggio del processo. @proxy_id è int, con il valore predefinito NULL. Se non viene specificato alcun @proxy_id , non viene specificato alcun @proxy_name e non viene specificato alcun @database_user_name , il passaggio del processo viene eseguito come account del servizio per SQL Server Agent.

[ @proxy_name = ] N'proxy_name'

Nome del proxy in base al quale viene eseguito il passaggio del processo. @proxy_name è sysname, con il valore predefinito NULL. Se non viene specificato alcun @proxy_id , non viene specificato alcun @proxy_name e non viene specificato alcun @database_user_name , il passaggio del processo viene eseguito come account del servizio per SQL Server Agent.

[ @step_uid = ] OUTPUT 'step_uid'

@step_uid è un parametro OUTPUT di tipo uniqueidentifier.

Valori del codice restituito

0 (esito positivo) o 1 (errore).

Set di risultati

Nessuno.

Osservazioni:

sp_add_jobstep deve essere eseguito dal msdb database.

SQL Server Management Studio include un semplice strumento grafico per la gestione dei processi ed è lo strumento consigliato per la creazione e gestione dell'infrastruttura dei processi.

Per impostazione predefinita, un passaggio del processo viene eseguito come account del servizio per SQL Server Agent, a meno che non venga specificato un altro proxy. Un requisito di questo account deve essere membro del ruolo predefinito di sicurezza sysadmin .

Un proxy può essere identificato da @proxy_name o @proxy_id.

Questa stored procedure condivide il nome di con un oggetto simile per il servizio Processi elastici di sp_add_jobstep Azure per database SQL di Azure. Per informazioni sulla versione dei processi elastici, vedere jobs.sp_add_jobstep (Processi elastici di Azure) (Transact-SQL).

Autorizzazioni

Questa stored procedure è di proprietà del ruolo db_owner . È possibile concedere EXECUTE autorizzazioni per qualsiasi utente, ma queste autorizzazioni possono essere sottoposte a override durante un aggiornamento di SQL Server.

È necessario concedere ad altri utenti uno dei ruoli predefiniti del database di SQL Server Agent seguenti:msdb

  • SQLAgentUserRole
  • SQLAgentReaderRole
  • SQLAgentOperatorRole

Per informazioni dettagliate sulle autorizzazioni di questi ruoli, vedere Ruoli di database predefiniti di SQL Server Agent.

L'autore del passaggio del processo deve avere accesso al proxy per il passaggio del processo. I membri del ruolo predefinito del server sysadmin hanno accesso a tutti i proxy. Per quanto riguarda gli altri utenti, è necessario concedere esplicitamente l'accesso a un proxy.

Esempi

Nell'esempio seguente viene creato un passaggio di processo che modifica l'accesso al database impostando la modalità sola lettura per il database Sales. In questo esempio vengono inoltre specificati cinque tentativi, con ogni tentativo di esecuzione dopo un'attesa di 5 minuti.

Nota

In questo esempio si presuppone che il processo Weekly Sales Data Backup esista già.

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

Contenuto correlato