sp_add_job (Transact-SQL)

Article
08/20/2013

Ajoute un nouveau travail exécuté par le service SQLServerAgent.

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

Syntaxe

sp_add_job [ @job_name = ] 'job_name'
     [ , [ @enabled = ] enabled ] 
     [ , [ @description = ] 'description' ] 
     [ , [ @start_step_id = ] step_id ] 
     [ , [ @category_name = ] 'category' ] 
     [ , [ @category_id = ] category_id ] 
     [ , [ @owner_login_name = ] 'login' ] 
     [ , [ @notify_level_eventlog = ] eventlog_level ] 
     [ , [ @notify_level_email = ] email_level ] 
     [ , [ @notify_level_netsend = ] netsend_level ] 
     [ , [ @notify_level_page = ] page_level ] 
     [ , [ @notify_email_operator_name = ] 'email_name' ] 
          [ , [ @notify_netsend_operator_name = ] 'netsend_name' ] 
     [ , [ @notify_page_operator_name = ] 'page_name' ] 
     [ , [ @delete_level = ] delete_level ] 
     [ , [ @job_id = ] job_id OUTPUT ]

Arguments

[ @job_name = ] 'job_name'
Nom du travail. Le nom doit être unique et ne doit pas contenir le caractère de pourcentage (%). job_nameest de type nvarchar(128) et n'a pas de valeur par défaut.
[ @enabled = ] enabled
Indique l'état du travail ajouté. enabledest de type tinyint, avec 1 (activé) comme valeur par défaut. Si la valeur est 0, le travail n'est pas activé et n'est pas exécuté selon sa planification. Il peut cependant être exécuté manuellement.
[ @description = ] 'description'
Description du travail. description est de type nvarchar(512), avec NULL comme valeur par défaut. Si l'argument description est omis, un message rappelle qu'aucune description n'est disponible.
[ @start_step_id = ] step_id
Numéro d'identification de la première étape à exécuter pour le travail. step_idest de type int, avec 1 comme valeur par défaut.
[ @category_name = ] 'category'
Catégorie du travail. categoryest de type sysname, avec NULL comme valeur par défaut.
[ @category_id = ] category_id
Mécanisme qui ne tient pas compte de la langue définie et qui permet de spécifier une catégorie de travail. category_idest de type int, avec NULL comme valeur par défaut.
[ @owner_login_name = ] 'login'
Nom du compte de connexion propriétaire du travail. loginest de type sysname, avec NULL comme valeur par défaut. Cet argument est interprété comme le nom de connexion d'accès en cours. Seuls les membres du rôle de serveur fixe sysadmin peuvent définir ou modifier la valeur pour @owner_login_name. Si des utilisateurs non membres du rôle sysadmin définissent ou modifient la valeur de @owner_login_name, l'exécution de cette procédure stockée échoue et une erreur est retournée.
[ @notify_level_eventlog = ] eventlog_level
Valeur indiquant le moment auquel une entrée doit être ajoutée pour ce travail dans le journal des applications Microsoft Windows. eventlog_levelest de type int et peut prendre l'une des valeurs suivantes.

Valeur

Description

0

Never

1

Si succès

2 (valeur par défaut)

Si échec

3

Always
[ @notify_level_email = ] email_level
Valeur indiquant à quel moment envoyer un message électronique une fois ce travail achevé. email_levelest de type int, avec 0 comme valeur par défaut, qui indique jamais. email_levelutilise les mêmes valeurs que eventlog_level.
[ @notify_level_netsend = ] netsend_level
Valeur indiquant à quel moment envoyer un message réseau une fois ce travail achevé. netsend_levelest de type int, avec 0 comme valeur par défaut, qui indique jamais. netsend_level utilise les mêmes valeurs que eventlog_level.
[ @notify_level_page = ] page_level
Valeur indiquant à quel moment envoyer une page une fois ce travail achevé. page_levelest de type int, avec 0 comme valeur par défaut, qui indique jamais. page_levelutilise les mêmes valeurs que eventlog_level.
[ @notify_email_operator_name = ] 'email_name'
Adresse électronique de la personne à qui envoyer un message une fois le niveau email_level atteint. email_name est de type sysname, avec NULL comme valeur par défaut.
[ @notify_netsend_operator_name = ] 'netsend_name'
Nom de l'opérateur à qui le message réseau est envoyé une fois ce travail exécuté. netsend_nameest de type sysname, avec NULL comme valeur par défaut.
[ @notify_page_operator_name = ] 'page_name'
Nom de la personne à qui envoyer un message par radiomessagerie une fois ce travail exécuté. page_nameest de type sysname, avec NULL comme valeur par défaut.
[ @delete_level = ] delete_level
Valeur indiquant à quel moment supprimer le travail. delete_valueest de type int, avec 0 comme valeur par défaut, qui signifie jamais. delete_levelutilise les mêmes valeurs que eventlog_level.

[!REMARQUE]

Lorsque la valeur 3 est affectée à delete_level, le travail n'est exécuté qu'une seule fois, indépendamment de toute planification définie pour ce travail. De plus, si un travail est supprimé, son historique est également supprimé.
[ @job_id = ] job_idOUTPUT
Numéro d'identification du travail affecté si le travail est correctement créé. job_idest une variable de sortie de type uniqueidentifier, avec NULL comme valeur par défaut.

Valeur	Description
0	Never
1	Si succès
2 (valeur par défaut)	Si échec
3	Always

Valeurs du code de retour

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

Jeux de résultats

Aucun

Notes

@originating_server existe dans sp_add_job, mais n'est pas répertorié dans les arguments. @originating_server est réservé à un usage interne.

Une fois la procédure sp_add_job exécutée pour ajouter un travail, la procédure sp_add_jobstep peut être utilisée pour ajouter des étapes qui effectuent les opérations du travail. La procédure sp_add_jobschedule permet de créer la planification que le service Agent SQL Server utilise pour exécuter le travail. Utilisez sp_add_jobserver pour définir l'instance de SQL Server où s'exécute le travail, et sp_delete_jobserver pour supprimer le travail à partir de l'instance SQL Server.

Si le travail doit être exécuté sur un ou plusieurs serveurs cibles dans un environnement multiserveurs, utilisez sp_apply_job_to_targets pour définir les serveurs cibles ou les groupes de serveurs cibles pour le travail. sp_remove_job_from_targets supprime les travaux des serveurs cibles ou des groupes de serveurs cibles.

SQL Server Management Studio est un outil dont l'interface graphique permet de gérer facilement les travaux. Son utilisation est recommandée pour créer et gérer l'infrastructure des travaux.

Autorisations

Pour exécuter cette procédure stockée, les utilisateurs doivent être membres du rôle de serveur fixe sysadmin ou disposer de l'un des rôles de base de données fixes SQL Server Agent suivants qui résident dans la base de données msdb.

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

Pour en savoir plus sur les autorisations spécifiques associées à chacun des rôles de base de données fixes, consultez Rôles de base de données fixes de l'Agent SQL Server.

Seuls les membres du rôle de serveur fixe sysadmin peuvent définir ou modifier la valeur pour @owner_login_name. Si des utilisateurs non membres du rôle sysadmin définissent ou modifient la valeur de @owner_login_name, l'exécution de cette procédure stockée échoue et une erreur est retournée.

Exemples

A.Ajout d'un travail

Cet exemple ajoute un nouveau travail appelé NightlyBackups (sauvegardes de nuit).

USE msdb ;
GO

EXEC dbo.sp_add_job
    @job_name = N'NightlyBackups' ;
GO

B.Ajout d'un travail contenant des informations de radiomessagerie, de messagerie électronique et d'envoi réseau

Dans l'exemple ci-dessous, un travail appelé Ad hoc Sales Data Backup avertit François Ajenstat (par radiomessagerie, messagerie électronique ou par message réseau) lorsqu'un travail échoue, et est supprimé une fois exécuté.

[!REMARQUE]

Dans cet exemple, nous considérons qu'un opérateur nommé François Ajenstat avec une connexion appelée françoisa existe déjà.

USE msdb ;
GO

EXEC dbo.sp_add_job
    @job_name = N'Ad hoc Sales Data Backup', 
    @enabled = 1,
    @description = N'Ad hoc backup of sales data',
    @owner_login_name = N'françoisa',
    @notify_level_eventlog = 2,
    @notify_level_email = 2,
    @notify_level_netsend = 2,
    @notify_level_page = 2,
    @notify_email_operator_name = N'François Ajenstat',
    @notify_netsend_operator_name = N'François Ajenstat', 
    @notify_page_operator_name = N'François Ajenstat',
    @delete_level = 1 ;
GO