Compartir a través de

jobs.sp_add_jobstep (trabajos elásticos de Azure) (Transact-SQL)

  • Artículo

Se aplica a: Azure SQL Database

Agrega un paso a un trabajo existente en el servicio Trabajos elásticos de Azure para Azure SQL Database. Use jobs.sp_update_jobstep para modificar los pasos existentes del trabajo elástico.

Este procedimiento almacenado comparte el nombre de sp_add_jobstep con un objeto similar en SQL Server para el servicio Agente SQL Server. Para obtener información sobre la versión de Agente SQL Server, consulte sp_add_jobstep.

Convenciones de sintaxis de Transact-SQL

Sintaxis

[jobs].sp_add_jobstep [ @job_name = ] 'job_name'
     [ , [ @step_id = ] step_id ]
     [ , [ @step_name = ] step_name ]
     [ , [ @command_type = ] 'command_type' ]
     [ , [ @command_source = ] 'command_source' ]
     , [ @command = ] 'command'
     [ , [ @credential_name = ] 'credential_name' ]
     , [ @target_group_name = ] 'target_group_name'
     [ , [ @initial_retry_interval_seconds = ] initial_retry_interval_seconds ]
     [ , [ @maximum_retry_interval_seconds = ] maximum_retry_interval_seconds ]
     [ , [ @retry_interval_backoff_multiplier = ] retry_interval_backoff_multiplier ]
     [ , [ @retry_attempts = ] retry_attempts ]
     [ , [ @step_timeout_seconds = ] step_timeout_seconds ]
     [ , [ @output_type = ] 'output_type' ]
     [ , [ @output_credential_name = ] 'output_credential_name' ]
     [ , [ @output_subscription_id = ] 'output_subscription_id' ]
     [ , [ @output_resource_group_name = ] 'output_resource_group_name' ]
     [ , [ @output_server_name = ] 'output_server_name' ]
     [ , [ @output_database_name = ] 'output_database_name' ]
     [ , [ @output_schema_name = ] 'output_schema_name' ]
     [ , [ @output_table_name = ] 'output_table_name' ]
     [ , [ @job_version = ] job_version OUTPUT ]
     [ , [ @max_parallelism = ] max_parallelism ]

Argumentos

@job_name

El nombre del trabajo al que se agrega el paso. job_name es nvarchar(128).

@step_id

Número de identificación de secuencia del paso del trabajo. Los números de identificación de pasos se inician en 1 e incrementan sin interrupciones. Si un paso existente ya tiene este identificador, ese paso y todos los pasos siguientes tendrán sus identificadores incrementados para que este nuevo paso se pueda insertar en la secuencia. Si no se especifica, el step_id se asignará automáticamente al último de la secuencia de pasos. step_id es un valor int.

@step_name

Nombre del paso. Debe especificarse, excepto para el primer paso de un trabajo que (por comodidad) tiene un nombre predeterminado de JobStep. step_name es nvarchar(128).

@command_type

Tipo de comando ejecutado por este paso de trabajo. command_type es nvarchar(50), con un valor predeterminado de TSql, lo que significa que el valor del parámetro @command_type es un script T-SQL.

Si se especifica, el valor debe ser TSql.

@command_source

Tipo de ubicación donde se almacena el comando. command_source es nvarchar(50), con un valor predeterminado de Inline, lo que significa que el valor del parámetro @command es el texto literal del comando.

Si se especifica, el valor debe ser Inline.

@command

Script T-SQL válido que va a ejecutar este paso de trabajo. command es nvarchar(max), con un valor predeterminado de NULL.

@credential_name

Nombre de la credencial de ámbito de base de datos almacenada en esta base de datos de control de trabajo que se usa para conectarse a cada una de las bases de datos de destino del grupo de destino cuando se ejecuta este paso. credential_name es nvarchar(128).

Al usar la autenticación de Microsoft Entra (anteriormente Azure Active Directory), omita el parámetro @credential_name , que solo se debe proporcionar al usar credenciales con ámbito de base de datos.

@target_group_name

Nombre del grupo de destino que contiene las bases de datos de destino en las que se ejecutará el paso de trabajo. target_group_name es nvarchar(128).

@initial_retry_interval_seconds

Retraso que se producirá antes del primer reintento,si el paso de trabajo no se ejecuta correctamente en el intento de ejecución inicial. initial_retry_interval_seconds es int, con el valor predeterminado de 1.

@maximum_retry_interval_seconds

Retraso máximo entre los reintentos. Si el retraso entre reintentos aumentaría más que este valor, se limita a este valor en su lugar. maximum_retry_interval_seconds es int, con el valor predeterminado de 120.

@retry_interval_backoff_multiplier

Multiplicador que se aplicará al retraso de reintentos si varios intentos de ejecución del paso de trabajo generan un error. Por ejemplo, si el primer reintento tuvo un retraso de 5 segundos y el multiplicador de retroceso es 2.0, el segundo reintento tendrá un retraso de 10 segundos y el tercero, de 20 segundos. retry_interval_backoff_multiplier es el tipo de datos real, con el valor predeterminado 2.0.

@retry_attempts

Número de veces que reintentará la ejecución si se produce un error en el intento inicial. Por ejemplo, si el valor de retry_attempts es 10, habrá 1 intento inicial y 10 reintentos, lo que dará un total de 11 intentos. Si se produce un error en el intento de reintento final, la ejecución del trabajo finalizará con un lifecycle de Failed registrado en jobs.job_executions. retry_attempts es int, con el valor predeterminado de 10.

@step_timeout_seconds

Cantidad máxima de tiempo permitida para la ejecución del paso. Si se supera este tiempo, la ejecución del trabajo finalizará con un lifecycle de TimedOut registrado en jobs.job_executions. step_timeout_seconds es int, con el valor predeterminado de 43 200 segundos (12 horas).

@output_type

Si no es NULL, el tipo de destino en el que se escribe el primer conjunto de resultados del comando. output_type es nvarchar(50), con un valor predeterminado de NULL.

Si se especifica, el valor debe ser SqlDatabase.

@output_credential_name

Si no es null, el nombre de la credencial con ámbito de base de datos que se usa para conectarse a la base de datos de destino de salida. Debe especificarse si output_type es igual a SqlDatabase. output_credential_name es nvarchar(128), con un valor predeterminado de NULL.

Al usar la autenticación de Microsoft Entra (anteriormente Azure Active Directory), omita el parámetro @output_credential_name , que solo se debe proporcionar al usar credenciales con ámbito de base de datos.

@output_subscription_id

Identificador de suscripción de Azure que se va a usar para la salida. El valor predeterminado es la suscripción del agente de trabajo. output_subscription_id es un únicoidentificador.

@output_resource_group_name

Nombre del grupo de recursos en el que reside la base de datos de salida. El valor predeterminado es el grupo de recursos del agente de trabajo. output_resource_group_name es nvarchar(128).

@output_server_name

Si no es NULL, el nombre DNS completo del servidor que contiene la base de datos de destino de salida, por ejemplo: @output_server_name = 'server1.database.windows.net'. Debe especificarse si output_type es igual a SqlDatabase. output_server_name es nvarchar(256), con un valor predeterminado de NULL.

@output_database_name

Si no es NULL, el nombre de la base de datos que contiene la tabla de destino de salida. Debe especificarse si output_type es igual a SqlDatabase. output_database_name es nvarchar(128), con un valor predeterminado de NULL.

@output_schema_name

Si no es NULL, el nombre del esquema SQL que contiene la tabla de destino de salida. Si output_type es igual SqlDatabasea , el valor predeterminado es dbo . output_schema_name es nvarchar(128).

@output_table_name

Si no es NULL, el nombre de la tabla en la que se escribirá el primer conjunto de resultados del comando. Si la tabla aún no existe, se creará en función del esquema del conjunto de resultados devuelto. Debe especificarse si output_type es igual a SqlDatabase. output_table_name es nvarchar(128), con un valor predeterminado de NULL.

Si especifica un output_table_name, se deben conceder permisos necesarios a la credencial de ámbito de base de datos o UMI del Agente de trabajo para CREAR TABLE e INSERTAR datos en la tabla.

@job_version SALIDA

Parámetro de salida al que se asignará el número de versión de trabajo nuevo. job_version es int.

@max_parallelism SALIDA

Nivel máximo de paralelismo por grupo elástico.

Si está establecido, el paso de trabajo se restringirá para que solo se ejecute en un máximo de las bases de datos por grupo elástico. Esto se aplica a cada grupo elástico que se incluya directamente en el grupo de destino o a los grupos elásticos que se encuentren dentro de un servidor incluido en el grupo de destino. max_parallelism es int.

Valores de código de retorno

0 (correcto) o 1 (erróneo).

Comentarios

Cuando sp_add_jobstep se ejecuta correctamente, se incrementa el número de versión actual del trabajo. La próxima vez que se ejecute el trabajo, se usará la nueva versión. Si el trabajo se está ejecutando actualmente, la ejecución en curso no contendrá el nuevo paso.

  • Al usar la autenticación de Microsoft Entra para autenticarse en servidores de destino o bases de datos, los argumentos @credential_name y @output_credential_name no se deben proporcionar para sp_add_jobstep o sp_update_jobstep.
  • Cuando se usan credenciales de ámbito de base de datos para autenticarse en servidores de destino o bases de datos, se requiere el parámetro @credential_name para sp_add_jobstep y sp_update_jobstep. Por ejemplo, @credential_name = 'job_credential'.

Permisos

De forma predeterminada, los miembros del rol fijo de servidor sysadmin pueden ejecutar este procedimiento almacenado. Solo los miembros de sysadmin pueden usar este procedimiento almacenado para editar los atributos de los trabajos que pertenecen a otros usuarios.

Ejemplos

Creación de un paso de trabajo para ejecutar una instrucción T-SQL

En el ejemplo siguiente se muestra cómo crear un trabajo elástico para ejecutar una instrucción T-SQL en un trabajo elástico. En el ejemplo siguiente se usa jobs.sp_add_jobstep para crear un paso de trabajo en el trabajo denominado CreateTableTest, que se ejecutará en el grupo PoolGroupde destino .

Conéctese a la job_database y ejecute el siguiente comando:

--Connect to the job database specified when creating the job agent

--Add job for create table
EXEC jobs.sp_add_job @job_name = 'CreateTableTest', @description = 'Create Table Test';

-- Add job step for create table
EXEC jobs.sp_add_jobstep @job_name = 'CreateTableTest',
@command = N'IF NOT EXISTS (SELECT * FROM sys.tables WHERE object_id = object_id(''Test''))
CREATE TABLE [dbo].[Test]([TestId] [int] NOT NULL);',
@target_group_name = 'PoolGroup';

Creación de un paso de trabajo para ejecutar una instrucción T-SQL y recopilar resultados

En el ejemplo siguiente se muestra cómo crear un trabajo elástico para ejecutar una instrucción T-SQL en un trabajo elástico y recopilar los resultados en una instancia de Azure SQL Database. En el ejemplo siguiente se usa jobs.sp_add_jobstep para crear un paso de trabajo en el trabajo denominado ResultsJob, que se ejecutará en el grupo PoolGroupde destino . Los resultados se registran en una tabla denominada dbo.results_table en la base de datos denominada Results en el servidor server1.database.windows.net.

--Connect to the job database specified when creating the job agent

-- Add a job to collect perf results
EXEC jobs.sp_add_job @job_name ='ResultsJob', @description='Collection Performance data from all customers'

-- Add a job step w/ schedule to collect results
EXEC jobs.sp_add_jobstep
@job_name = 'ResultsJob',
@command = N' SELECT DB_NAME() DatabaseName, $(job_execution_id) AS job_execution_id, * FROM sys.dm_db_resource_stats WHERE end_time > DATEADD(mi, -20, GETDATE());',
@target_group_name = 'PoolGroup',
@output_type = 'SqlDatabase',
@output_server_name = 'server1.database.windows.net',
@output_database_name = 'Results',
@output_schema_name = 'dbo',
@output_table_name = 'results_table';

Contenido relacionado