Usar tokens en pasos de trabajo

Se aplica a:SQL ServerAzure SQL Managed Instance

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

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

Macros de escape del Agente SQL Server

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 .

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;

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.

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.

Consulte también

• Implementar trabajos
• Administrar pasos de trabajo