Partager via

jobs.sp_add_jobstep (travaux élastiques Azure) (Transact-SQL)

  • Article

S’applique à : Azure SQL Database

Ajoute une étape à un travail existant dans le service Travaux élastiques Azure pour Azure SQL Database. Utilisez jobs.sp_update_jobstep pour modifier les étapes de travail élastique existantes.

Cette procédure stockée partage le nom d’un sp_add_jobstep objet similaire dans SQL Server pour le service SQL Server Agent. Pour plus d’informations sur la version de SQL Server Agent, consultez sp_add_jobstep.

Conventions de la syntaxe Transact-SQL

Syntaxe

[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 ]

Arguments

@job_name

Nom du travail auquel ajouter l'étape. job_name est nvarchar(128).

@step_id

Numéro d'identification de la séquence de l'étape de travail. Les numéros d’identification d’étape commencent à 1 et augmentent sans intervalle. Si une étape existante possède déjà cet ID, cette étape et toutes les étapes suivantes auront leurs ID incrémentés afin que cette nouvelle étape puisse être insérée dans la séquence. S’il n’est pas spécifié, le step_id est automatiquement affecté au dernier dans la séquence d’étapes. step_id est un int.

@step_name

Nom de l’étape. Doit être spécifié, à l’exception de la première étape d’un travail dont (par commodité) a un nom JobSteppar défaut . step_name est nvarchar(128).

@command_type

Type de commande exécuté par cette étape de travail. command_type est nvarchar(50), avec une valeur TSqlpar défaut , ce qui signifie que la valeur du paramètre @command_type est un script T-SQL.

Si elle est spécifiée, la valeur doit être TSql.

@command_source

Type d’emplacement de stockage de la commande. command_source est nvarchar(50), avec une valeur par défaut , Inlinece qui signifie que la valeur du paramètre @command est le texte littéral de la commande.

Si elle est spécifiée, la valeur doit être Inline.

@command

Script T-SQL valide à exécuter par cette étape de travail. la commande est nvarchar(max), avec la valeur par défaut NULL.

@credential_name

Nom des informations d’identification délimitées à la base de données stockées dans cette base de données de contrôle de travail utilisée pour se connecter à chacune des bases de données cibles au sein du groupe cible lorsque cette étape est exécutée. credential_name est nvarchar(128).

Lorsque vous utilisez l’authentification Microsoft Entra (anciennement Azure Active Directory), omettez le paramètre @credential_name , qui ne doit être fourni que lors de l’utilisation d’informations d’identification délimitées à la base de données.

@target_group_name

Nom du groupe cible qui contient les bases de données cibles sur laquelle l’étape de travail sera exécutée. target_group_name est nvarchar(128).

@initial_retry_interval_seconds

Le délai avant la première nouvelle tentative, si l’étape de travail échoue lors de la tentative d’exécution initiale. initial_retry_interval_seconds est int, avec la valeur par défaut 1.

@maximum_retry_interval_seconds

Délai maximal entre les nouvelles tentatives. Si le délai entre les nouvelles tentatives augmente plus grand que cette valeur, il est limité à cette valeur à la place. maximum_retry_interval_seconds est int, avec la valeur par défaut 120.

@retry_interval_backoff_multiplier

Le multiplicateur à appliquer au délai de nouvelle tentative si plusieurs tentatives d’exécution d’une étape de travail échouent. Par exemple, si la première nouvelle tentative avait un délai de 5 secondes et que le multiplicateur d’interruption est 2,0, la deuxième tentative aura un délai de 10 secondes et la troisième un délai de 20 secondes. retry_interval_backoff_multiplier est le type de données réel, avec la valeur par défaut 2.0.

@retry_attempts

Nombre de nouvelles tentatives d’exécution si la tentative initiale échoue. Par exemple, si la valeur retry_attempts est 10, il y aura 1 tentative initiale et 10 nouvelles tentatives, ce qui donne un total de 11 tentatives. Si la tentative finale de nouvelle tentative échoue, l’exécution du travail se termine par un lifecycle enregistrement Failed dans jobs.job_executions. retry_attempts est int, avec la valeur par défaut 10.

@step_timeout_seconds

La durée maximale autorisée pour l’étape à exécuter. Si cette durée est dépassée, l’exécution du travail se termine par un lifecycle enregistrement TimedOut dans jobs.job_executions. step_timeout_seconds est int, avec la valeur par défaut de 43 200 secondes (12 heures).

@output_type

Si ce n’est pas NULLle cas, le type de destination dans lequel le premier jeu de résultats de la commande est écrit. output_type est nvarchar(50), avec la valeur par défaut NULL.

Si elle est spécifiée, la valeur doit être SqlDatabase.

@output_credential_name

S’il n’est pas null, nom des informations d’identification délimitées à la base de données utilisées pour se connecter à la base de données de destination de sortie. Doit être spécifié si output_type est égal SqlDatabaseà . output_credential_name est nvarchar(128), avec une valeur par défaut de NULL.

Lorsque vous utilisez l’authentification Microsoft Entra (anciennement Azure Active Directory), omettez le paramètre @output_credential_name , qui ne doit être fourni que lors de l’utilisation d’informations d’identification délimitées à la base de données.

@output_subscription_id

ID d’abonnement Azure à utiliser pour la sortie. La valeur par défaut est l’abonnement de l’agent de travail. output_subscription_id est un identificateur unique.

@output_resource_group_name

Nom du groupe de ressources dans lequel réside la base de données de sortie. La valeur par défaut est le groupe de ressources de l’agent de travail. output_resource_group_name est nvarchar(128).

@output_server_name

Si ce n’est pas NULLle cas, le nom DNS complet du serveur qui contient la base de données de destination de sortie, par exemple : @output_server_name = 'server1.database.windows.net'. Doit être spécifié si output_type est égal SqlDatabaseà . output_server_name est nvarchar(256), avec la valeur par défaut NULL.

@output_database_name

Si ce n’est pas NULLle cas, nom de la base de données qui contient la table de destination de sortie. Doit être spécifié si output_type est égal SqlDatabaseà . output_database_name est nvarchar(128), avec la valeur par défaut NULL.

@output_schema_name

Si ce n’est pas NULLle cas, nom du schéma SQL qui contient la table de destination de sortie. Si output_type est égalSqlDatabase, la valeur par défaut est dbo . output_schema_name est nvarchar(128).

@output_table_name

Si ce n’est pas NULLle cas, le nom de la table dans laquelle le premier jeu de résultats de la commande sera écrit. Si la table n’existe pas encore, elle est créée en fonction du schéma du jeu de résultats retourné. Doit être spécifié si output_type est égal SqlDatabaseà . output_table_name est nvarchar(128), avec la valeur NULLpar défaut .

Si vous spécifiez un output_table_name, les informations d’identification de l’agent de travail ou de l’étendue de la base de données doivent disposer des autorisations nécessaires pour CREATE TABLE et INSERT data into the table.

@job_version SORTIE

Paramètre de sortie auquel sera assigné le nouveau numéro de version de travail. job_version est int.

@max_parallelism SORTIE

Le niveau maximal de parallélisme par pool élastique.

S’il est défini, l’étape de travail sera limitée à l’exécution sur un nombre maximum de ces nombreuses bases de données par pool élastique. Ceci s’applique à chaque pool élastique qui est directement inclus dans le groupe cible ou qui se trouve au sein d’un serveur inclus dans le groupe cible. max_parallelism est int.

Valeurs des codes de retour

0 (réussite) or 1 (échec).

Notes

En sp_add_jobstep cas de réussite, le numéro de version actuel du travail est incrémenté. La prochaine fois que le travail sera exécuté, la nouvelle version sera utilisée. Si le travail est en cours d’exécution, cette exécution ne contiendra pas la nouvelle étape.

  • Lors de l’utilisation de l’authentification Microsoft Entra pour s’authentifier auprès des serveurs/bases de données cibles, les arguments @credential_name et @output_credential_name ne doivent pas être fournis pour ou sp_update_jobsteppour sp_add_jobstep .
  • Lors de l’utilisation des informations d’identification limitées à la base de données pour s’authentifier auprès des serveurs/bases de données cibles, le paramètre @credential_name est requis pour sp_add_jobstep et sp_update_jobstep. Par exemple : @credential_name = 'job_credential'.

autorisations

Par défaut, les membres du rôle serveur fixe sysadmin peuvent exécuter cette procédure stockée. Seuls des membres de sysadmin peuvent utiliser cette procédure stockée pour modifier les attributs des travaux qui appartiennent à d’autres utilisateurs.

Exemples

Créer une étape de travail pour exécuter une instruction T-SQL

L’exemple suivant montre comment créer un travail élastique pour exécuter une instruction T-SQL dans un travail élastique. L’exemple suivant utilise jobs.sp_add_jobstep pour créer une étape de travail dans le travail nommé CreateTableTest, à exécuter sur le groupe PoolGroupcible .

Connectez-vous au job_database et exécutez la commande suivante :

--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';

Créer une étape de travail pour exécuter une instruction T-SQL et collecter des résultats

L’exemple suivant montre comment créer un travail élastique pour exécuter une instruction T-SQL dans un travail élastique et collecter les résultats dans une base de données Azure SQL. L’exemple suivant utilise jobs.sp_add_jobstep pour créer une étape de travail dans le travail nommé ResultsJob, à exécuter sur le groupe PoolGroupcible . Les résultats sont enregistrés dans une table nommée dbo.results_table dans la base de données nommée Results dans le serveur 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';

Contenu connexe