Menggunakan Token dalam Langkah Pekerjaan

Artikel
10/20/2023

Berlaku untuk:SQL Server Azure SQL Managed Instance

Penting

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

SQL Server Agent memungkinkan Anda menggunakan token dalam skrip langkah pekerjaan Transact-SQL. Menggunakan token saat Anda menulis langkah-langkah pekerjaan memberi Anda fleksibilitas yang sama dengan yang disediakan variabel saat Anda menulis program perangkat lunak. Setelah Anda menyisipkan token dalam skrip langkah pekerjaan, SQL Server Agent menggantikan token pada waktu proses, sebelum langkah pekerjaan dijalankan oleh subsistem Transact-SQL.

Memahami Menggunakan Token

Penting

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-ERR, A-SEV, A-MSG, dan WMI(properti). 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.

Penggantian token SQL Server Agent sederhana dan efisien: SQL Server Agent menggantikan nilai string literal yang tepat untuk token. Semua token peka huruf besar/kecil. Langkah-langkah pekerjaan Anda harus memperhitungkan hal ini dan mengutip token yang Anda gunakan atau mengonversi string pengganti dengan benar ke jenis data yang benar.

Misalnya, Anda mungkin menggunakan pernyataan berikut untuk mencetak nama database dalam langkah pekerjaan:

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

Dalam contoh ini, makro ESCAPE_SQUOTE disisipkan dengan token A-DBN . Pada waktu proses, token A-DBN diganti dengan nama database yang sesuai. Makro escape lolos dari tanda kutip tunggal yang mungkin secara tidak sengaja diteruskan dalam string penggantian token. Agen SQL Server menggantikan satu tanda kutip tunggal dengan dua tanda kutip tunggal dalam string akhir.

Misalnya, jika string yang diteruskan untuk mengganti token adalah AdventureWorks2022'SELECT @@VERSION --, perintah yang dijalankan oleh langkah pekerjaan SQL Server Agent adalah:

PRINT N'Current database name is AdventureWorks2022''SELECT @@VERSION --' ;

Dalam hal ini, pernyataan yang disisipkan, SELECT @@VERSION, tidak dijalankan. Sebaliknya, tanda kutip tunggal tambahan menyebabkan server mengurai pernyataan yang disisipkan sebagai string. Jika string penggantian token tidak berisi tanda kutip tunggal, tidak ada karakter yang lolos dan langkah pekerjaan yang berisi token dijalankan seperti yang dimaksudkan.

Untuk men-debug penggunaan token dalam langkah-langkah pekerjaan Anda, gunakan pernyataan cetak seperti PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' dan simpan output langkah pekerjaan ke file atau tabel. Gunakan halaman Tingkat Lanjut dari kotak dialog Properti Langkah Pekerjaan untuk menentukan file atau tabel output langkah pekerjaan.

Token dan Makro Agen SQL Server

Tabel berikut mencantumkan dan menjelaskan token dan makro yang didukung SQL Server Agent.

Token Agen SQL Server

Token	Deskripsi
(A-DBN)	Nama database. Jika pekerjaan dijalankan oleh pemberitahuan, nilai nama database secara otomatis menggantikan token ini di langkah pekerjaan.
(A-SVR)	Nama server. Jika pekerjaan dijalankan oleh pemberitahuan, nilai nama server secara otomatis menggantikan token ini di langkah pekerjaan.
(A-ERR)	Nomor salah. Jika pekerjaan dijalankan oleh pemberitahuan, nilai nomor kesalahan secara otomatis menggantikan token ini di langkah pekerjaan.
(A-SEV)	Tingkat keparahan kesalahan. Jika pekerjaan dijalankan oleh pemberitahuan, nilai tingkat keparahan kesalahan secara otomatis menggantikan token ini di langkah pekerjaan.
(A-MSG)	Teks pesan. Jika pekerjaan dijalankan oleh pemberitahuan, nilai teks pesan secara otomatis menggantikan token ini di langkah pekerjaan.
(NAMA PEKERJAAN)	Nama pekerjaan. Token ini hanya tersedia di SQL Server 2016 ke atas.
(STEPNAME)	Nama langkah. Token ini hanya tersedia di SQL Server 2016 ke atas.
(TANGGAL)	Tanggal saat ini (dalam format YYYYMMDD).
(INST)	Nama instans. Untuk instans default, token ini memiliki nama instans default: MSSQLSERVER.
(JOBID)	ID Pekerjaan.
(MACH)	Nama komputer.
(MSSA)	Nama layanan Master SQLServerAgent.
(OSCMD)	Awalan untuk program yang digunakan untuk menjalankan langkah-langkah pekerjaan CmdExec .
(SQLDIR)	Direktori tempat SQL Server diinstal. Secara default, nilai ini adalah C:\Program Files\Microsoft SQL Server\MSSQL.
(SQLLOGDIR)	Token pengganti untuk jalur folder log kesalahan SQL Server - misalnya, $(ESCAPE_SQUOTE(SQLLOGDIR)). Token ini hanya tersedia di SQL Server 2014 ke atas.
(STEPCT)	Hitungan berapa kali langkah ini telah dijalankan (tidak termasuk percobaan ulang). Dapat digunakan oleh perintah langkah untuk memaksa penghentian perulangan multistep.
(STEPID)	ID Langkah.
(SRVR)	Nama komputer yang menjalankan SQL Server. Jika instans SQL Server adalah instans bernama, ini termasuk nama instans.
(WAKTU)	Waktu saat ini (dalam format HHMMSS).
(STRTTM)	Waktu (dalam format HHMMSS) pekerjaan mulai dijalankan.
(STRTDT)	Tanggal (dalam format YYYYMMDD) yang mulai dijalankan pekerjaan.
(WMI(properti))	Untuk pekerjaan yang berjalan sebagai respons terhadap pemberitahuan WMI, nilai properti yang ditentukan oleh properti. Misalnya, `$(WMI(DatabaseName))` menyediakan nilai properti DatabaseName untuk peristiwa WMI yang menyebabkan pemberitahuan berjalan.

Makro Escape Agen SQL Server

Makro Escape	Deskripsi
$(ESCAPE_SQUOTE(token_name))	Lolos tanda kutip tunggal (') dalam string penggantian token. Mengganti satu tanda kutip tunggal dengan dua tanda kutip tunggal.
$(ESCAPE_DQUOTE(token_name))	Lolos tanda kutip ganda (") dalam string penggantian token. Mengganti satu tanda kutip ganda dengan dua tanda kutip ganda.
$(ESCAPE_RBRACKET(token_name))	Lolos kurung kanan (]) dalam string penggantian token. Mengganti satu tanda kurung siku kanan dengan dua tanda kurung siku kanan.
$(ESCAPE_NONE(token_name))	Mengganti token tanpa melarikan diri karakter apa pun dalam string. Makro ini disediakan untuk mendukung kompatibilitas mundur di lingkungan di mana string penggantian token hanya diharapkan dari pengguna tepercaya. Untuk informasi selengkapnya, lihat "Memperbarui Langkah Pekerjaan untuk Menggunakan Makro," nanti dalam topik ini.

Perbarui Langkah Pekerjaan untuk Menggunakan Makro

Tabel berikut ini menjelaskan cara penggantian token ditangani oleh SQL Server Agent. Untuk mengaktifkan atau menonaktifkan penggantian token pemberitahuan, klik kanan Agen SQL Server di Object Explorer, pilih Properti, dan pada halaman Sistem Pemberitahuan, pilih atau kosongkan kotak centang Ganti token untuk semua respons pekerjaan ke pemberitahuan.

Sintaks token	Penggantian token pemberitahuan pada	Penggantian token pemberitahuan nonaktif
Makro ESCAPE yang digunakan	Semua token dalam pekerjaan berhasil diganti.	Token yang diaktifkan oleh pemberitahuan tidak diganti. Token ini adalah A-DBN, A-SVR, A-ERR, A-SEV, A-MSG, dan WMI(properti). Token statis lainnya berhasil diganti.
Tidak ada makro ESCAPE yang digunakan	Pekerjaan apa pun yang berisi token gagal.	Pekerjaan apa pun yang berisi token gagal.

Contoh Pembaruan Sintaks Token

Di bawah ini adalah contoh sintaks token untuk membantu mengilustrasikan cara menggunakan perintah ini.

J. Menggunakan token dalam string yang tidak berlapis

Contoh berikut menunjukkan cara memperbarui skrip sederhana yang tidak berlapis dengan makro escape yang sesuai. Sebelum menjalankan skrip pembaruan, skrip langkah pekerjaan berikut menggunakan token langkah pekerjaan untuk mencetak nama database yang sesuai:

PRINT N'Current database name is $(A-DBN)' ;

Setelah menjalankan skrip pembaruan, ESCAPE_NONE makro disisipkan sebelum A-DBN token. Karena tanda kutip tunggal digunakan untuk memisahkan string cetak, Anda harus memperbarui langkah pekerjaan dengan menyisipkan ESCAPE_SQUOTE makro sebagai berikut:

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

B. Menggunakan token dalam string berlapis

Dalam skrip langkah pekerjaan di mana token digunakan dalam string atau pernyataan berlapis, pernyataan berlapis harus ditulis ulang sebagai beberapa pernyataan sebelum menyisipkan makro escape yang sesuai.

Misalnya, pertimbangkan langkah pekerjaan berikut, yang menggunakan A-MSG token dan belum diperbarui dengan makro escape:

PRINT N'Print ''$(A-MSG)''' ;

Setelah menjalankan skrip pembaruan, ESCAPE_NONE makro disisipkan dengan token. Namun, dalam hal ini, Anda harus menulis ulang skrip tanpa menggunakan berlapis sebagai berikut dan menyisipkan ESCAPE_SQUOTE makro untuk melepaskan pemisah dengan benar yang mungkin diteruskan dalam string penggantian token:

DECLARE @msgString nvarchar(max);
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))';
SET @msgString = QUOTENAME(@msgString,'''');
PRINT N'Print ' + @msgString;

Catatan

Dalam contoh ini, fungsi QUOTENAME mengatur karakter kuotasi.

C. Menggunakan token dengan makro ESCAPE_NONE

Contoh berikut adalah bagian dari skrip yang mengambil job_id dari tabel sysjobs dan menggunakan token JOBID untuk mengisi @JobID variabel, yang dideklarasikan sebelumnya dalam skrip sebagai jenis data biner.

Catatan

Karena tidak ada pemisah yang diperlukan untuk jenis data biner, makro ESCAPE_NONE digunakan dengan token JOBID. Anda tidak perlu memperbarui langkah pekerjaan ini setelah menjalankan skrip pembaruan.

DECLARE @JobID uniqueidentifier
SET @JobID = $(ESCAPE_NONE(JOBID))

Ini secara langsung menetapkan nilai dari token JOBID ke @JobID, menghilangkan kueri database yang tidak perlu dan konversi implisit, mengatasi masalah yang dimunculkan di bagian C.

Bagikan melalui