sp_add_jobstep (Transact-SQL)
S’applique à : 
SQL Server Azure SQL Managed Instance
Ajoute une étape (opération) à un travail SQL Server Agent.
Conventions de la syntaxe Transact-SQL
Important
Sur Azure SQL Managed Instance, la plupart, mais pas tous les types de travaux SQL Server Agent sont pris en charge. Pour plus d’informations, consultez Différences T-SQL entre Azure SQL Managed Instance et SQL Server.
Syntaxe
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 ]
[ ; ]
Arguments
[ @job_id = ] 'job_id'
Numéro d'identification du travail auquel ajouter l'étape. @job_id est uniqueidentifier, avec la valeur par défaut NULL.
Vous devez spécifier @job_id ou @job_name , mais les deux ne peuvent pas être spécifiées.
[ @job_name = ] N’job_name'
Nom du travail auquel ajouter l'étape. @job_name est sysname, avec la valeur par défaut NULL.
Vous devez spécifier @job_id ou @job_name , mais les deux ne peuvent pas être spécifiées.
[ @step_id = ] step_id
Numéro d'identification de la séquence de l'étape de travail. @step_id est int, avec la valeur par défaut NULL. Les numéros d’identification des étapes commencent à 1 et incrémentent sans lacunes. 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ée.
[ @step_name = ] N’step_name'
Nom de l’étape. @step_name est sysname, sans valeur par défaut.
[ @subsystem = ] N’sous-système'
Sous-système utilisé par le service SQL Server Agent pour exécuter @command. @subsystem est nvarchar(40) et peut être l’une de ces valeurs.
| Valeur | Description |
|---|---|
ActiveScripting |
Script actif Important : cette fonctionnalité sera supprimée dans une prochaine version de 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) |
SSIS |
Exécution du package Integration Services |
PowerShell |
script PowerShell |
TSQL (valeur par défaut) |
Instruction Transact-SQL |
[ @command = ] N’command'
Commandes à exécuter par le service SQL Server Agent via @subsystem. @command est nvarchar(max), avec la valeur par défaut NULL. SQL Server Agent fournit une substitution de jetons, ce qui vous offre la même flexibilité que les variables lorsque vous écrivez des programmes logiciels.
Une macro d’échappement doit accompagner tous les jetons utilisés dans les étapes du travail, ou bien ces étapes de travail échouent. 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 la mise à jour de vos étapes de travail pour utiliser la nouvelle syntaxe de jeton, consultez Utiliser des jetons dans les étapes du travail.
Tout utilisateur Windows qui dispose des autorisations d'écriture dans le journal des é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 éviter ce risque de sécurité, les jetons de SQL Server Agent qui peuvent être utilisés dans des travaux activés par des alertes sont désactivés par défaut. Ces jetons sont les suivants : A-DBN, , A-SVRA-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, pour activer ces jetons, cliquez avec le bouton droit sur SQL Server Agent dans l’Explorateur d’objets, sélectionnez Propriétés, puis dans la page Système d’alerte qui s’affiche, sélectionnez l’option Remplacer les jetons pour toutes les réponses de travaux aux alertes .
[ @additional_parameters = ] N’additional_parameters'
Identifié à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie.
[ @cmdexec_success_code = ] cmdexec_success_code
Valeur retournée par une commande de CmdExec sous-système pour indiquer que @command exécuté avec succès. @cmdexec_success_code est int, avec la valeur par défaut 0.
[ @on_success_action = ] on_success_action
Action à effectuer si l'étape est exécutée correctement. @on_success_action est tinyint et peut être l’une de ces valeurs.
| Valeur | Description (action) |
|---|---|
1 (valeur par défaut) |
Quitter avec succès |
2 |
Quitter en cas d’échec |
3 |
Passez à l'étape suivante |
4 |
Passer à l’étape @on_success_step_id |
[ @on_success_step_id = ] on_success_step_id
ID de l’étape de ce travail à exécuter si l’étape réussit et @on_success_action est 4. @on_success_step_id est int, avec la valeur par défaut 0.
[ @on_fail_action = ] on_fail_action
Action à effectuer si l’étape échoue. @on_fail_action est tinyint et peut être l’une de ces valeurs.
| Valeur | Description (action) |
|---|---|
1 |
Quitter avec succès |
2 (valeur par défaut) |
Quitter en cas d’échec |
3 |
Passez à l'étape suivante |
4 |
Accéder à l’étape @on_fail_step_id |
[ @on_fail_step_id = ] on_fail_step_id
ID de l’étape de ce travail à exécuter si l’étape échoue et @on_fail_action est 4. @on_fail_step_id est int, avec la valeur par défaut 0.
[ @server = ] N’server'
Identifié à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie.
[ @database_name = ] N’database_name'
Nom de la base de données dans laquelle exécuter une étape Transact-SQL. @database_name est sysname, avec une valeur par défaut NULL, auquel cas la master base de données est utilisée. Les noms placés entre crochets ([]) ne sont pas autorisés. Pour une étape de travail ActiveX, l '@database_name est le nom du langage de script utilisé par l’étape.
[ @database_user_name = ] N’database_user_name'
Nom du compte d’utilisateur à utiliser lors de l’exécution d’une étape Transact-SQL. @database_user_name est sysname, avec la valeur par défaut NULL. Lorsque @database_user_name est NULL, l’étape s’exécute dans le contexte utilisateur du propriétaire du travail sur @database_name. SQL Server Agent inclut ce paramètre uniquement si le propriétaire du travail est un administrateur système SQL Server. Dans ce cas, l’étape Transact-SQL donnée est exécutée dans le contexte du nom d’utilisateur SQL Server donné. Si le propriétaire du travail n’est pas un administrateur système SQL Server, l’étape Transact-SQL est toujours exécutée dans le contexte de la connexion propriétaire 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_attempts est int, avec une valeur par défaut , 0qui indique qu’aucune tentative de nouvelle tentative n’est effectuée.
[ @retry_interval = ] retry_interval
Nombre de minutes s'écoulant entre chaque tentative de reprise. @retry_interval est int, avec une valeur par défaut , 0qui indique un 0intervalle -minute.
[ @os_run_priority = ] os_run_priority
Identifié à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie.
[ @output_file_name = ] N’output_file_name'
Nom du fichier dans lequel est enregistré le résultat de l'étape. @output_file_name est nvarchar(200), avec la valeur par défaut NULL. @output_file_name pouvez inclure un ou plusieurs jetons répertoriés sous @command. Ce paramètre est valide uniquement avec les commandes s’exécutant sur les sous-systèmes Transact-SQL, CmdExec, PowerShellIntegration Services ou Analysis Services.
[ @flags = ] indicateurs
Option qui contrôle le comportement. @flags est int et peut être l’une de ces valeurs.
| Valeur | Description |
|---|---|
0 (valeur 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éer un événement Windows à utiliser comme signal pour que l’étape du cmd travail abandonne |
[ @proxy_id = ] proxy_id
Numéro d'identification du proxy sous lequel s'exécute l'étape de travail. @proxy_id est int, avec la valeur par défaut NULL. Si aucune @proxy_id n’est spécifiée, aucune @proxy_name n’est spécifiée et aucune @database_user_name n’est spécifiée, l’étape de travail s’exécute en tant que compte de service pour SQL Server Agent.
[ @proxy_name = ] N’proxy_name'
Nom du proxy sous lequel s'exécute l'étape de travail. @proxy_name est sysname, avec la valeur par défaut NULL. Si aucune @proxy_id n’est spécifiée, aucune @proxy_name n’est spécifiée et aucune @database_user_name n’est spécifiée, l’étape de travail s’exécute en tant que compte de service pour SQL Server Agent.
[ @step_uid = ] SORTIE 'step_uid'
@step_uid est un paramètre OUTPUT de type uniqueidentifier.
Valeurs des codes de retour
0 (réussite) or 1 (échec).
Jeu de résultats
Aucune.
Notes
sp_add_jobstep doit être exécuté à partir de la msdb base de données.
SQL Server Management Studio offre un moyen simple et graphique de gérer les tâches, et est recommandé pour la création et la gestion de l'infrastructure de travail.
Par défaut, une étape de travail s’exécute en tant que compte de service pour SQL Server Agent, sauf si un autre proxy est spécifié. L’exigence de ce compte est d’être membre du rôle de sécurité fixe sysadmin .
Un proxy peut être identifié par @proxy_name ou @proxy_id.
Cette procédure stockée partage le nom d’un sp_add_jobstep objet similaire pour le service Travaux élastiques Azure pour Azure SQL Database. Pour plus d’informations sur la version des travaux élastiques, consultez jobs.sp_add_jobstep (Travaux élastiques Azure).
autorisations
Vous pouvez accorder EXECUTE des autorisations sur cette procédure, mais ces autorisations peuvent être remplacées lors d’une mise à niveau de SQL Server.
D’autres utilisateurs doivent disposer de l’un des rôles de base de données fixes SQL Server Agent suivants dans la msdb base de données :
- 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 ont accès à tous les proxys. 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 spécifie cinq tentatives de nouvelle tentative, chaque nouvelle tentative se produisant après une attente de 5 minutes.
Remarque
Cet exemple suppose que le Weekly Sales Data Backup travail 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