Paket Integration Services (SSIS) dan Parameter Proyek

Artikel
05/23/2023

Berlaku untuk: Integration Runtime SSIS SQL Server di Azure Data Factory

Parameter Integration Services (SSIS) memungkinkan Anda menetapkan nilai ke properti dalam paket pada saat eksekusi paket. Anda dapat membuat parameter proyek di tingkat proyek dan parameter paket di tingkat paket. Parameter proyek digunakan untuk menyediakan input eksternal yang diterima proyek ke satu atau beberapa paket dalam proyek. Parameter paket memungkinkan Anda memodifikasi eksekusi paket tanpa harus mengedit dan menyebarkan ulang paket.

Dalam SQL Server Data Tools Anda membuat, memodifikasi, atau menghapus parameter proyek dengan menggunakan jendela Project.params. Anda membuat, memodifikasi, dan menghapus parameter paket dengan menggunakan tab Parameter di SSIS Designer. Anda mengaitkan parameter baru atau yang sudah ada dengan properti tugas dengan menggunakan kotak dialog Parameterisasi . Untuk informasi selengkapnya tentang menggunakan jendela Project.params dan tab Parameter , lihat Membuat Parameter. Untuk informasi selengkapnya tentang kotak dialog Parameterisasi , lihat Kotak Dialog Parameterisasi.

Parameter dan Model Penyebaran Paket

Secara umum, jika Anda menyebarkan paket menggunakan model penyebaran paket, Anda harus menggunakan konfigurasi alih-alih parameter.

Saat Anda menyebarkan paket yang berisi parameter menggunakan model penyebaran paket lalu menjalankan paket, parameter tidak dipanggil selama eksekusi. Jika paket berisi parameter dan ekspresi paket dalam paket, gunakan parameter, nilai yang dihasilkan diterapkan pada runtime. Jika paket berisi parameter proyek, eksekusi paket mungkin gagal.

Parameter dan Model Penyebaran Proyek

Saat Anda menyebarkan proyek ke server Integration Services (SSIS), Anda menggunakan tampilan, prosedur tersimpan, dan UI SQL Server Management Studio untuk mengelola parameter proyek dan paket. Untuk informasi selengkapnya, lihat topik berikut.

Nilai Parameter

Anda dapat menetapkan hingga tiga jenis nilai yang berbeda ke parameter. Ketika eksekusi paket dimulai, satu nilai digunakan untuk parameter , dan parameter diselesaikan ke nilai harfiah akhirnya.

Tabel berikut ini mencantumkan jenis nilai.

Nama Nilai	Deskripsi	Jenis nilai
Nilai Eksekusi	Nilai yang ditetapkan ke instans eksekusi paket tertentu. Penugasan ini mengambil alih semua nilai lainnya, tetapi hanya berlaku untuk satu instans eksekusi paket.	Harfiah
Nilai Server	Nilai yang ditetapkan ke parameter dalam cakupan proyek, setelah proyek disebarkan ke server Integration Services. Nilai ini mengambil alih default desain.	Referensi Variabel Literal atau Lingkungan
Nilai Desain	Nilai yang ditetapkan ke parameter saat proyek dibuat atau diedit di SQL Server Data Tools. Nilai ini bertahan dengan proyek.	Harfiah

Anda dapat menggunakan satu parameter untuk menetapkan nilai ke beberapa properti paket. Properti paket tunggal hanya dapat diberi nilai dari satu parameter.

Eksekusi dan Nilai Parameter

Eksekusi adalah objek yang mewakili satu instans eksekusi paket. Saat membuat eksekusi, Anda menentukan semua detail yang diperlukan untuk menjalankan paket seperti nilai parameter eksekusi. Anda juga dapat mengubah nilai parameter untuk eksekusi yang ada.

Ketika Anda secara eksplisit menetapkan nilai parameter eksekusi, nilai hanya berlaku untuk instans eksekusi tertentu. Nilai eksekusi digunakan alih-alih nilai server atau nilai desain. Jika Anda tidak secara eksplisit menetapkan nilai eksekusi, dan nilai server telah ditentukan, nilai server akan digunakan.

Ketika parameter ditandai sebagai diperlukan, nilai server atau nilai eksekusi harus ditentukan untuk parameter tersebut. Jika tidak, paket yang sesuai tidak dijalankan. Meskipun parameter memiliki nilai default pada waktu desain, parameter tidak akan pernah digunakan setelah proyek disebarkan.

Variabel Lingkungan

Jika parameter mereferensikan variabel lingkungan, nilai harfiah dari variabel tersebut diselesaikan melalui referensi lingkungan yang ditentukan dan diterapkan ke parameter . Nilai parameter literal akhir yang digunakan untuk eksekusi paket disebut sebagai nilai parameter eksekusi. Anda menentukan referensi lingkungan untuk eksekusi dengan menggunakan kotak dialog Jalankan

Jika parameter proyek mereferensikan variabel lingkungan dan nilai harfiah dari variabel tidak dapat diselesaikan saat eksekusi, nilai desain digunakan. Nilai server tidak digunakan.

Untuk melihat variabel lingkungan yang ditetapkan ke nilai parameter, kueri tampilan catalog.object_parameters. Untuk informasi selengkapnya, lihat catalog.object_parameters (Database SSISDB).

Menentukan Nilai Parameter Eksekusi

Tampilan T-SQL berikut dan prosedur tersimpan dapat digunakan untuk menampilkan dan mengatur nilai parameter.

catalog.execution_parameter_values (Database SSISDB)(tampilan)
Memperlihatkan nilai parameter aktual dalam eksekusi tertentu.

catalog.get_parameter_values (Database SSISDB) (prosedur tersimpan)
Mengatasi dan memperlihatkan nilai aktual untuk paket dan referensi lingkungan yang ditentukan.

catalog.object_parameters (Database SSISDB) (tampilan)
Menampilkan parameter dan properti untuk semua paket dan proyek dalam katalog Layanan Integrasi, termasuk nilai default desain dan default server.

catalog.set_execution_parameter_value (Database SSISDB)
Menetapkan nilai parameter untuk instans eksekusi dalam katalog Layanan Integrasi.

Anda juga dapat menggunakan kotak dialog Jalankan Paket di SQL Server Data Tools (SSDT) mengubah nilai parameter. Untuk informasi selengkapnya, lihat Kotak Dialog Jalankan Paket.

Anda juga dapat menggunakan opsi dtexec /Parameter untuk mengubah nilai parameter. Untuk informasi selengkapnya, lihat Utilitas dtexec.

Validasi Parameter

Jika nilai parameter tidak dapat diselesaikan, eksekusi paket yang sesuai akan gagal. Untuk membantu menghindari kegagalan, Anda dapat memvalidasi proyek dan paket dengan menggunakan kotak dialog Validasi di SQL Server Data Tools (SSDT). Validasi memungkinkan Anda mengonfirmasi bahwa semua parameter memiliki nilai yang diperlukan atau dapat menyelesaikan nilai yang diperlukan dengan referensi lingkungan tertentu. Validasi juga memeriksa masalah paket umum lainnya.

Untuk informasi selengkapnya, lihat Kotak Dialog Validasi.

Contoh Parameter

Contoh ini menjelaskan parameter bernama pkgOptions yang digunakan untuk menentukan opsi untuk paket tempatnya berada.

Selama waktu desain, ketika parameter dibuat di SQL Server Data Tools, nilai default 1 ditetapkan ke parameter . Nilai default ini disebut sebagai default desain. Jika proyek disebarkan ke katalog SSISDB dan tidak ada nilai lain yang ditetapkan ke parameter ini, properti paket yang sesuai dengan parameter pkgOptions akan diberi nilai 1 selama eksekusi paket. Default desain tetap ada pada proyek sepanjang siklus hidupnya.

Saat menyiapkan instans eksekusi paket tertentu, nilai 5 ditetapkan ke parameter pkgOptions . Nilai ini disebut sebagai nilai eksekusi karena berlaku untuk parameter hanya untuk instans eksekusi tertentu. Ketika eksekusi dimulai, properti paket yang sesuai dengan parameter pkgOptions ditetapkan nilai 5.

Membuat parameter

Anda menggunakan SQL Server Data Tools (SSDT) untuk membuat parameter proyek dan parameter paket. Prosedur berikut memberikan instruksi langkah demi langkah untuk membuat parameter paket/proyek.

Catatan

Jika Anda mengonversi proyek yang Anda buat menggunakan versi Integration Services yang lebih lama ke model penyebaran proyek, Anda dapat menggunakan Wizard Konversi Proyek Integration Services untuk membuat parameter berdasarkan konfigurasi. Untuk informasi selengkapnya, lihat Menyebarkan Proyek dan Paket Integration Services (SSIS).

Membuat parameter paket

Buka paket di SQL Server Data Tools, lalu klik tab Parameter di Perancang SSIS.

Parameter
Klik tombol Tambahkan Parameter pada toolbar.

Masukkan nilai untuk properti Nama, Jenis Data, Nilai, Sensitif, dan Diperlukan dalam daftar itu sendiri atau di jendela Properti . Tabel berikut ini menjelaskan properti ini.

Properti	Deskripsi
Nama	Nama parameter.
Jenis Data	Tipe data parameter.
Nilai default	Nilai default untuk parameter yang ditetapkan pada waktu desain. Ini juga dikenal sebagai default desain.
Sensitif	Nilai parameter sensitif dienkripsi dalam katalog dan muncul sebagai nilai NULL saat dilihat dengan Transact-SQL atau SQL Server Management Studio.
Diperlukan	Mengharuskan nilai, selain default desain, ditentukan sebelum paket dapat dijalankan.
Deskripsi	Untuk keberlanjutan, deskripsi parameter . Di SQL Server Data Tools (SSDT), atur deskripsi parameter di jendela Properti Visual Studio saat parameter dipilih di jendela parameter yang berlaku.

Catatan

Saat Anda menyebarkan proyek ke katalog, beberapa properti lagi akan dikaitkan dengan proyek. Untuk melihat semua properti untuk semua parameter dalam katalog, gunakan tampilan catalog.object_parameters (Database SSISDB).

Simpan proyek untuk menyimpan perubahan ke parameter. Nilai parameter disimpan dalam file proyek.

Peringatan

Anda dapat mengedit di tempat dalam daftar atau menggunakan jendela Properti untuk mengubah nilai properti parameter. Anda dapat menghapus parameter dengan menggunakan tombol toolbar Hapus (X). Dengan menggunakan tombol toolbar terakhir, Anda dapat menentukan nilai untuk parameter yang hanya digunakan saat Anda menjalankan paket di SQL Server Data Tools.

Catatan

Jika Anda membuka kembali file paket tanpa membuka proyek di SQL Server Data Tools, tab Parameter akan kosong dan dinonaktifkan.

Membuat parameter proyek

Buka proyek di SQL Server Data Tools.
Klik kanan Project.params di Penjelajah Solusi, lalu klik Buka (ATAU) klik dua kali Project.params untuk membukanya.
Klik tombol Tambahkan Parameter pada toolbar.

Masukkan nilai untuk properti Nama, Jenis Data, Nilai, Sensitif, dan Diperlukan .

Properti	Deskripsi
Nama	Nama parameter.
Jenis Data	Tipe data parameter.
Nilai default	Nilai default untuk parameter yang ditetapkan pada waktu desain. Ini juga dikenal sebagai default desain.
Sensitif	Nilai parameter sensitif dienkripsi dalam katalog dan muncul sebagai nilai NULL saat dilihat dengan Transact-SQL atau SQL Server Management Studio.
Diperlukan	Mengharuskan nilai, selain default desain, ditentukan sebelum paket dapat dijalankan.
Deskripsi	Untuk keberlanjutan, deskripsi parameter . Di SQL Server Data Tools, atur deskripsi parameter di jendela Properti Visual Studio saat parameter dipilih di jendela parameter yang berlaku.

Simpan proyek untuk menyimpan perubahan ke parameter. Nilai parameter disimpan dalam konfigurasi dalam file proyek. Simpan file proyek untuk berkomitmen pada disk perubahan apa pun dalam nilai parameter.

Peringatan

Anda dapat mengedit di tempat dalam daftar atau menggunakan jendela Properti untuk mengubah nilai properti parameter. Anda dapat menghapus parameter dengan menggunakan tombol toolbar Hapus (X). Menggunakan tombol toolbar terakhir untuk membuka kotak dialog Kelola Nilai Parameter, Anda dapat menentukan nilai untuk parameter yang hanya digunakan saat Anda menjalankan paket di SQL Server Data Tools.

Kotak Dialog Parameterisasi

Kotak dialog Parameterisasi memungkinkan Anda mengaitkan parameter baru atau yang sudah ada dengan properti tugas. Anda membuka kotak dialog dengan mengklik kanan tugas atau tab Alur Kontrol di Perancang SSIS lalu dengan mengklik Parameterisasi. Daftar berikut ini menjelaskan elemen UI dalam kotak dialog. Untuk informasi selengkapnya tentang parameter, lihat Parameter Integration Services (SSIS).

Opsi

Properti
Pilih properti tugas yang ingin Anda kaitkan dengan parameter. Daftar ini diisi dengan semua properti yang dapat diparameterkan.

Gunakan parameter yang ada
Pilih opsi ini untuk mengaitkan properti tugas dengan parameter yang ada lalu pilih parameter dari daftar drop-down.

Jangan gunakan parameter
Pilih opsi ini untuk menghapus referensi ke parameter. Parameter tidak dihapus.

Membuat parameter baru
Pilih opsi ini untuk membuat parameter baru yang ingin Anda kaitkan dengan properti tugas.

Nama
Tentukan nama parameter yang ingin Anda buat.

Deskripsi
Tentukan deskripsi untuk parameter.

Nilai
Tentukan nilai default untuk parameter . Ini juga dikenal sebagai default desain, yang dapat ditimpa nanti pada waktu penyebaran.

Cakupan
Tentukan cakupan parameter dengan memilih opsi Proyek atau Paket . Parameter proyek digunakan untuk menyediakan input eksternal yang diterima proyek ke satu atau beberapa paket dalam proyek. Parameter paket memungkinkan Anda memodifikasi eksekusi paket tanpa harus mengedit dan menyebarkan ulang paket.

Sensitif
Tentukan apakah parameter sensitif dengan mencentang atau mengosongkan kotak centang. Nilai parameter sensitif dienkripsi dalam katalog dan muncul sebagai nilai NULL saat dilihat dengan Transact-SQL atau SQL Server Management Studio.

Diperlukan
Tentukan apakah parameter mengharuskan nilai, selain default desain, ditentukan sebelum paket dapat dijalankan.

Mengatur nilai parameter setelah proyek disebarkan

Panduan Penyebaran memungkinkan Anda mengatur nilai parameter default server saat Anda menyebarkan proyek ke katalog. Setelah proyek Anda berada di katalog, Anda dapat menggunakan SQL Server Management Studio (SSMS) Object Explorer atau Transact-SQL untuk mengatur nilai default server.

Mengatur default server dengan SQL Server Management Object Explorer

Pilih dan klik kanan proyek di bawah simpul Layanan Integrasi .
Klik Properti untuk membuka jendela dialog Properti Proyek .
Buka halaman parameter dengan mengklik Parameter di bawah Pilih halaman.
Pilih parameter yang diinginkan di daftar Parameter . Catatan: Kolom Kontainer membantu membedakan parameter proyek dari parameter paket.
Di kolom Nilai , tentukan nilai parameter default server yang diinginkan.

Mengatur default server dengan Transact-SQL

Untuk mengatur default server dengan Transact-SQL, gunakan prosedur tersimpan catalog.set_object_parameter_value (Database SSISDB). Untuk menampilkan default server saat ini, kueri tampilan catalog.object_parameters (Database SSISDB). Untuk menghapus nilai default server, gunakan prosedur tersimpan catalog.clear_object_parameter_value (Database SSISDB ).