sp_add_jobstep (T-SQL)

  • Artikel

Berlaku untuk:SQL ServerAzure SQL Managed Instance

Menambahkan langkah (operasi) ke pekerjaan SQL Server Agent.

Konvensi sintaks transact-SQL

Penting

Pada Azure SQL Managed Instance, sebagian besar, tetapi tidak semua jenis pekerjaan SQL Server Agent didukung. Lihat Perbedaan T-SQL Azure SQL Managed Instance dari SQL Server untuk detailnya.

Sintaks

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

Argumen

[ @job_id = ] 'job_id'

Nomor identifikasi pekerjaan yang akan ditambahkan langkahnya. @job_id adalah uniqueidentifier, dengan default NULL.

Baik @job_id atau @job_name harus ditentukan, tetapi keduanya tidak dapat ditentukan.

[ @job_name = ] N'job_name'

Nama pekerjaan untuk menambahkan langkah. @job_name adalah sysname, dengan default NULL.

Baik @job_id atau @job_name harus ditentukan, tetapi keduanya tidak dapat ditentukan.

[ @step_id = ] step_id

Nomor identifikasi urutan untuk langkah pekerjaan. @step_id int, dengan default NULL. Nomor identifikasi langkah dimulai pada 1 dan tahapan tanpa celah. Jika langkah disisipkan dalam urutan yang ada, nomor urut disesuaikan secara otomatis. Nilai disediakan jika @step_id tidak ditentukan.

[ @step_name = ] N'step_name'

Nama langkah. @step_name adalah sysname, tanpa default.

[ @subsystem = ] N'subsistem'

Subsistem yang digunakan oleh layanan SQL Server Agent untuk menjalankan @command. @subsystem adalah nvarchar(40), dan bisa menjadi salah satu nilai ini.

Nilai Deskripsi
ActiveScripting Skrip Aktif

Penting: Fitur ini akan dihapus di versi SQL Server yang akan datang. Hindari menggunakan fitur ini dalam pekerjaan pengembangan baru, dan rencanakan untuk memodifikasi aplikasi yang saat ini menggunakan fitur ini.
CmdExec Perintah sistem operasi atau program yang dapat dieksekusi
Distribution Pekerjaan Agen Distribusi Replikasi
Snapshot Pekerjaan Agen Replikasi Rekam Jepret
LogReader Pekerjaan Agen Pembaca Log Replikasi
Merge Pekerjaan Agen Penggabungan Replikasi
QueueReader Pekerjaan Agen Pembaca Antrean Replikasi
ANALYSISQUERY Kueri Analysis Services (MDX, DMX)
ANALYSISCOMMAND Perintah Analysis Services (XMLA)
SSIS Eksekusi paket Integration Services
PowerShell Skrip PowerShell
TSQL (default) Pernyataan Transact-SQL

[ @command = ] N'command'

Perintah yang akan dijalankan oleh layanan SQL Server Agent melalui @subsystem. @command adalah nvarchar(max), dengan default NULL. SQL Server Agent menyediakan substitusi token, yang memberi Anda fleksibilitas yang sama dengan yang disediakan variabel saat Anda menulis program perangkat lunak.

Makro escape harus menyertai semua token yang digunakan dalam langkah-langkah pekerjaan, atau langkah pekerjaan tersebut gagal. Selain itu, Anda sekarang harus memasukkan nama token dalam tanda kurung dan menempatkan tanda dolar ($) di awal sintaks token. Misalnya: $(ESCAPE_<macro name>(DATE)).

Untuk informasi selengkapnya tentang token ini dan memperbarui langkah-langkah pekerjaan Anda untuk menggunakan sintaks token baru, lihat Menggunakan Token di Langkah Pekerjaan.

Setiap pengguna Windows dengan izin tulis pada Log Peristiwa Windows dapat mengakses langkah-langkah pekerjaan yang diaktifkan oleh pemberitahuan SQL Server Agent atau pemberitahuan WMI. Untuk menghindari risiko keamanan ini, token SQL Server Agent yang dapat digunakan dalam pekerjaan yang diaktifkan oleh pemberitahuan dinonaktifkan secara default. Token ini adalah: A-DBN, , A-SVR, A-ERRA-SEV, A-MSG, dan WMI(<property>). Dalam rilis ini, penggunaan token diperluas ke semua pemberitahuan.

Jika Anda perlu menggunakan token ini, pertama-tama pastikan bahwa hanya anggota grup keamanan Windows tepercaya, seperti grup Administrator, yang memiliki izin tulis di Log Peristiwa komputer tempat SQL Server berada. Kemudian, klik kanan SQL Server Agent di Object Explorer, pilih Properti, dan pada halaman Sistem Pemberitahuan, pilih Ganti token untuk semua respons pekerjaan ke pemberitahuan untuk mengaktifkan token ini.

[ @additional_parameters = ] N'additional_parameters'

Diidentifikasi hanya untuk tujuan informasi. Tidak didukung. Kompatibilitas di masa mendatang tidak dijamin.

[ @cmdexec_success_code = ] cmdexec_success_code

Nilai yang CmdExec dikembalikan oleh perintah subsistem untuk menunjukkan bahwa @command berhasil dijalankan. @cmdexec_success_code int, dengan default 0.

[ @on_success_action = ] on_success_action

Tindakan yang harus dilakukan jika langkah berhasil. @on_success_action kecil, dan bisa menjadi salah satu nilai ini.

Nilai Deskripsi (tindakan)
1 (default) Keluar dengan sukses
2 Keluar dengan kegagalan
3 Masuk ke langkah berikutnya
4 Buka langkah @on_success_step_id

[ @on_success_step_id = ] on_success_step_id

ID langkah dalam pekerjaan ini untuk dijalankan jika langkah berhasil dan @on_success_action adalah 4. @on_success_step_id int, dengan default 0.

[ @on_fail_action = ] on_fail_action

Tindakan yang harus dilakukan jika langkah gagal. @on_fail_action kecil, dan bisa menjadi salah satu nilai ini.

Nilai Deskripsi (tindakan)
1 Keluar dengan sukses
2 (default) Keluar dengan kegagalan
3 Masuk ke langkah berikutnya
4 Buka langkah @on_fail_step_id

[ @on_fail_step_id = ] on_fail_step_id

ID langkah dalam pekerjaan ini untuk dijalankan jika langkah gagal dan @on_fail_action adalah 4. @on_fail_step_id int, dengan default 0.

[ @server = ] N'server'

Diidentifikasi hanya untuk tujuan informasi. Tidak didukung. Kompatibilitas di masa mendatang tidak dijamin.

[ @database_name = ] N'database_name'

Nama database untuk menjalankan langkah Transact-SQL. @database_name adalah sysname, dengan default NULL, dalam hal master ini database digunakan. Nama yang diapit dalam tanda kurung siku ([]) tidak diizinkan. Untuk langkah pekerjaan ActiveX, @database_name adalah nama bahasa pembuatan skrip yang digunakan langkah tersebut.

[ @database_user_name = ] N'database_user_name'

Nama akun pengguna yang akan digunakan saat menjalankan langkah Transact-SQL. @database_user_name adalah sysname, dengan default NULL. Saat @database_user_name adalah NULL, langkah berjalan dalam konteks pengguna pemilik pekerjaan di @database_name. SQL Server Agent menyertakan parameter ini hanya jika pemilik pekerjaan adalah sysadmin SQL Server. Jika demikian, langkah Transact-SQL yang diberikan dijalankan dalam konteks nama pengguna SQL Server yang diberikan. Jika pemilik pekerjaan bukan sysadmin SQL Server, maka langkah Transact-SQL selalu dijalankan dalam konteks login yang memiliki pekerjaan ini, dan parameter @database_user_name diabaikan.

[ @retry_attempts = ] retry_attempts

Jumlah percobaan ulang yang akan digunakan jika langkah ini gagal. @retry_attempts int, dengan default 0, yang menunjukkan tidak ada upaya coba lagi.

[ @retry_interval = ] retry_interval

Jumlah waktu dalam menit antara upaya percobaan ulang. @retry_interval int, dengan default 0, yang menunjukkan 0interval -menit.

[ @os_run_priority = ] os_run_priority

Diidentifikasi hanya untuk tujuan informasi. Tidak didukung. Kompatibilitas di masa mendatang tidak dijamin.

[ @output_file_name = ] N'output_file_name'

Nama file tempat output langkah ini disimpan. @output_file_name adalah nvarchar(200), dengan default NULL. @output_file_name dapat menyertakan satu atau beberapa token yang tercantum di bawah @command. Parameter ini hanya valid dengan perintah yang berjalan pada subsistem Transact-SQL, CmdExec, , PowerShellIntegration Services, atau Analysis Services.

[ @flags = ] bendera

Opsi yang mengontrol perilaku. @flags int, dan bisa menjadi salah satu nilai ini.

Nilai Deskripsi
0 (default) Timpa file output
2 Tambahkan ke file output
4 Tulis output langkah pekerjaan Transact-SQL ke riwayat langkah
8 Menulis log ke tabel (timpa riwayat yang ada)
16 Menulis log ke tabel (tambahkan ke riwayat yang ada)
32 Menulis semua output ke riwayat pekerjaan
64 Membuat peristiwa Windows untuk digunakan sebagai sinyal bagi cmd langkah pekerjaan untuk membatalkan

[ @proxy_id = ] proxy_id

Nomor ID proksi tempat langkah pekerjaan berjalan. @proxy_id int, dengan default NULL. Jika tidak ada @proxy_id yang ditentukan, tidak ada @proxy_name yang ditentukan, dan tidak ada @database_user_name yang ditentukan, langkah pekerjaan berjalan sebagai akun layanan untuk SQL Server Agent.

[ @proxy_name = ] N'proxy_name'

Nama proksi tempat langkah pekerjaan berjalan. @proxy_name adalah sysname, dengan default NULL. Jika tidak ada @proxy_id yang ditentukan, tidak ada @proxy_name yang ditentukan, dan tidak ada @database_user_name yang ditentukan, langkah pekerjaan berjalan sebagai akun layanan untuk SQL Server Agent.

[ @step_uid = ] OUTPUT 'step_uid'

@step_uid adalah parameter OUTPUT dari jenis pengidentifikasi unik.

Mengembalikan nilai kode

0 (berhasil) atau 1 (kegagalan).

Tataan hasil

Tidak ada.

Keterangan

sp_add_jobstep harus dijalankan dari msdb database.

SQL Server Management Studio menyediakan cara grafis yang mudah untuk mengelola pekerjaan, dan merupakan cara yang direkomendasikan untuk membuat dan mengelola infrastruktur pekerjaan.

Secara default, langkah pekerjaan berjalan sebagai akun layanan untuk SQL Server Agent kecuali proksi lain ditentukan. Persyaratan akun ini adalah menjadi anggota peran keamanan tetap sysadmin .

Proksi mungkin diidentifikasi oleh @proxy_name atau @proxy_id.

Prosedur tersimpan sp_add_jobstep ini berbagi nama dengan objek serupa untuk layanan Azure Elastic Jobs untuk Azure SQL Database. Untuk informasi tentang versi pekerjaan elastis, lihat jobs.sp_add_jobstep (Azure Elastic Jobs) (Transact-SQL).

Izin

Prosedur tersimpan ini dimiliki oleh peran db_owner . Anda dapat memberikan EXECUTE izin untuk pengguna mana pun, tetapi izin ini dapat ditimpa selama peningkatan SQL Server.

Pengguna lain harus diberikan salah satu peran database tetap SQL Server Agent berikut dalam msdb database:

  • SQLAgentUserRole
  • SQLAgentReaderRole
  • SQLAgentOperatorRole

Untuk detail tentang izin peran ini, lihat Peran Database Tetap Agen SQL Server.

Pembuat langkah pekerjaan harus memiliki akses ke proksi untuk langkah pekerjaan. Anggota peran server tetap sysadmin memiliki akses ke semua proksi. Pengguna lain harus secara eksplisit diberikan akses ke proksi.

Contoh

Contoh berikut membuat langkah pekerjaan yang mengubah akses database menjadi baca-saja untuk database Penjualan. Selain itu, contoh ini menentukan lima upaya coba lagi, dengan setiap percobaan kembali terjadi setelah penantian 5 menit.

Catatan

Contoh ini mengasumsikan bahwa Weekly Sales Data Backup pekerjaan sudah ada.

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

Konten terkait