sp_add_jobstep (Transact-SQL)
Se aplica a: 
SQL Server Azure SQL Managed Instance
Agrega un paso (operación) a un trabajo de Agente SQL Server.
Convenciones de sintaxis de Transact-SQL
Importante
En Azure SQL Instancia administrada, la mayoría, pero no todos los tipos de trabajo Agente SQL Server se admiten. Consulte Diferencias entre T-SQL de Azure SQL Managed Instance y SQL Server para más información.
Sintaxis
sp_add_jobstep
[ [ @job_id = ] 'job_id' ]
[ , [ @job_name = ] N'job_name' ]
[ , [ @step_id = ] step_id ]
, [ @step_name = ] N'step_name'
[ , [ @subsystem = ] N'subsystem' ]
[ , [ @command = ] N'command' ]
[ , [ @additional_parameters = ] N'additional_parameters' ]
[ , [ @cmdexec_success_code = ] cmdexec_success_code ]
[ , [ @on_success_action = ] on_success_action ]
[ , [ @on_success_step_id = ] on_success_step_id ]
[ , [ @on_fail_action = ] on_fail_action ]
[ , [ @on_fail_step_id = ] on_fail_step_id ]
[ , [ @server = ] N'server' ]
[ , [ @database_name = ] N'database_name' ]
[ , [ @database_user_name = ] N'database_user_name' ]
[ , [ @retry_attempts = ] retry_attempts ]
[ , [ @retry_interval = ] retry_interval ]
[ , [ @os_run_priority = ] os_run_priority ]
[ , [ @output_file_name = ] N'output_file_name' ]
[ , [ @flags = ] flags ]
[ , [ @proxy_id = ] proxy_id ]
[ , [ @proxy_name = ] N'proxy_name' ]
[ , [ @step_uid = ] 'step_uid' OUTPUT ]
[ ; ]
Argumentos
[ @job_id = ] 'job_id'
Número de identificación del trabajo al que se agrega el paso. @job_id es uniqueidentifier, con un valor predeterminado de NULL.
Se deben especificar @job_id o @job_name , pero no se pueden especificar ambos.
[ @job_name = ] N'job_name'
El nombre del trabajo al que se agrega el paso. @job_name es sysname, con un valor predeterminado de NULL.
Se deben especificar @job_id o @job_name , pero no se pueden especificar ambos.
[ @step_id = ] step_id
Número de identificación de secuencia del paso del trabajo. @step_id es int, con un valor predeterminado de NULL. Los números de identificación de pasos comienzan en 1 e incrementan sin huecos. Si se inserta un paso en la secuencia existente, los números de secuencia se ajustan automáticamente. Se proporciona un valor si no se especifica @step_id .
[ @step_name = ] N'step_name'
Nombre del paso. @step_name es sysname, sin valor predeterminado.
[ @subsystem = ] N'subsystem'
Subsistema utilizado por el servicio Agente SQL Server para ejecutar @command. @subsystem es nvarchar(40) y puede ser uno de estos valores.
| Valor | Descripción |
|---|---|
ActiveScripting |
Script Active Importante: esta característica se quitará en una versión futura de SQL Server. Evite utilizar esta característica en nuevos trabajos de desarrollo y tenga previsto modificar las aplicaciones que actualmente la utilizan. |
CmdExec |
Comando del sistema operativo o programa ejecutable |
Distribution |
Trabajo del Agente de distribución de replicación |
Snapshot |
Trabajo del Agente de instantáneas de replicación |
LogReader |
Trabajo del Agente de registro del LOG de replicación |
Merge |
Trabajo del Agente de mezcla de replicación |
QueueReader |
Trabajo del Agente de lectura de cola de replicación |
ANALYSISQUERY |
Consulta de Analysis Services (MDX, DMX) |
ANALYSISCOMMAND |
Comando de Analysis Services (XMLA) |
SSIS |
Ejecución de paquetes de Integration Services |
PowerShell |
Script de PowerShell |
TSQL (valor predeterminado) |
Instrucción Transact-SQL |
[ @command = ] N'command'
Los comandos que ejecutará el servicio Agente SQL Server a través de @subsystem. @command es nvarchar(max), con un valor predeterminado de NULL. Agente SQL Server proporciona sustitución de tokens, lo que proporciona la misma flexibilidad que proporcionan las variables al escribir programas de software.
Una macro de escape debe acompañar a todos los tokens usados en los pasos del trabajo o, de lo contrario, se producirá un error en esos pasos de trabajo. Además, ahora debe escribir los nombres de los tokens entre paréntesis y colocar un signo de dólar ($) al principio de la sintaxis del token. Por ejemplo: $(ESCAPE_<macro name>(DATE)).
Para obtener más información sobre estos tokens y actualizar los pasos del trabajo para usar la nueva sintaxis de token, consulte Uso de tokens en pasos de trabajo.
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-MSGy WMI(<property>). 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 .
[ @additional_parameters = ] N'additional_parameters'
Solamente se identifica con fines informativos. No compatible. La compatibilidad con versiones posteriores no está garantizada.
[ @cmdexec_success_code = ] cmdexec_success_code
Valor devuelto por un CmdExec comando de subsistema para indicar que @command se ejecutó correctamente. @cmdexec_success_code es int, con un valor predeterminado de 0.
[ @on_success_action = ] on_success_action
Acción que se realiza si el paso termina correctamente. @on_success_action es tinyint y puede ser uno de estos valores.
| Valor | Descripción (acción) |
|---|---|
1 (valor predeterminado) |
Salir con éxito |
2 |
Salir con error |
3 |
Ir al paso siguiente |
4 |
Vaya al paso @on_success_step_id |
[ @on_success_step_id = ] on_success_step_id
Identificador del paso de este trabajo que se va a ejecutar si el paso se realiza correctamente y @on_success_action es 4. @on_success_step_id es int, con un valor predeterminado de 0.
[ @on_fail_action = ] on_fail_action
Acción que se va a realizar si se produce un error en el paso. @on_fail_action es tinyint y puede ser uno de estos valores.
| Valor | Descripción (acción) |
|---|---|
1 |
Salir con éxito |
2 (valor predeterminado) |
Salir con error |
3 |
Ir al paso siguiente |
4 |
Vaya al paso @on_fail_step_id |
[ @on_fail_step_id = ] on_fail_step_id
Identificador del paso de este trabajo que se va a ejecutar si se produce un error en el paso y @on_fail_action es 4. @on_fail_step_id es int, con un valor predeterminado de 0.
[ @server = ] N'server'
Solamente se identifica con fines informativos. No compatible. La compatibilidad con versiones posteriores no está garantizada.
[ @database_name = ] N'database_name'
Nombre de la base de datos en la que se va a ejecutar un paso de Transact-SQL. @database_name es sysname, con un valor predeterminado de NULL, en cuyo caso se usa la master base de datos. No se permiten nombres entre corchetes ([]). Para un paso de trabajo de ActiveX, el @database_name es el nombre del lenguaje de scripting que usa el paso.
[ @database_user_name = ] N'database_user_name'
Nombre de la cuenta de usuario que se va a usar al ejecutar un paso de Transact-SQL. @database_user_name es sysname, con un valor predeterminado de NULL. Cuando @database_user_name es NULL, el paso se ejecuta en el contexto de usuario del propietario del trabajo en @database_name. Agente SQL Server incluye este parámetro solo si el propietario del trabajo es sysadmin de SQL Server. Si es así, el paso transact-SQL especificado se ejecuta en el contexto del nombre de usuario de SQL Server especificado. Si el propietario del trabajo no es un administrador del sistema de SQL Server, el paso transact-SQL siempre se ejecuta en el contexto del inicio de sesión que posee este trabajo y se omite el parámetro @database_user_name .
[ @retry_attempts = ] retry_attempts
Número de reintentos en caso de que el paso dé error. @retry_attempts es int, con un valor predeterminado de 0, que indica que no hay reintentos.
[ @retry_interval = ] retry_interval
Tiempo en minutos entre reintentos. @retry_interval es int, con un valor predeterminado de 0, que indica un 0intervalo de -minute.
[ @os_run_priority = ] os_run_priority
Solamente se identifica con fines informativos. No compatible. La compatibilidad con versiones posteriores no está garantizada.
[ @output_file_name = ] N'output_file_name'
Nombre del archivo en el que se guarda el resultado de este paso. @output_file_name es nvarchar(200), con un valor predeterminado de NULL. @output_file_name puede incluir uno o varios de los tokens enumerados en @command. Este parámetro solo es válido con comandos que se ejecutan en los subsistemas Transact-SQL, CmdExec, PowerShell, Integration Services o Analysis Services.
[ @flags = ] marcas
Una opción que controla el comportamiento. @flags es int y puede ser uno de estos valores.
| Valor | Descripción |
|---|---|
0 (valor predeterminado) |
Sobrescribir el archivo de salida |
2 |
Anexar al archivo de salida |
4 |
Escribir la salida del paso de trabajo Transact-SQL en el historial de pasos |
8 |
Escribir el registro en la tabla (sobrescribir el historial existente) |
16 |
Escribir el registro en la tabla (anexar al historial existente) |
32 |
Escribir todo el resultado en el historial de trabajos |
64 |
Crear un evento de Windows para usarlo como señal para que el paso de cmd trabajo anule |
[ @proxy_id = ] proxy_id
Número de identificación del proxy con el que se ejecuta el paso de trabajo. @proxy_id es int, con un valor predeterminado de NULL. Si no se especifica ningún @proxy_id, no se especifica ningún @proxy_name y no se especifica ningún @database_user_name, el paso de trabajo se ejecuta como la cuenta de servicio de Agente SQL Server.
[ @proxy_name = ] N'proxy_name'
Nombre del proxy con el que se ejecuta el paso de trabajo. @proxy_name es sysname, con un valor predeterminado de NULL. Si no se especifica ningún @proxy_id, no se especifica ningún @proxy_name y no se especifica ningún @database_user_name, el paso de trabajo se ejecuta como la cuenta de servicio de Agente SQL Server.
[ @step_uid = ] SALIDA 'step_uid'
@step_uid es un parámetro OUTPUT de tipo uniqueidentifier.
Valores de código de retorno
0 (correcto) o 1 (erróneo).
Conjunto de resultados
Ninguno.
Comentarios
sp_add_jobstep debe ejecutarse desde la msdb base de datos.
SQL Server Management Studio ofrece un método gráfico sencillo para administrar trabajos y es el método recomendado para crear y administrar la infraestructura de trabajo.
De forma predeterminada, un paso de trabajo se ejecuta como la cuenta de servicio de Agente SQL Server a menos que se especifique otro proxy. Un requisito de esta cuenta es ser miembro del rol fijo de seguridad sysadmin .
Un proxy puede identificarse mediante @proxy_name o @proxy_id.
Este procedimiento almacenado comparte el nombre de sp_add_jobstep con un objeto similar para el servicio Trabajos elásticos de Azure para Azure SQL Database. Para obtener información sobre la versión de trabajos elásticos, consulte jobs.sp_add_jobstep (Trabajos elásticos de Azure).
Permisos
Puede conceder EXECUTE permisos en este procedimiento, pero estos permisos se pueden invalidar durante una actualización de SQL Server.
A otros usuarios se les debe conceder uno de los siguientes Agente SQL Server roles fijos de base de datos en la msdb base de datos:
- SQLAgentUserRole
- SQLAgentReaderRole
- SQLAgentOperatorRole
Para detalles sobre los permisos de estos roles, consulte Roles fijos de base de datos del Agente SQL Server.
El creador del paso de trabajo debe tener acceso al proxy para el paso de trabajo. Los miembros del rol fijo de servidor sysadmin tienen acceso a todos los servidores proxy. Se debe conceder acceso al proxy de forma explícita al resto de los usuarios.
Ejemplos
En este ejemplo se crea un paso de trabajo que cambia el acceso a la base de datos de modo que sea de solo lectura para la base de datos Sales. Además, en este ejemplo se especifican cinco reintentos, con cada reintento que se va a producir después de una espera de 5 minutos.
Nota:
En este ejemplo se supone que el Weekly Sales Data Backup trabajo ya existe.
USE msdb;
GO
EXEC sp_add_jobstep
@job_name = N'Weekly Sales Data Backup',
@step_name = N'Set database to read only',
@subsystem = N'TSQL',
@command = N'ALTER DATABASE SALES SET READ_ONLY',
@retry_attempts = 5,
@retry_interval = 5;
GO