Utiliser des jetons dans les étapes d'un travail
S’applique à : 
SQL Server Azure SQL Managed Instance
Important
Dans Azure SQL Managed Instance, la plupart, mais pas toutes les fonctionnalités SQL Server Agent sont actuellement prises en charge. Pour plus d’informations, consultez Différences T-SQL entre Azure SQL Managed Instance et SQL Server.
SQL Server Agent vous permet d’utiliser des jetons dans des scripts d’étape de travail Transact-SQL . Ces jetons avec lesquels vous rédigez des étapes de travail vous offrent la même flexibilité que les variables lors de l'écriture de programmes logiciels. Après avoir inséré un jeton dans un script d'étape de travail, SQL Server Agent le remplace au moment de l'exécution avant que le sous-système Transact-SQL n'exécute l'étape de travail.
Comprendre l’utilisation des jetons
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-MSGet 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 .
SQL Server Agent : Le remplacement du jeton est simple et efficace, SQL Server Agent remplace le jeton par une valeur de chaîne littérale exacte. Tous les jetons respectent la casse. Vous devez tenir compte de ce changement dans vos étapes de travail et nommer correctement les jetons utilisés, ou bien convertir la chaîne de remplacement en type de données correct.
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 interprète comme des caractères d'échappement tous les guillemets simples transmis par inadvertance à la chaîne de remplacement des jetons. SQL Server Agent remplace un guillemet simple par deux guillemets simples dans la chaîne finale.
Par exemple, si la chaîne transmise en vue de remplacer le jeton est AdventureWorks2022'SELECT @@VERSION --, la commande exécutée par l'étape de travail SQL Server Agent sera la suivante :
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. À la place, le guillemet simple supplémentaire incite le serveur à analyser l'instruction insérée en tant que chaîne. Si la chaîne de remplacement de jetons ne contient aucun guillemet simple, aucun caractère n’est interprété comme caractère d’échappement et l’étape de tâche contenant le jeton s’exécute comme prévu.
Pour déboguer l'usage de jetons dans vos étapes de travail, utilisez des instructions d'impression, telles que PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' , et enregistrez la sortie des étapes de travail dans un fichier ou une table. Ouvrez la page Avancé de la boîte de dialogue Propriétés de l’étape du travail pour spécifier une table ou un fichier de sortie pour les étapes de travail.
Jetons et macros de SQL Server Agent
Les tableaux suivants répertorient et décrivent les jetons et les macros pris en charge par SQL Server Agent.
Jetons de SQL Server Agent
| par jeton | Description |
|---|---|
| (A-DBN) | Nom de la base de données. Si le travail est exécuté par une alerte, la valeur du nom de la base de données remplace automatiquement ce jeton dans l'étape de travail. |
| (A-SVR) | Nom du serveur. Si le travail est exécuté par une alerte, la valeur du nom du serveur remplace automatiquement ce jeton dans l'étape de travail. |
| (A-ERR) | Numéro d’erreur. Si le travail est exécuté par une alerte, la valeur du numéro d'erreur remplace automatiquement ce jeton dans l'étape de travail. |
| (A-SEV) | Gravité de l'erreur Si le travail est exécuté par une alerte, la valeur de la gravité de l'erreur remplace automatiquement ce jeton dans l'étape de travail. |
| (A-MSG) | Texte du message. Si le travail est exécuté par une alerte, la valeur du texte du message remplace automatiquement ce jeton dans l'étape de travail. |
| (JOBNAME) | Nom du travail. Ce jeton est disponible uniquement sur SQL Server 2016 et ultérieur. |
| (STEPNAME) | Nom de l'étape. Ce jeton est disponible uniquement sur SQL Server 2016 et ultérieur. |
| (DATE) | Date actuelle (au format AAAAMMJJ). |
| (INST) | Nom de l’instance. Pour une instance par défaut, ce jeton aura le nom de l’instance par défaut : MSSQLSERVER. |
| (JOBID) | ID de travail. |
| (MACH) | Nom de l’ordinateur. |
| (MSSA) | Nom du service SQLServerAgent principal. |
| (OSCMD) | Préfixe du programme utilisé pour exécuter les étapes de travail CmdExec . |
| (SQLDIR) | Répertoire d'installation de SQL Server . La valeur par défaut est : C:\Program Files\Microsoft SQL Server\MSSQL. |
| (SQLLOGDIR) | Jeton de remplacement pour le chemin du dossier des fichiers journaux des erreurs SQL Server, par exemple, $(ESCAPE_SQUOTE(SQLLOGDIR)). Ce jeton est disponible uniquement sur SQL Server 2014 et ultérieur. |
| (STEPCT) | Nombre de fois où cette étape a été exécutée (ne tient pas compte des nouvelles tentatives). Peut être utilisé par la commande d'étape pour forcer l'arrêt d'une boucle multi-étape. |
| (STEPID) | Numéro d'identification de l'étape. |
| (SRVR) | Nom de l'ordinateur sur lequel SQL Serverest exécuté. Si l'instance SQL Server est une instance nommée, le nom de l'instance est compris. |
| (TIME) | Heure actuelle (au format HHMMSS). |
| (STRTTM) | Heure (au format HHMMSS) à laquelle l'exécution du travail a débuté. |
| (STRTDT) | Date (au format AAAAMMJJ) à laquelle l'exécution du travail a débuté. |
| (WMI(propriété)) | Pour les travaux qui s’exécutent en réponse à des alertes WMI, la valeur de la propriété est 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 entraîné l’exécution de l’alerte. |
Macros d'échappement de SQL Server Agent
| Macros d'échappement | Description |
|---|---|
| $(ESCAPE_SQUOTE(nom_jeton)) | Interprète les guillemets simples (') comme caractères d'échappement dans la chaîne de remplacement des jetons. Remplace un guillemet simple par un guillemet double. |
| $(ESCAPE_DQUOTE(nom_jeton)) | Interprète les guillemets doubles (") comme caractères d'échappement dans la chaîne de remplacement des jetons. Remplace un guillemet double par deux guillemets doubles. |
| $(ESCAPE_RBRACKET(nom_jeton)) | Interprète les crochets droits (]) comme caractères d'échappement dans la chaîne de remplacement des jetons. Remplace un crochet droit par deux crochets droits. |
| $(ESCAPE_NONE(nom_jeton)) | Remplace le jeton sans interpréter de caractères comme caractères d'échappement dans la chaîne. La macro est fournie pour des raisons de prise en charge de la compatibilité descendante dans des environnements où l'usage de chaînes de remplacement de jetons est généralement réservé à des utilisateurs approuvés. Pour plus d'informations, consultez la section « Mise à jour des étapes de travail pour l'utilisation de macros » plus loin dans cette rubrique. |
Mettre à jour les étapes de la tâche pour utiliser des macros
La table suivante décrit comment le remplacement des jetons est contrôlé par SQL Server Agent. Pour activer/désactiver le remplacement des 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 , cochez ou décochez la case Remplacer les jetons pour toutes les réponses de travaux aux alertes .
| Syntaxe des jetons | Remplacement de jetons d'alerte activé | Remplacement de jetons d'alerte désactivé |
|---|---|---|
| Macro ESCAPE utilisée | Tous les jetons des travaux sont remplacés avec succès. | Les jetons activés par des alertes ne sont pas remplacés. Ces jetons sont A-DBN, A-SVR, A-ERR, A-SEV, A-MSGet WMI(propriété) . Les autres jetons statiques sont remplacés comme il se doit. |
| Aucune macro ESCAPE utilisée | Échec de tous les travaux contenant des jetons. | Échec de tous les travaux contenant des jetons. |
Exemples de mise à jour de syntaxe de jeton
Vous trouverez ci-dessous des exemples de syntaxe de jeton pour illustrer l’utilisation de ces commandes.
A. Utilisation de jetons dans des chaînes non imbriquées
L'exemple suivant explique comment mettre à jour un script non imbriqué simple 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 base de données correct :
PRINT N'Current database name is $(A-DBN)' ;
Après l'exécution du script de mise à jour, une ESCAPE_NONE macro est insérée avant le jeton A-DBN . Du fait 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. Utilisation de 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 des instructions imbriquées, les instructions imbriquées doivent être réécrites sous forme de plusieurs instructions avant d'insérer les macros d'échappement appropriées.
Par exemple, considérez l’étape de tâche 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 l'exécution du script de mise à jour, une macro ESCAPE_NONE est insérée avec le jeton. Néanmoins, dans ce cas, il vous faudrait réécrire le script sans avoir recours à l'imbrication comme illustré ci-après, puis insérer la macro ESCAPE_SQUOTE pour interpréter correctement en tant que caractères d'échappement les délimiteurs susceptibles d'être transmis à la chaîne de remplacement des jetons :
DECLARE @msgString nvarchar(max);
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))';
SET @msgString = QUOTENAME(@msgString,'''');
PRINT N'Print ' + @msgString;
Remarque
Notez également dans cet exemple que la fonction QUOTENAME définit le guillemet.
C. Utilisation de jetons avec la macro ESCAPE_NONE
L’exemple suivant s’inscrit dans un script chargé d’extraire le job_id dans la table sysjobs et utilise le jeton JOBID pour remplir la variable @JobID déclarée plus tôt dans le script en tant que type de données binaire.
Remarque
Notez que, du fait qu’aucun délimiteur n’est requis pour les types de données binaires, la macro ESCAPE_NONE est utilisée dans le jeton JOBID. Vous n’avez pas besoin de mettre ce travail à jour après avoir exécuté le script de mise à niveau.
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.