Utiliser des jetons dans les étapes de travail
s’applique à :
SQL ServerAzure SQL Managed Instance
Important
Sur Azure SQL Managed Instance, la plupart, mais pas toutes les fonctionnalités de SQL Server Agent sont actuellement prises en charge. Pour plus d’informations, consultez différences T-SQL d’Azure SQL Managed Instance par rapport à SQL Server.
SQL Server Agent vous permet d'utiliser des jetons dans les scripts d'étape de tâche Transact-SQL. L’utilisation de jetons lorsque vous écrivez vos étapes de travail vous offre la même flexibilité que celle que fournissent les variables lorsque vous écrivez des programmes logiciels. Après avoir inséré un jeton dans un script d’étape de travail, SQL Server Agent remplace le jeton au moment de l’exécution, avant l’exécution de l’étape de travail par le sous-système Transact-SQL.
Comprendre l’utilisation de jetons
Important
Tout utilisateur Windows disposant d’autorisations d’écriture dans le journal des événements Windows peut accéder aux étapes de travail activées par les alertes SQL Server Agent ou les alertes WMI. Pour éviter ce risque de sécurité, les jetons SQL Server Agent qui peuvent être utilisés 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-MSGet WMI(). Dans cette version, l’utilisation de jetons est étendue à toutes les alertes.
Si vous devez utiliser ces jetons, vérifiez d’abord que seuls les membres des groupes de sécurité Windows approuvés, tels que le groupe Administrateurs, disposent d’autorisations d’écriture sur le journal des événements de l’ordinateur où réside SQL Server. Cliquez ensuite 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, sélectionnez Remplacer les jetons pour toutes les réponses de tâches aux alertes pour activer ces jetons.
Le remplacement du jeton SQL Server Agent est simple et efficace : SQL Server Agent remplace une valeur de chaîne littérale exacte pour le jeton. Tous les jetons respectent la casse. Vos étapes de travail doivent prendre cela en compte et citer correctement les jetons que vous utilisez ou convertir la chaîne de substitution au type de données approprié.
Par exemple, vous pouvez utiliser l’instruction suivante pour imprimer le nom de la base de données dans une étape de travail :
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
Dans cet exemple, la macro ESCAPE_SQUOTE est insérée avec le jeton A-DBN. Au moment de l’exécution, le jeton A-DBN est remplacé par le nom de base de données approprié. La macro d’échappement échappe les guillemets simples qui peuvent être transmis par inadvertance dans la chaîne de remplacement de jeton. SQL Server Agent remplace un guillemet unique par deux guillemets simples dans la chaîne finale.
Par exemple, si la chaîne passée pour remplacer le jeton est AdventureWorks2022'SELECT @@VERSION --, la commande exécutée par l’étape du travail du SQL Server Agent est :
PRINT N'Current database name is AdventureWorks2022''SELECT @@VERSION --' ;
Dans ce cas, l’instruction insérée, SELECT @@VERSION, n’est pas exécutée. Au lieu de cela, le guillemet unique supplémentaire entraîne l’analyse de l’instruction insérée en tant que chaîne par le serveur. Si la chaîne de remplacement de jeton ne contient pas d'apostrophe, aucun caractère n’est échappé et l’étape de la tâche contenant le jeton s’exécute comme prévu.
Pour déboguer l’utilisation des jetons dans vos étapes de travail, utilisez des instructions d’impression telles que PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' et enregistrez la sortie de l’étape de travail dans un fichier ou une table. Utilisez la page Advanced de la boîte de dialogue Propriétés de l’étape de travail pour spécifier un fichier ou une table de sortie d’étape de travail.
Les jetons et macros SQL Server Agent
Les tableaux suivants répertorient et décrivent les jetons et macros pris en charge par SQL Server Agent.
Jetons SQL Server Agent
| Jeton | Description |
|---|---|
| (A-DBN) | Nom de la base de données. Si la tâche est exécutée par une alerte, la valeur du nom de la base de données remplace automatiquement ce jeton à l’étape de la tâche. |
| (A-SVR) | Nom du serveur. Si le travail est exécuté à la suite d'une alerte, la valeur du nom du serveur remplace automatiquement ce jeton à l'étape de la tâche. |
| (A-ERR) | Numéro d’erreur. Si la tâche est exécutée par une alerte, le numéro d’erreur remplace automatiquement ce jeton à l’étape de la tâche. |
| (A-SEV) | Gravité de l’erreur. Si la tâche est exécutée suite à une alerte, la valeur de gravité de l’erreur remplace automatiquement ce jeton à l’étape de la tâche. |
| (A-MSG) | Texte du message. Si la tâche est exécutée par une alerte, la valeur de texte du message remplace automatiquement ce jeton dans l'étape de la tâche. |
| (JOBNAME) | Nom du travail. Ce jeton est disponible uniquement sur SQL Server 2016 et versions ultérieures. |
| (STEPNAME) | Nom de l’étape. Ce jeton est disponible uniquement sur SQL Server 2016 et versions ultérieures. |
| (DATE) | Date actuelle (au format AAAAMMDD). |
| (INST) | Nom de l’instance. Pour une instance par défaut, ce jeton a le nom d’instance par défaut : MSSQLSERVER. |
| (JOBID) | ID du travail. |
| (MACH) | Nom de l’ordinateur. |
| (MSSA) | Nom du service MASTER SQLServerAgent. |
| (OSCMD) | Préfixe du programme utilisé pour exécuter les étapes de tâche CmdExec. |
| (SQLDIR) | Répertoire dans lequel SQL Server est installé. Par défaut, cette valeur est C :\Program Files\Microsoft SQL Server\MSSQL. |
| (SQLLOGDIR) | Jeton de remplacement pour le chemin du dossier du journal des erreurs SQL Server ( par exemple, $(ESCAPE_SQUOTE(SQLLOGDIR)). Ce jeton est disponible uniquement sur SQL Server 2014 et versions ultérieures. |
| (STEPCT) | Nombre de fois où cette étape a été exécutée (à l’exception des nouvelles tentatives). Peut être utilisé par la commande 'step' pour forcer l’arrêt d’une boucle à plusieurs étapes. |
| (STEPID) | ID d’étape. |
| (SRVR) | Nom de l’ordinateur exécutant SQL Server. Si l’instance SQL Server est une instance nommée, cela inclut le nom de l’instance. |
| (TIME) | Heure actuelle (au format HHMMSS). |
| (STRTTM) | Heure (au format HHMMSS) pendant laquelle le travail a commencé à s’exécuter. |
| (STRTDT) | La date (format AAAAMMDD) à laquelle le travail a commencé à être exécuté. |
| (propriété WMI()) | Pour les travaux qui s’exécutent en réponse aux alertes WMI, la valeur de la propriété spécifiée par propriété. Par exemple, $(WMI(DatabaseName)) fournit la valeur de la propriété DatabaseName pour l’événement WMI qui a provoqué l’exécution de l’alerte. |
Macros d’échappement SQL Server Agent
| Macros d’échappement | Description |
|---|---|
| $(ESCAPE_SQUOTE(token_name)) | Annule le caractère guillemet simple (') dans la chaîne de remplacement de jeton. Remplace un guillemet simple par deux guillemets simples. |
| $(ESCAPE_DQUOTE(token_name)) | Échappe les guillemets doubles (") dans la chaîne de caractères de remplacement du jeton. Remplace un guillemet double par deux guillemets doubles. |
| $(ESCAPE_RBRACKET(token_name)) | Échappe les crochets droit (]) dans la chaîne de remplacement du jeton. Remplace un crochet droit par deux crochets droits. |
| $(ESCAPE_NONE(token_name)) | Remplace le jeton sans échapper à des caractères dans la chaîne. Cette macro est fournie pour prendre en charge la compatibilité descendante dans les environnements où les chaînes de remplacement de jetons ne sont attendues que des utilisateurs approuvés. Pour plus d’informations, consultez « Mise à jour des étapes de travail pour utiliser des macros », plus loin dans cette rubrique. |
Mettre à jour les étapes du travail pour utiliser des macros
Le tableau suivant décrit comment le remplacement de jeton est géré par SQL Server Agent. Pour activer ou désactiver le remplacement du jeton d’alerte, cliquez avec le bouton droit sur SQL Server Agent dans l’Explorateur d’objets, sélectionnez Propriétés, puis, sur la page Système d'alerte, activez ou désactivez la case à cocher Remplacer les jetons pour toutes les réponses de travail aux alertes.
| Syntaxe du jeton | Remplacement du jeton d’alerte sur | Remplacement du jeton d’alerte désactivé |
|---|---|---|
| Macro ESCAPE utilisée | Tous les jetons des tâches sont correctement remplacés. | Les jetons activés par les alertes ne sont pas remplacés. Ces jetons sont A-DBN, A-SVR, A-ERR, A-SEV, A-MSG, et WMI(propriété). D’autres jetons statiques sont remplacés avec succès. |
| Aucune macro ESCAPE utilisée | Les travaux contenant des jetons échouent. | Les travaux contenant des jetons échouent. |
Exemples de mise à jour de la syntaxe du jeton
Vous trouverez ci-dessous des exemples de syntaxe de jeton pour illustrer l’utilisation de ces commandes.
A. Utiliser des jetons dans des chaînes non imbriquées
L’exemple suivant montre comment mettre à jour un script simple non imbriqué avec la macro d’échappement appropriée. Avant d’exécuter le script de mise à jour, le script d’étape de travail suivant utilise un jeton d’étape de travail pour imprimer le nom de la base de données appropriée :
PRINT N'Current database name is $(A-DBN)' ;
Après avoir exécuté le script de mise à jour, une macro ESCAPE_NONE est insérée avant le jeton A-DBN. Étant donné que les guillemets simples sont utilisés pour délimiter la chaîne d’impression, vous devez mettre à jour l’étape de travail en insérant la macro ESCAPE_SQUOTE comme suit :
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
B. Utiliser des jetons dans des chaînes imbriquées
Dans les scripts d’étape de travail où les jetons sont utilisés dans des chaînes ou instructions imbriquées, les instructions imbriquées doivent être réécrites en tant qu’instructions multiples avant d’insérer les macros d’échappement appropriées.
Par exemple, considérez l’étape de travail suivante, qui utilise le jeton A-MSG et n’a pas été mise à jour avec une macro d’échappement :
PRINT N'Print ''$(A-MSG)''' ;
Après avoir exécuté le script de mise à jour, une macro ESCAPE_NONE est insérée avec le jeton. Toutefois, dans ce cas, vous devrez réécrire le script sans utiliser l’imbrication comme suit et insérer la macro ESCAPE_SQUOTE pour placer correctement les délimiteurs d’échappement qui peuvent être passés dans la chaîne de remplacement du jeton :
DECLARE @msgString nvarchar(max);
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))';
SET @msgString = QUOTENAME(@msgString,'''');
PRINT N'Print ' + @msgString;
Note
Dans cet exemple, la fonction QUOTENAME définit le caractère de guillemet.
C. Utiliser des jetons avec la macro ESCAPE_NONE
L’exemple suivant fait partie d’un script qui récupère les job_id de la table sysjobs et utilise le jeton JOBID pour remplir la variable @JobID, déclarée précédemment dans le script comme type de données binaire.
Note
Étant donné qu’aucun délimiteur n’est requis pour les types de données binaires, la macro ESCAPE_NONE est utilisée avec le jeton JOBID. Vous n’avez pas besoin de mettre à jour cette étape de travail après avoir exécuté le script de mise à jour.
DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))
Cela affecte directement la valeur du jeton JOBID à @JobID, éliminant les requêtes de base de données inutiles et les conversions implicites, en répondant aux préoccupations soulevées dans la section C.