Notes
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
s’applique à :
SQL ServerAzure SQL Managed Instance
Importante
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 ou Limitations des travaux SQL Agent dans SQL Managed instance.
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 des jetons
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 les suivants : A-DBN, , A-SVRA-ERR, A-SEV, A-MSG, et WMI(<property>). Dans cette version, l’utilisation de jetons est étendue à toutes les alertes.
Importante
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 ESCAPE_SQUOTE macro est insérée avec le A-DBN jeton. Au moment de l’exécution, le A-DBN jeton 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 qui pourraient être transmis par inadvertance à la chaîne de remplacement des jetons. 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 de travail de 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 jetons ne contient aucun guillemet simple, aucun caractère n'est interprété comme caractère d'échappement et l'étape de travail 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.
Jetons et macros de SQL Server Agent
Les tableaux suivants répertorient et décrivent les jetons et macros pris en charge par SQL Server Agent.
Jetons de SQL Server Agent
| Jeton | Descriptif |
|---|---|
(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 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 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 yyyyMMdd format). |
(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 SQL Server Agent. |
(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 définie sur C:\Program Files\Microsoft SQL Server\MSSQL. |
(SQLLOGDIR) |
Jeton de remplacement pour le chemin du dossier de journal des erreurs SQL Server, par exemple $(ESCAPE_SQUOTE(SQLLOGDIR)). S’applique à : SQL Server 2014 (12.x) et ultérieur. |
(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) |
Numéro d'identification de l'é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 HHmmss format). |
(STRTTM) |
Heure (au HHmmss format) pendant laquelle le travail a commencé à s’exécuter. |
(STRTDT) |
Date (au yyyyMMdd format) pendant laquelle le travail a commencé à s’exécuter. |
(WMI(<property>)) |
Pour les travaux qui s’exécutent en réponse à des alertes WMI, la valeur de la propriété est spécifiée par <property>. Par exemple, $(WMI(DatabaseName)) fournit la valeur de la DatabaseName propriété pour l’événement WMI qui a provoqué l’exécution de l’alerte. |
Les macros d'échappement de l'Agent SQL Server
| Macros d'échappement | Descriptif |
|---|---|
$(ESCAPE_SQUOTE(<token_name>)) |
Interprète les guillemets simples (') comme caractères d'échappement dans la chaîne de remplacement des jetons. Remplace un guillemet simple par deux guillemets simples. |
$(ESCAPE_DQUOTE(<token_name>)) |
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(<token_name>)) |
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(<token_name>)) |
Remplace le jeton sans interpréter de caractères comme caractères d'échappement 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 la section suivante, Mettre à jour les étapes du travail pour utiliser des macros. |
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 de jetons d'alerte activé | Remplacement de jetons d'alerte désactivé |
|---|---|---|
ESCAPE macro utilisée |
Tous les jetons des travaux sont remplacés avec succè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(<property>). 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 syntaxe de jeton
Voici des exemples de syntaxe de jeton pour vous aider à illustrer l’utilisation de ces commandes.
A. Utilisez des jetons dans des chaînes non imbriquées
L’exemple suivant montre comment mettre à jour un script non imbriqué de base 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, imaginez 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. 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 qui pourraient être transmis à la chaîne de remplacement des jetons :
DECLARE @msgString AS NVARCHAR (MAX);
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))';
SET @msgString = QUOTENAME(@msgString, '''');
PRINT N'Print ' + @msgString;
Dans cet exemple, la QUOTENAME fonction définit le caractère de guillemet.
Chapitre C. Utiliser des jetons avec la macro ESCAPE_NONE
L’exemple suivant fait partie d’un script qui récupère l’job_id à partir de la table sysjobs et utilise le JOBID jeton pour remplir la @JobID variable, qui a été déclarée précédemment dans le script en tant que type de données binaire.
Remarque
Étant donné qu’aucun délimiteur n’est requis pour les types de données binaires, la ESCAPE_NONE macro est utilisée avec le JOBID jeton. 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 JOBID jeton à @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.