Ajouter une étape de travail à un travail existant de l'Agent SQL Server (T-SQL)

Lorsque vous créez un travail de l'Agent SQL Server avec T-SQL, vous utilisez le sp_add_jobstep procédure stockée pour ajouter chaque étape de tâche.

Si jamais vous avez besoin d'ajouter une nouvelle étape à ce travail, vous pouvez utiliser sp_add_jobstep une fois de plus pour ajouter la nouvelle étape de travail.

Mais vous devrez peut-être également modifier l'étape existante, selon la façon dont vous souhaitez que la tâche progresse dans les étapes.

Exemple

Dans cet exemple, nous créons un travail avec une étape de travail, puis nous utilisons sp_add_jobstep pour ajouter une deuxième étape à ce travail. Nous utilisons ensuite sp_update_jobstep pour mettre à jour la première étape de tâche afin qu'elle passe à la deuxième étape de tâche dès qu'elle est terminée.

Créer la tâche

Tout d'abord, créez la tâche en une seule étape :

USE msdb;  
GO  
EXEC sp_add_job  
    @job_name = N'SqlAgentTest',
    @description = N'Insert data.',
    @category_name = 'Database Maintenance';
GO  
EXEC sp_add_jobstep  
    @job_name = N'SqlAgentTest',  
    @step_name = N'Insert data for step 1',  
    @subsystem = N'TSQL',  
    @command = N'USE TestDB; INSERT INTO SqlAgentJobs VALUES (''SqlAgentTest'', 1, SYSDATETIME())';
GO
EXEC sp_add_schedule 
    @schedule_name = N'Run_Sat_6AM',
    @freq_type = 8,
    @freq_interval = 64,
    @freq_recurrence_factor = 1,
    @active_start_time = 060000;
GO  
EXEC sp_attach_schedule  
   @job_name = N'SqlAgentTest',  
   @schedule_name = N'Run_Sat_6AM';
GO  
EXEC sp_add_jobserver  
    @job_name = N'SqlAgentTest';
GO

Juste pour être clair, la partie suivante était le bit qui a ajouté l'étape :

EXEC sp_add_jobstep  
    @job_name = N'SqlAgentTest',  
    @step_name = N'Insert data for step 1',  
    @subsystem = N'TSQL',  
    @command = N'USE TestDB; INSERT INTO SqlAgentJobs VALUES (''SqlAgentTest'', 1, SYSDATETIME())';

Ajouter une nouvelle étape de tâche

Nous pouvons maintenant utiliser sp_add_jobstep à nouveau pour ajouter une nouvelle étape au travail.

USE msdb;
EXEC sp_add_jobstep  
    @job_name = N'SqlAgentTest',  
    @step_name = N'Insert data for step 2',  
    @subsystem = N'TSQL',  
    @command = N'USE TestDB; INSERT INTO SqlAgentJobs VALUES (''SqlAgentTest'', 2, SYSDATETIME())';

Cela ajoute une deuxième étape au travail.

Mettre à jour le flux de travail

Si vous souhaitez que la tâche progresse automatiquement de l'étape 1 à l'étape 2, vous devrez le spécifier à l'étape 1 de la tâche.

L'action par défaut pour toute étape de travail consiste à quitter le travail avec succès dès qu'il réussit. Si l'étape échoue, l'action par défaut consiste à quitter avec échec.

Ainsi, dans l'état actuel de notre travail, le travail se terminera dès que l'étape 1 sera terminée (sans exécuter l'étape 2), et l'historique indiquera que le travail a été exécuté avec succès.

Par conséquent, nous devons utiliser sp_update_jobstep pour mettre à jour l'étape 1, afin qu'elle passe à l'étape 2 une fois terminée avec succès.

Nous pouvons également spécifier ce qu'il faut faire si l'étape 1 échoue.

USE msdb;
EXEC sp_update_jobstep  
    @job_name = N'SqlAgentTest',  
    @step_id = 1,  
    @on_success_action = 3,  
    @on_fail_action = 3;

Dans ce cas, j'ai spécifié qu'il devrait passer à l'étape suivante à la fois s'il réussit et aussi s'il échoue.

Les valeurs que vous pouvez fournir à @on_success_action et @on_fail_action sont les suivants :

Afficher les étapes du travail

Vous pouvez utiliser sp_help_job pour obtenir des informations sur les travaux de l'Agent SQL Server dans le système.

Vous pouvez l'utiliser avec ou sans paramètres, mais pour obtenir les détails de l'étape de la tâche, vous devez fournir le nom ou l'ID de la tâche.

Nous pouvons l'utiliser pour voir les deux étapes de travail que nous avons créées pour le travail.

Comme ceci :

EXEC sp_help_job 
	@job_name = 'SqlAgentTest';

Voici à quoi ressemble le résultat lors de son exécution dans SSMS :

Voici un exemple de code lors de l'utilisation de l'ID :

EXEC sp_help_job 
	@job_id = '343D9F2A-070A-4367-BF69-4248FFF57D70';

Lorsque vous utilisez l'ID, vous pouvez omettre le nom du paramètre si vous le souhaitez.

Exemple :

EXEC sp_help_job '343D9F2A-070A-4367-BF69-4248FFF57D70';

Vous pouvez également utiliser sp_help_jobstep de la même manière pour renvoyer uniquement les étapes du travail (sans toutes les autres informations sur le travail). Cela accepte le nom ou l'ID de la tâche, ainsi qu'un nom ou un ID d'étape facultatif.

Syntaxe complète

La syntaxe complète de sp_add_jobstep va comme ceci :

sp_add_jobstep [ @job_id = ] job_id | [ @job_name = ] 'job_name'
     [ , [ @step_id = ] step_id ]
     { , [ @step_name = ] 'step_name' }
     [ , [ @subsystem = ] 'subsystem' ]
     [ , [ @command = ] 'command' ]
     [ , [ @additional_parameters = ] '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 = ] 'server' ]
     [ , [ @database_name = ] 'database' ]
     [ , [ @database_user_name = ] 'user' ]
     [ , [ @retry_attempts = ] retry_attempts ]
     [ , [ @retry_interval = ] retry_interval ]
     [ , [ @os_run_priority = ] run_priority ]
     [ , [ @output_file_name = ] 'file_name' ]
     [ , [ @flags = ] flags ]
     [ , { [ @proxy_id = ] proxy_id
         | [ @proxy_name = ] 'proxy_name' } ]

Voir la documentation de Microsoft pour sp_add_jobstep pour une explication de chaque paramètre, ainsi que les valeurs que chacun accepte.

La syntaxe complète de sp_update_jobstep va comme ceci :

sp_update_jobstep   
     {   [@job_id =] job_id   
       | [@job_name =] 'job_name' } ,  
     [@step_id =] step_id  
     [ , [@step_name =] 'step_name' ]  
     [ , [@subsystem =] 'subsystem' ]   
     [ , [@command =] 'command' ]  
     [ , [@additional_parameters =] 'parameters' ]  
     [ , [@cmdexec_success_code =] success_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 =] 'server' ]   
     [ , [@database_name =] 'database' ]  
     [ , [@database_user_name =] 'user' ]   
     [ , [@retry_attempts =] retry_attempts ]  
     [ , [@retry_interval =] retry_interval ]   
     [ , [@os_run_priority =] run_priority ]  
     [ , [@output_file_name =] 'file_name' ]   
     [ , [@flags =] flags ]  
     [ ,  {   [ @proxy_id = ] proxy_id   
            | [ @proxy_name = ] 'proxy_name' }

Consultez la documentation de Microsoft pour sp_update_jobstep pour une explication de chaque paramètre, ainsi que les valeurs que chacun accepte.