jobs.sp_add_jobstep (Azure Elastic Jobs) (Transact-SQL)

  • Artikel

Gilt für: Azure SQL-Datenbank

Fügt einen Schritt zu einem vorhandenen Auftrag im Azure Elastic Jobs-Dienst für Azure SQL-Datenbank hinzu. Verwenden Sie jobs.sp_update_jobstep , um vorhandene elastische Auftragsschritte zu ändern.

Diese gespeicherte Prozedur teilt den Namen mit sp_add_jobstep einem ähnlichen Objekt in SQL Server für den SQL Server-Agent-Dienst. Informationen zur SQL Server-Agent-Version finden Sie unter sp_add_jobstep.

Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

@job_name

Der Name des Auftrags, dem der Schritt hinzugefügt werden soll. job_name ist nvarchar(128).

@step_id

Die Sequenz-ID des Auftragsschritts. Die Schritt-IDs beginnen bei „1“ und erhöhen sich lückenlos schrittweise. Wenn ein vorhandener Schritt bereits über diese ID verfügt, wird dieser Schritt und alle folgenden Schritte inkrementiert, sodass dieser neue Schritt in die Sequenz eingefügt werden kann. Wenn nicht angegeben, wird der step_id automatisch der letzten in der Abfolge der Schritte zugewiesen. step_id ist ein Int.

@step_name

Der Name des Schritts. Muss angegeben werden, mit Ausnahme des ersten Schritts eines Auftrags, der (aus Gründen der Einfachheit) einen Standardnamen hat JobStep. step_name ist nvarchar(128).

@command_type

Der Typ des Befehls, der von diesem Auftragsschritt ausgeführt wird. command_type ist nvarchar(50), mit einem Standardwert von TSql, was bedeutet, dass der Wert des @command_type-Parameters ein T-SQL-Skript ist.

Wenn angegeben, muss TSqlder Wert sein.

@command_source

Der Typ des Speicherorts, an dem der Befehl gespeichert ist. command_source ist nvarchar(50), mit einem Standardwert von Inline, was bedeutet, dass der Wert des @command Parameters der Literaltext des Befehls ist.

Wenn angegeben, muss Inlineder Wert sein.

@command

Das gültige T-SQL-Skript, das von diesem Auftragsschritt ausgeführt werden soll. command is nvarchar(max), with a default of NULL.

@credential_name

Der Name der datenbankbezogenen Anmeldeinformationen, die in dieser Auftragssteuerungsdatenbank gespeichert sind, die zum Herstellen einer Verbindung mit den einzelnen Zieldatenbanken innerhalb der Zielgruppe verwendet wird, wenn dieser Schritt ausgeführt wird. credential_name ist nvarchar(128).

Wenn Sie die Microsoft Entra-Authentifizierung (vormals Azure Active Directory) verwenden, lassen Sie den parameter @credential_name aus, der nur bei Verwendung von Anmeldeinformationen mit Datenbankbereich bereitgestellt werden sollte.

@target_group_name

Der Name der Zielgruppe, die die Zieldatenbanken enthält, für die der Auftragsschritt ausgeführt wird. target_group_name ist nvarchar(128).

@initial_retry_interval_seconds

Die Verzögerung vor dem ersten Wiederholungsversuch, wenn der Auftragsschritt bei der ersten Ausführung einen Fehler verursacht. initial_retry_interval_seconds ist int mit dem Standardwert 1.

@maximum_retry_interval_seconds

Die maximale Verzögerung zwischen Wiederholungsversuchen. Wenn die Verzögerung zwischen Wiederholungen größer als dieser Wert würde, wird sie stattdessen auf diesen Wert begrenzt. maximum_retry_interval_seconds ist int mit dem Standardwert 120.

@retry_interval_backoff_multiplier

Der Multiplikator, der auf die Wiederholungsverzögerung anzuwenden ist, wenn bei mehreren Auftragsschrittausführungen ein Fehler aufgetreten ist. Wenn beim ersten Wiederholungsversuch z.B. eine Verzögerung von 5 Sekunden aufgetreten ist und der Wartezeitmultiplikator „2,0“ beträgt, tritt beim zweiten Wiederholungsversuch eine Verzögerung von 10 Sekunden und beim dritten Wiederholungsversuch eine Verzögerung von 20 Sekunden auf. retry_interval_backoff_multiplier ist der echte Datentyp mit dem Standardwert 2,0.

@retry_attempts

Die Anzahl der Wiederholungen für die Ausführung, wenn beim ersten Versuch ein Fehler auftritt. Wenn beispielsweise der wert retry_attempts 10 ist, gibt es 1 anfänglichen Versuch und 10 Wiederholungsversuche, sodass insgesamt 11 Versuche zurückgegeben werden. Wenn der letzte Wiederholungsversuch fehlschlägt, wird die Auftragsausführung mit einem lifecycle in Failed jobs.job_executions aufgezeichneten Beendet. retry_attempts ist int mit dem Standardwert 10.

@step_timeout_seconds

Die maximal zulässige Dauer für den auszuführenden Schritt. Wenn diese Zeit überschritten wird, wird die Auftragsausführung mit einem lifecycle in TimedOut jobs.job_executions aufgezeichneten Beendet. step_timeout_seconds ist "int" mit dem Standardwert 43.200 Sekunden (12 Stunden).

@output_type

Wenn nichtNULL, wird der Typ des Ziels, in das das erste Resultset des Befehls geschrieben wird, geschrieben. output_type ist nvarchar(50), mit einem Standardwert von NULL.

Wenn angegeben, muss SqlDatabaseder Wert sein.

@output_credential_name

Wenn nicht NULL, der Name der Anmeldeinformationen mit Datenbankbereich, die zum Herstellen einer Verbindung mit der Ausgabezieldatenbank verwendet wird. Muss angegeben werden, wenn output_type gleich ist SqlDatabase. output_credential_name ist nvarchar(128), mit einem Standardwert von NULL.

Wenn Sie die Microsoft Entra-Authentifizierung (vormals Azure Active Directory) verwenden, lassen Sie den parameter @output_credential_name aus, der nur bei Verwendung von Anmeldeinformationen mit Datenbankbereich bereitgestellt werden sollte.

@output_subscription_id

Azure-Abonnement-ID, die für die Ausgabe verwendet werden soll. Standardmäßig wird das Abonnement des Auftragsberaters verwendet. output_subscription_id ist ein eindeutiger Bezeichner.

@output_resource_group_name

Name der Ressourcengruppe, in der sich die Ausgabedatenbank befindet. Standardmäßig wird die Ressourcengruppe des Auftragsagents verwendet. output_resource_group_name ist nvarchar(128).

@output_server_name

Wenn nicht NULL, der vollqualifizierte DNS-Name des Servers, der die Ausgabezieldatenbank enthält, z. B.: @output_server_name = 'server1.database.windows.net'. Muss angegeben werden, wenn output_type gleich ist SqlDatabase. output_server_name ist nvarchar(256), mit einem Standardwert von NULL.

@output_database_name

Wenn nicht NULL, der Name der Datenbank, die die Ausgabezieltabelle enthält. Muss angegeben werden, wenn output_type gleich ist SqlDatabase. output_database_name ist nvarchar(128), mit einem Standardwert von NULL.

@output_schema_name

Wenn nicht NULL, der Name des SQL-Schemas, das die Ausgabezieltabelle enthält. Wenn output_type gleich ist SqlDatabase, lautet dboder Standardwert . output_schema_name ist nvarchar(128).

@output_table_name

Wenn nicht NULL, wird der Name der Tabelle, in die das erste Resultset des Befehls geschrieben wird, geschrieben. Wenn die Tabelle noch nicht vorhanden ist, wird sie basierend auf dem Schema des zurückgegebenen Resultsets erstellt. Muss angegeben werden, wenn output_type gleich ist SqlDatabase. output_table_name ist nvarchar(128), mit einem Standardwert von NULL.

Wenn Sie eine output_table_name angeben, sollten dem Auftrags-Agent UMI oder datenbankbezogenen Anmeldeinformationen die erforderlichen Berechtigungen für CREATE TABLE und INSERT-Daten in der Tabelle erteilt werden.

@job_version AUSGABE

Der Output-Parameter, der die Versionsnummer des neuen Auftrags zugewiesen wird. job_version ist int.

@max_parallelism AUSGABE

Der maximale Grad an Parallelität pro Pool für elastische Datenbanken.

Wenn dieser festgelegt ist, kann beim Auftragsschritt ausschließlich der maximale Grenzwert der zahlreichen Datenbanken pro Pool für elastische Datenbanken ausgeführt werden. Dies gilt für sämtliche Pools für elastische Datenbanken, die entweder direkt in die Zielgruppe eingeschlossen sind oder sich auf einem Server befinden, der in der Zielgruppe eingeschlossen ist. max_parallelism ist int.

Rückgabecodewerte

0 (erfolgreich) oder 1 Fehler.

Hinweise

Wenn sp_add_jobstep dies erfolgreich ist, wird die aktuelle Versionsnummer des Auftrags erhöht. Bei der nächsten Ausführung des Auftrags wird die neue Version verwendet. Wenn der Auftrag gerade ausgeführt wird, enthält die Ausführung nicht den neuen Schritt.

  • Bei Verwendung der Microsoft Entra-Authentifizierung zur Authentifizierung bei Zielservern/Datenbanken sollten die argumente @credential_name und @output_credential_name nicht bereitgestellt sp_add_jobstep werden.sp_update_jobstep
  • Bei der Verwendung von datenbankübergreifenden Anmeldeinformationen zur Authentifizierung bei Zielserver(n)/Datenbank(en) ist der Parameter @credential_name für sp_add_jobstep und sp_update_jobstep erforderlich. Beispiel: @credential_name = 'job_credential'.

Berechtigungen

Standardmäßig können nur Mitglieder der festen Serverrolle sysadmin diese gespeicherte Prozedur ausführen. Nur Mitglieder der Rolle „sysadmin“ können mithilfe dieser gespeicherten Prozedur Attribute von Aufträgen bearbeiten, die anderen Benutzern gehören.

Beispiele

Erstellen eines Auftragsschritts zum Ausführen einer T-SQL-Anweisung

Das folgende Beispiel zeigt, wie Sie einen elastischen Auftrag erstellen, um eine T-SQL-Anweisung in einem elastischen Auftrag auszuführen. Im folgenden Beispiel wird jobs.sp_add_jobstep ein Auftragsschritt im Auftrag namens CreateTableTesterstellt, der für die Zielgruppe PoolGroupausgeführt werden soll.

Stellen Sie eine Verbindung mit der job_database her, und führen Sie den folgenden Befehl aus:

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

Erstellen eines Auftragsschritts zum Ausführen einer T-SQL-Anweisung und Sammeln von Ergebnissen

Das folgende Beispiel zeigt, wie Sie einen elastischen Auftrag erstellen, um eine T-SQL-Anweisung in einem elastischen Auftrag auszuführen und die Ergebnisse in einem Azure SQL-Datenbank zu sammeln. Im folgenden Beispiel wird jobs.sp_add_jobstep ein Auftragsschritt im Auftrag namens ResultsJoberstellt, der für die Zielgruppe PoolGroupausgeführt werden soll. Die Ergebnisse werden in einer Tabelle aufgezeichnet, die in der Datenbank mit dem Namen auf dem Server server1.database.windows.netbenannt dbo.results_table Results ist.

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

Zugehöriger Inhalt