sp_add_jobstep (Transact-SQL)
S’applique à :
SQL Server (toutes les versions prises en charge) Azure SQL Managed Instance
Ajoute une étape (opération) à un travail SQL Agent.
Conventions de la syntaxe Transact-SQL
Important
Sur Azure SQL Managed Instance, la plupart des types de travaux SQL Server Agent, mais pas tous, 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 = ] '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 uniqueidentifier, avec la valeur par défaut NULL.
[ @job_name = ] 'job_name' Nom du travail auquel ajouter l’étape. job_name est sysname, avec la valeur par défaut NULL.
Notes
Vous devez spécifier job_id ou job_name , mais les deux ne peuvent pas être spécifiés.
[ @step_id = ] step_id Numéro d’identification de séquence de l’étape de travail. Les numéros d’identification d’étape commencent à 1 et s’incrémentent sans intervalles. 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_id est int, avec la valeur par défaut NULL.
[ @step_name = ] 'step_name' Nom de l’étape. step_name est sysname, sans valeur par défaut.
[ @subsystem = ] 'subsystem'Sous-système utilisé par le service SQL Server Agent pour exécuter la commande. le sous-système est nvarchar(40) et peut être l’une de ces valeurs.
| Valeur | Description |
|---|---|
| 'ActiveScripting' | Script actif **Important** Cette fonctionnalité sera supprimée dans une version ultérieure 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 |
| 'Instantané' | Travail de l'Agent d'instantané de réplication |
| 'LogReader' | Travail de l'Agent de lecture du journal de réplications |
| 'Fusionner' | 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' (par défaut) | Instruction Transact-SQL |
[ @command = ] 'command' Commandes à exécuter par le service SQLServerAgent via le sous-système. la commande est nvarchar(max), avec la valeur par défaut NULL. L'Agent SQL Server effectue une substitution de jetons qui offre la même souplesse que les variables lorsque vous écrivez des logiciels.
Important
Une macro d’échappement doit maintenant accompagner tous les jetons utilisés dans les étapes de travail, sinon 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_nom de la macro(DATE))
Pour plus d’informations sur ces jetons et la mise à jour des étapes de votre travail afin d’utiliser la nouvelle syntaxe de jeton, consultez Utiliser des jetons dans les étapes de travail.
Important
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 : A-DBN, A-SVR, A-ERR, A-SEV, A-MSG et WMI(propriété) . 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 = ] 'parameters' Identifié à titre d’information uniquement. Non pris en charge. La compatibilité future n'est pas garantie. parameters est ntext, avec la valeur par défaut NULL.
[ @cmdexec_success_code = ] code Valeur retournée par une commande de sous-système CmdExec pour indiquer que cette commande s’est exécutée avec succès. code est int, avec la valeur par défaut 0.
[ @on_success_action = ] success_action Action à effectuer si l’étape réussit. success_action est tinyint et peut être l’une de ces valeurs.
| Valeur | Description (action) |
|---|---|
| 1 (par défaut) | Quitter avec succès |
| 2 | Quitter avec échec |
| 3 | Passez à l'étape suivante |
| 4 | Accéder à l’étape on_success_step_id |
[ @on_success_step_id = ] success_step_id ID de l’étape dans ce travail à exécuter si l’étape réussit et success_action est 4. success_step_id est int, avec la valeur par défaut 0.
[ @on_fail_action = ] fail_action Action à effectuer en cas d’échec de l’étape. fail_action est tinyint et peut être l’une de ces valeurs.
| Valeur | Description (action) |
|---|---|
| 1 | Quitter avec succès |
| 2 (par défaut) | Quitter avec échec |
| 3 | Passez à l'étape suivante |
| 4 | Accéder à l’étape on_fail_step_id |
[ @on_fail_step_id = ] fail_step_id ID de l’étape dans ce travail à exécuter si l’étape échoue et fail_action est 4. fail_step_id est int, avec la valeur par défaut 0.
[ @server = ] 'server' Identifié à titre d’information uniquement. Non pris en charge. La compatibilité future n'est pas garantie. server est nvarchar(30), avec la valeur par défaut NULL.
[ @database_name = ] 'database' Nom de la base de données dans laquelle exécuter une étape Transact-SQL. la base de données est sysname, avec la valeur par défaut NULL, auquel cas la base de données master est utilisée. Les noms placés entre crochets ([ ]) ne sont pas autorisés. Pour une étape de travail ActiveX, la base de données est le 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. l’utilisateur est sysname, avec la valeur par défaut NULL. Lorsque l’utilisateur a la valeur NULL, l’étape s’exécute dans le contexte utilisateur du propriétaire du travail sur la base de données. 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 SQL Server sysadmin, l’étape Transact-SQL est toujours exécutée dans le contexte de la connexion propriétaire de ce travail, et le @database_user_name paramètre est ignoré.
[ @retry_attempts = ] retry_attempts Nombre de nouvelles tentatives à utiliser en cas d’échec de cette étape. retry_attempts est int, avec la valeur par défaut 0, ce qui indique qu’aucune nouvelle tentative n’est effectuée.
[ @retry_interval = ] retry_interval Durée en minutes entre les tentatives de nouvelle tentative. retry_interval est int, avec la valeur par défaut 0, ce qui indique un intervalle de 0 minute.
[ @os_run_priority = ] run_priority Réservés au.
[ @output_file_name = ] 'file_name' Nom du fichier dans lequel la sortie de cette étape est enregistrée. file_name est nvarchar(200), avec la valeur par défaut NULL. file_name pouvez inclure un ou plusieurs des jetons répertoriés sous la commande . Ce paramètre est valide uniquement avec les commandes exécutées sur les sous-systèmes Transact-SQL, CmdExec, PowerShell, Integration Services ou Analysis Services.
[ @flags = ] flags 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é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 l’étape de travail s’exécute. proxy_id est de type int, avec la valeur par défaut NULL. Si aucune proxy_id n’est spécifiée, qu’aucune proxy_name n’est spécifiée et qu’aucune 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 = ] 'proxy_name' Nom du proxy sous lequel l’étape de travail s’exécute. proxy_name est de type sysname, avec la valeur par défaut NULL. Si aucune proxy_id n’est spécifiée, qu’aucune proxy_name n’est spécifiée et qu’aucune user_name n’est spécifiée, l’étape de travail s’exécute en tant que compte de service pour SQL Server Agent.
Codet de retour
0 (réussite) ou 1 (échec)
Jeux de résultats
None
Remarques
sp_add_jobstep doit être exécuté à partir de la base de données msdb .
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é. Ce compte doit être membre du rôle de sécurité fixe sysadmin .
Un proxy peut être identifié par proxy_name ou proxy_id.
Autorisations
Par défaut, 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 suivants de SQL Server Agent 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 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 indique 5 tentatives de reprises, chacune d'elles étant exécutée toutes les 5 minutes.
Notes
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