Usar tokens en pasos de trabajo
Se aplica a: 
SQL Server Azure SQL Managed Instance
Importante
En Azure SQL Managed Instance, actualmente son compatibles la mayoría de las características del Agente SQL Server. Consulte Diferencias entre T-SQL de Azure SQL Managed Instance y SQL Server para más información.
El Agente SQL Server le permite usar tokens en scripts de pasos de trabajo de Transact-SQL. La utilización de tokens al escribir pasos de trabajo ofrece la misma flexibilidad que las variables al escribir programas de software. Una vez que se inserta un token en un script de pasos de trabajo, el Agente SQL Server reemplaza el token en tiempo de ejecución, antes de que el subsistema de Transact-SQL ejecute el paso de trabajo.
Descripción del uso de tokens
Importante
Todos los usuarios de Windows que tengan permisos de escritura en el Registro de eventos de Windows pueden tener acceso a los pasos de trabajo activados por alertas del Agente SQL Server o de WMI. Para evitar este riesgo de seguridad, se deshabilitan de manera predeterminada los tokens del Agente SQL Server que pueden utilizarse en trabajos activados por alertas. Estos tokens son: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG y WMI(propiedad). En esta versión el uso de los tokens se ha ampliado a todas las alertas.
Si necesita usar estos tokens, asegúrese primero de que solo los miembros de los grupos de seguridad de Windows de confianza, como el grupo Administradores, tienen permisos de escritura en el registro de eventos del equipo donde reside SQL Server . A continuación, para habilitar estos tokens, haga clic con el botón derecho en Agente SQL Server en el Explorador de objetos, elija Propiedadesy, en la página Sistema de alerta , active la casilla Reemplazar tokens para todas las respuestas de trabajos a alertas .
SQL Server La sustitución del token del Agente es sencilla y eficaz: el Agente SQL Server reemplaza el token por un valor literal de cadena exacto. Todos los tokens distinguen mayúsculas de minúsculas. Los pasos de trabajo deben tenerlo en cuenta y citar correctamente los tokens utilizados o convertir la cadena de reemplazo al tipo de datos correcto.
Por ejemplo, se puede usar la siguiente instrucción para imprimir el nombre de la base de datos en un paso de trabajo:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
En este ejemplo, la macro ESCAPE_SQUOTE se inserta con el token A-DBN . En tiempo de ejecución, el nombre de la base de datos apropiada sustituye al token A-DBN. La macro de escape convierte cualquier comilla simple que se pueda pasar de forma inadvertida en la cadena de reemplazo del token. El Agente SQL Server reemplaza una comilla simple por dos comillas simples en la cadena final.
Por ejemplo, si la cadena que se pasa para reemplazar al token es AdventureWorks2022'SELECT @@VERSION --, el comando que ejecuta el paso de trabajo del Agente SQL Server será:
PRINT N'Current database name is AdventureWorks2022''SELECT @@VERSION --' ;
En este caso, la instrucción insertada, SELECT @@VERSION, no se ejecuta. En su lugar, la comilla simple adicional hace que el servidor analice la instrucción insertada como una cadena. Si la cadena de reemplazo del token no contiene una comilla simple, no se convierte ninguno de los caracteres y el paso de trabajo que contiene el token se ejecutará como se espera.
Para depurar el uso de tokens en pasos de trabajo, utilice instrucciones de impresión como, por ejemplo, PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' y guarde la salida del paso de trabajo en un archivo o una tabla. Use la página Avanzadas del cuadro de diálogo Propiedades de paso de trabajo para especificar un archivo o tabla de salida del paso de trabajo.
Tokens y macros del Agente SQL Server
En las siguientes tablas se indican y describen los tokens y macros compatibles con el Agente SQL Server .
Tokens del Agente SQL Server
| Token | Descripción |
|---|---|
| (A-DBN) | nombre de base de datos. Si el trabajo se ejecuta a causa de una alerta, el valor del nombre de la base de datos sustituye automáticamente a este token en el paso de trabajo. |
| (A-SVR) | Nombre de servidor. Si el trabajo se ejecuta a causa de una alerta, el valor del nombre del servidor sustituye automáticamente a este token en el paso de trabajo. |
| (A-ERR) | Número de error. Si el trabajo se ejecuta a causa de una alerta, el valor del número de error sustituye automáticamente a este token en el paso de trabajo. |
| (A-SEV) | Gravedad del error. Si el trabajo se ejecuta a causa de una alerta, el valor de la gravedad del error sustituye automáticamente a este token en el paso de trabajo. |
| (A-MSG) | Texto del mensaje. Si el trabajo se ejecuta a causa de una alerta, el valor del texto del mensaje sustituye automáticamente a este token en el paso de trabajo. |
| (JOBNAME) | Nombre del trabajo. Este token solo está disponible en SQL Server 2016 y versiones posteriores. |
| (STEPNAME) | Nombre del paso. Este token solo está disponible en SQL Server 2016 y versiones posteriores. |
| (DATE) | Fecha actual (en formato AAAAMMDD). |
| (INST) | Nombre de instancia. Para una instancia predeterminada, este token tiene el nombre de instancia predeterminado: MSSQLSERVER. |
| (JOBID) | Id. del trabajo. |
| (MACH) | Nombre del equipo. |
| (MSSA) | Nombre del servicio SQLServerAgent maestro. |
| (OSCMD) | Prefijo del programa usado para ejecutar los pasos de trabajo de CmdExec . |
| (SQLDIR) | Directorio en el que se instala SQL Server . El directorio predeterminado es C:\Archivos de programa\Microsoft SQL Server\MSSQL. |
| (SQLLOGDIR) | Token de reemplazo para la ruta de la carpeta de registro de errores de SQL Server; por ejemplo, $(ESCAPE_SQUOTE(SQLLOGDIR)). Este token solo está disponible en SQL Server 2014 y versiones posteriores. |
| (STEPCT) | Contador del número de veces que se ha ejecutado este paso (sin incluir los reintentos). Lo puede utilizar el comando del paso para forzar la terminación de un bucle de múltiples pasos. |
| (STEPID) | Id. del paso. |
| (SRVR) | Nombre del equipo en el que se ejecuta SQL Server. Si la instancia de SQL Server es una instancia con nombre, incluye el nombre. |
| (TIME) | Hora actual (en formato HHMMSS). |
| (STRTTM) | La hora (en formato HHMMSS) en la que el trabajo empezó a ejecutarse. |
| (STRTDT) | La fecha (en formato AAAAMMDD) en la que el trabajo empezó a ejecutarse. |
| (WMI(propiedad)) | Para los trabajos que se ejecutan en respuesta a las alertas de WMI, es el valor de la propiedad especificada por property. Por ejemplo, $(WMI(DatabaseName)) proporciona el valor de la propiedad DatabaseName del evento WMI que provocó la ejecución de la alerta. |
Macros de escape del Agente SQL Server
| Macros de escape | Descripción |
|---|---|
| $(ESCAPE_SQUOTE(nombre_token)) | Convierte las comillas simples (') en la cadena de reemplazo del token. Sustituye una comilla simple por dos comillas simples. |
| $(ESCAPE_DQUOTE(nombre_token)) | Convierte las comillas dobles ('') en la cadena de reemplazo del token. Sustituye una comilla doble por dos comillas dobles. |
| $(ESCAPE_RBRACKET(nombre_token)) | Convierte los corchetes de cierre (]) en la cadena de reemplazo del token. Sustituye un corchete de cierre por dos corchetes de cierre. |
| $(ESCAPE_NONE(nombre_token)) | Sustituye el token sin convertir ninguno de los caracteres de la cadena. Se incluye esta macro para la compatibilidad con versiones anteriores en entornos donde las cadenas de reemplazo de tokens se esperan únicamente de usuarios de confianza. Para obtener más información, vea "Actualizar pasos de trabajo para usar macros" más adelante en este tema. |
Actualizar pasos de trabajo para usar macros
La tabla siguiente describe cómo el Agente SQL Server administra el reemplazo de los tokens. Para habilitar o deshabilitar la alerta de sustitución de los tokens, haga clic con el botón derecho en Agente SQL Server en el Explorador de objetos, seleccione Propiedadesy, en la página Sistema de alerta , active o desactive la casilla Reemplazar tokens para todas las respuestas de trabajos a alertas .
| Sintaxis de los tokens | Alerta de sustitución de tokens activada | Alerta de sustitución de tokens desactivada |
|---|---|---|
| Macro ESCAPE utilizada | Todos los tokens de los trabajos se han sustituido correctamente. | Los tokens activados por alertas no se sustituyen. Estos tokens son: A-DBN, A-SVR, A-ERR, A-SEV, A-MSGy WMI(propiedad) . Otros tokens estáticos se han sustituido correctamente. |
| Macro ESCAPE no utilizada | Los trabajos que contienen tokens producen un error. | Los trabajos que contienen tokens producen un error. |
Ejemplos de actualización de la sintaxis del token
A continuación se muestran ejemplos de sintaxis de tokens para ayudar a ilustrar cómo usar estos comandos.
A. Usar tokens en cadenas no anidadas
En el siguiente ejemplo se muestra cómo actualizar un script simple no anidado con la macro de escape apropiada. Antes de ejecutar el script de actualización, el siguiente script de paso de trabajo usa un token de paso de trabajo para imprimir el nombre de la base de datos apropiada:
PRINT N'Current database name is $(A-DBN)' ;
Después de ejecutar el script de actualización, se inserta una macro ESCAPE_NONE antes del token A-DBN . Debido a que se utilizan comillas simples para delimitar la cadena de impresión, se debe actualizar el paso de trabajo mediante la inserción de la macro ESCAPE_SQUOTE , del siguiente modo:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
B. Usar tokens en cadenas anidadas
En scripts de pasos de trabajo donde se utilizan tokens en cadenas o instrucciones anidadas, éstas deben volver a escribirse como varias instrucciones antes de insertarse en las macros de escape apropiadas.
Por ejemplo, considere el siguiente paso de trabajo, que utiliza el token A-MSG y no se ha actualizado con una macro de escape:
PRINT N'Print ''$(A-MSG)''' ;
Después de ejecutar el script de actualización, se inserta una macro ESCAPE_NONE con el token. No obstante, en este caso, se debería volver a escribir el script sin usar anidamiento e insertar la macro ESCAPE_SQUOTE para convertir los delimitadores que se puedan haber pasado en la cadena de reemplazo del token:
DECLARE @msgString nvarchar(max);
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))';
SET @msgString = QUOTENAME(@msgString,'''');
PRINT N'Print ' + @msgString;
Nota:
En este ejemplo la función QUOTENAME establece el carácter de comillas.
C. Usar tokens con la macro ESCAPE_NONE
El siguiente ejemplo es parte de un script que recupera el job_id de la tabla sysjobs y utiliza el token JOBID para rellenar la variable @JobID, que se declaró previamente en el script como un tipo de datos binario.
Nota:
Debido a que no se requieren delimitadores para los tipos de datos binarios, la macro ESCAPE_NONE se usa con el token JOBID. Una vez que se ejecute el script de actualización, no debería ser necesario actualizar este paso de trabajo.
DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))
Esto asigna directamente el valor del token JOBID a @JobID, lo que elimina las consultas de base de datos innecesarias y las conversiones implícitas, abordando las preocupaciones planteadas en la sección C.