sp_add_jobstep (Transact-SQL)

Se aplica a:SQL ServerAzure SQL Managed Instance

Agrega un paso (operación) a un trabajo de Agente SQL Server.

Convenciones de sintaxis de Transact-SQL

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.

[ @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.

[ @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.

[ @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.

[ @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) (Transact-SQL).

Permisos

Este procedimiento almacenado es propiedad del rol db_owner . Puede conceder EXECUTE permisos para cualquier usuario, 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.

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

Contenido relacionado

• Ver o modificar trabajos
• sp_add_job (Transact-SQL)
• sp_add_schedule (Transact-SQL)
• sp_delete_jobstep (Transact-SQL)
• sp_help_job (Transact-SQL)
• sp_help_jobstep (Transact-SQL)
• sp_update_jobstep (Transact-SQL)
• Procedimientos almacenados del sistema (Transact-SQL)