sp_add_jobstep (Transact-SQL)

Article
08/20/2013

Ajoute une étape (opération) à un travail.

Icône Lien de rubrique Conventions de la syntaxe Transact-SQL

Syntaxe

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' } ]

Arguments

[ @job_id = ] job_id
Numéro d'identification du travail auquel ajouter l'étape. job_id est de type uniqueidentifier, avec NULL comme valeur par défaut.
[ @job_name = ] 'job_name'
Nom du travail auquel ajouter l'étape. job_name est de type sysname, avec NULL comme valeur par défaut.

[!REMARQUE]

Vous devez définir la valeur de job_id ou de job_name, mais pas les deux valeurs à la fois.
[ @step_id = ] step_id
Numéro d'identification de la séquence de l'étape de travail. Les numéros d'identification d'étape commencent à 1 et sont incrémentés sans intervalle. Si une étape est insérée dans une séquence existante, les numéros de cette séquence sont ajustés automatiquement. Une valeur est fournie si step_id n'est pas spécifié. step_idest de type int, avec NULL comme valeur par défaut.
[ @step_name = ] 'step_name'
Nom de l'étape. step_nameest de type sysname et n'a pas de valeur par défaut.

[ @subsystem = ] 'subsystem'
Sous-système utilisé par le service de l'Agent SQL Server pour exécuter command. subsystem est de type nvarchar(40) et peut prendre l'une des valeurs suivantes.

Valeur	Description
'ACTIVESCRIPTING'	Script actif Important Cette fonctionnalité sera supprimée dans une prochaine version de Microsoft SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité.
'CMDEXEC'	Commande du système d'exécution ou programme exécutable
'DISTRIBUTION'	Travail de l'Agent de distribution de réplication
'SNAPSHOT'	Travail de l'Agent d'instantané de réplication
'LOGREADER'	Travail de l'Agent de lecture du journal de réplications
'MERGE'	Travail de l'Agent de fusion de réplication
'QueueReader'	Travail de l'Agent de lecture de la file d'attente de réplication
'ANALYSISQUERY'	Requête Analysis Services (MDX, DMX).
'ANALYSISCOMMAND'	Commande Analysis Services (XMLA).
'Dts'	Exécution du package Integration Services
'PowerShell'	script PowerShell
'TSQL' (valeur par défaut)	Instruction Transact-SQL

[ @command= ] 'command'
Commandes devant être exécutées par le service SQLServerAgent via subsystem. command est de type nvarchar(max), avec NULL comme valeur par défaut. L'Agent SQL Server effectue une substitution de jetons qui offre la même souplesse que les variables lorsque vous écrivez des logiciels.

Important

Dans SQL Server 2005 Service Pack 1, la syntaxe de jeton des étapes de travail de l'Agent SQL Server n'est plus la même. Par conséquent, une macro d'échappement doit désormais accompagner tous les jetons utilisés dans les étapes de travail, afin que celles-ci n'échouent pas. De plus, vous devez désormais mettre les noms de jeton entre parenthèses et placer un signe dollar ($) au début de la syntaxe du jeton. Par exemple :

$(ESCAPE_macro name(DATE))

Pour plus d'informations sur ces jetons et sur la mise à jour des étapes de travail afin d'utiliser la nouvelle syntaxe des jetons, consultez Utiliser des jetons dans les étapes d'un travail.

Remarque relative à la sécurité
Tout utilisateur Windows qui dispose des autorisations d'écriture dans le journal d'événements Windows peut accéder aux étapes de travail activées par les alertes WMI ou par les alertes de SQL Server Agent. Pour remédier à ce problème lié à la sécurité, les jetons de l'Agent SQL Server qui sont utilisables dans les travaux activés par les alertes sont désactivés par défaut. Ces jetons sont A-DBN, A-SVR, A-ERR, A-SEV, A-MSG et WMI(property). Notez que dans cette version, l'utilisation des jetons est étendue toutes les alertes. Si vous devez utiliser ces jetons, assurez-vous d'abord que seuls les membres des groupes de sécurité Windows approuvés, comme le groupe Administrateurs, disposent des autorisations d'écriture pour le journal d'événements de l'ordinateur sur lequel SQL Server réside. Ensuite, affichez l'Explorateur d'objets, cliquez avec le bouton droit sur Agent SQL Server, puis sélectionnez Propriétés et dans la page Système d'alerte qui s'affiche, sélectionnez Remplacer les jetons pour toutes les réponses de travaux aux alertes pour activer ces jetons.

Tout utilisateur Windows qui dispose des autorisations d'écriture dans le journal d'événements Windows peut accéder aux étapes de travail activées par les alertes WMI ou par les alertes de SQL Server Agent. Pour remédier à ce problème lié à la sécurité, les jetons de l'Agent SQL Server qui sont utilisables dans les travaux activés par les alertes sont désactivés par défaut. Ces jetons sont A-DBN, A-SVR, A-ERR, A-SEV, A-MSG et WMI(property). Notez que dans cette version, l'utilisation des jetons est étendue toutes les alertes.

Si vous devez utiliser ces jetons, assurez-vous d'abord que seuls les membres des groupes de sécurité Windows approuvés, comme le groupe Administrateurs, disposent des autorisations d'écriture pour le journal d'événements de l'ordinateur sur lequel SQL Server réside. Ensuite, affichez l'Explorateur d'objets, cliquez avec le bouton droit sur Agent SQL Server, puis sélectionnez Propriétés et dans la page Système d'alerte qui s'affiche, sélectionnez Remplacer les jetons pour toutes les réponses de travaux aux alertes pour activer ces jetons.

[ @additional_parameters= ] 'parameters'
Identifié à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie. parameters est de type ntext, avec NULL comme valeur par défaut.
[ @cmdexec_success_code = ] code
Valeur retournée par une commande du sous-système CmdExec pour indiquer que l'argument command a été exécuté avec succès. codeest de type int, avec 0 comme valeur par défaut.
[ @on_success_action= ] success_action
Action à effectuer si l'étape est exécutée correctement. success_actionest de type tinyint et peut prendre l'une des valeurs suivantes.

Valeur

Description (action)

1 (valeur par défaut)

Sortie avec succès

2

Sortie avec échec

3

Passez à l'étape suivante

4

Passez à l'étape on_success_step_id
[ @on_success_step_id = ] success_step_id
ID de l'étape à exécuter dans ce travail si l'étape réussit et si success_actiona la valeur 4. success_step_idest de type int, avec 0 comme valeur par défaut.
[ @on_fail_action= ] fail_action
Action à exécuter si l'étape échoue. fail_actionest de type tinyint et peut prendre l'une des valeurs suivantes.

Valeur

Description (action)

1

Sortie avec succès

2 (valeur par défaut)

Sortie avec échec

3

Passez à l'étape suivante

4

Passez à l'étape on_fail_step_id
[ @on_fail_step_id= ] fail_step_id
ID de l'étape à exécuter dans ce travail si l'étape échoue et si fail_actiona la valeur 4. fail_step_idest de type int, avec 0 comme valeur par défaut.
[ @server =] 'server'
Identifié à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie. serverest de type nvarchar(30), avec NULL comme valeur par défaut.
[ @database_name = ] 'database'
Nom de la base de données dans laquelle l'étape Transact-SQL doit être exécutée. database est de type sysname, avec NULL comme valeur par défaut, auquel cas la base de données maîtreest utilisée. Les noms placés entre crochets ([]) ne sont pas autorisés. Pour une étape de travail ActiveX, database correspond au nom du langage de script utilisé par l'étape.
[ @database_user_name= ] 'user'
Nom du compte d'utilisateur à utiliser lors de l'exécution d'une étape Transact-SQL. user est de type sysname, avec NULL comme valeur par défaut. Lorsque la valeur de user est NULL, l'étape est exécutée dans le contexte de l'utilisateur propriétaire du travail dans database. L'Agent SQL Server inclut ce paramètre uniquement si le propriétaire du travail est un sysadmin SQL Server. Dans ce cas, l'étape Transact-SQL donnée est exécutée dans le contexte du nom d'utilisateur SQL Server spécifié. Si le propriétaire du travail n'est pas un sysadmin SQL Server, l'étape Transact-SQL est toujours exécutée dans le contexte de la connexion qui possède ce travail et le paramètre @database\_user\_name est ignoré.
[ @retry_attempts= ] retry_attempts
Nombre de tentatives à effectuer si l'étape échoue. retry_attemptsest de type int, avec 0 comme valeur par défaut, indiquant aucune tentative.
[ @retry_interval= ] retry_interval
Nombre de minutes s'écoulant entre chaque tentative de reprise. retry_intervalest de type int, avec 0 comme valeur par défaut, indiquant un intervalle de 0 minute.
[ @os_run_priority = ] run_priority
Réservé.
[ @output_file_name= ] 'file_name'
Nom du fichier dans lequel est enregistré le résultat de l'étape. file_nameest de type nvarchar(200), avec NULL comme valeur par défaut. file_name peut inclure un ou plusieurs jetons répertoriés sous command. Ce paramètre est valide uniquement avec les commandes fonctionnant dans les sous-systèmes Transact-SQL, CmdExec, PowerShell, Integration Services ou Analysis Services.

Valeur	Description (action)
1 (valeur par défaut)	Sortie avec succès
2	Sortie avec échec
3	Passez à l'étape suivante
4	Passez à l'étape on_success_step_id

Valeur	Description (action)
1	Sortie avec succès
2 (valeur par défaut)	Sortie avec échec
3	Passez à l'étape suivante
4	Passez à l'étape on_fail_step_id

[ @flags= ] flags
Option contrôlant le comportement. flags est de type int et peut prendre l'une des valeurs suivantes.

Valeur	Description
0 (par défaut)	Écrasement du fichier de sortie
2	Ajout au fichier de sortie
4	Écriture de la sortie de l'étape d'un travail Transact-SQL dans l'historique des étapes.
8	Écriture du journal dans la table (remplace l'historique existant)
16	Écriture du journal dans la table (s'ajoute à l'historique existant)
32	Écriture de toute la sortie dans l'historique des travaux
64	Création d'un événement Windows à utiliser comme signal pour l'étape de travail Cmd à abandonner

[ @proxy_id = ] proxy_id
Numéro d'identification du proxy sous lequel s'exécute l'étape de travail. proxy_id est de type int, avec NULL comme valeur par défaut. Si aucune valeur proxy_id, proxy_name et user_name n'est spécifiée, l'étape du travail s'exécute sous le compte du service pour l'Agent SQL Server.
[ @proxy_name = ] 'proxy_name'
Nom du proxy sous lequel s'exécute l'étape de travail. proxy_name est de type sysname, avec NULL comme valeur par défaut. Si aucune valeur proxy_id, proxy_name et user_name n'est spécifiée, l'étape du travail s'exécute sous le compte de service de l'Agent SQL Server.

Valeurs des codes de retour

0 (succès) ou 1 (échec)

Jeux de résultats

Aucun

Notes

La procédure sp_add_jobstep doit être exécutée à partir de la base de données msdb.

SQL Server Management Studio est un outil simple, basé sur une interface graphique, qui permet de gérer les travaux. Son utilisation est recommandée pour créer et gérer l'infrastructure des travaux.

Une étape de travail doit spécifier un proxy, sauf si le créateur de l'étape est membre du rôle de sécurité fixe sysadmin.

Un proxy est identifié par l'argument proxy_name ou proxy_id.

Autorisations

Seuls les membres du rôle serveur fixe sysadmin peuvent exécuter cette procédure stockée. Les autres utilisateurs doivent disposer de l'un des rôles de base de données fixes SQL Server Agent suivants dans la base de données msdb.

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

Pour en savoir plus sur les autorisations de ces rôles, consultez Rôles de base de données fixes de l'Agent SQL Server.

Le créateur de l'étape de travail doit disposer des droits d'accès au proxy pour cette étape. Les membres du rôle serveur fixe sysadmin disposent des droits d'accès à tous les serveurs proxy. Pour les autres utilisateurs, les droits d'accès à un proxy doivent être octroyés explicitement.

Exemples

L'exemple suivant montre la création de l'étape d'un travail permettant de modifier l'accès à une base de données appelée Sales et de lui affecter le mode d'accès en lecture seule. En outre, cet exemple indique 5 tentatives de reprises, chacune d'elles étant exécutée toutes les 5 minutes.

[!REMARQUE]

Cet exemple part du principe que le travail Weekly Sales Data Backup existe déjà.

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