Integration Services (SSIS) パッケージおよびプロジェクトパラメーター

[アーティクル]
05/23/2023

適用対象:SQL Server Azure Data Factory の SSIS Integration Runtime

Integration Services (SSIS) パラメーターを使用すると、パッケージの実行時にパッケージ内のプロパティに値を割り当てることができます。 " プロジェクトパラメーター " はプロジェクトレベル、" パッケージパラメーター " はパッケージレベルで作成できます。プロジェクトパラメーターは、プロジェクトが受け取る外部入力をプロジェクト内の 1 つまたは複数のパッケージに指定するために使用します。パッケージパラメーターを使用すると、パッケージを編集したり再配置したりせずにパッケージ実行を変更できます。

SQL Server Data Tools で、 [Project.params] ウィンドウを使用して、プロジェクトパラメーターを作成、変更、または削除します。 デザイナーの [パラメーター] SSIS タブを使用して、パッケージパラメーターを作成、変更、および削除します。 [パラメーター化] ダイアログボックスを使用して、新規または既存のパラメーターをタスクのプロパティと関連付けます。 [Project.params] ウィンドウと [パラメーター] タブの使用の詳細については「 Create Parameters」を参照してください。 [パラメーター化] ダイアログボックスの詳細については、「 Parameterize Dialog Box」を参照してください。

パラメーターとパッケージ配置モデル

通常、パッケージ配置モデルを使用してパッケージを配置する場合、パラメーターではなく構成を使用する必要があります。

パッケージ配置モデルを使用してパラメーターを含むパッケージを配置し、パッケージを実行した場合、実行時にパラメーターは呼び出されません。パッケージにパッケージパラメーターが含まれ、パッケージ内の式でパラメーターが使用されている場合、実行時に結果の値が適用されます。パッケージにプロジェクトパラメーターが含まれている場合、パッケージの実行は失敗する可能性があります。

パラメーターとプロジェクト配置モデル

Integration Services (SSIS) サーバーにプロジェクトを配置する場合は、ビュー、ストアドプロシージャ、および SQL Server Management Studio の UI を使用してプロジェクトパラメーターおよびパッケージパラメーターを管理します。詳細については、次の各トピックを参照してください。

パラメーター値

パラメーターに最大 3 つの型の値を割り当てることができます。パッケージ実行が開始されると、パラメーターに 1 つの値が使用され、パラメーターはその最終的なリテラル値に解決されます。

次の表に、値の型の一覧を示します。

値の名前	説明	値の型
実行値	パッケージ実行の特定のインスタンスに割り当てられる値です。この割り当ては他のすべての値をオーバーライドしますが、適用されるのは、パッケージ実行の 1 つのインスタンスのみです。	リテラル
サーバーの値	プロジェクトが Integration Services サーバーに配置された後にプロジェクトのスコープ内にあるパラメーターに割り当てられる値です。この値は、設計上の既定値をオーバーライドします。	リテラルまたは環境変数の参照
設計上の値	SQL Server Data Toolsでプロジェクトを作成または編集するときにパラメーターに割り当てられる値です。この値はプロジェクトと共に保持されます。	リテラル

1 つのパラメーターを使用して、複数のパッケージのプロパティに値を割り当てることができます。 1 つのパッケージのプロパティには、1 つのパラメーターの値のみを割り当てることができます。

実行とパラメーター値

実行とは、パッケージ実行の 1 つのインスタンスを表すオブジェクトです。実行を作成するときに、実行パラメーター値など、パッケージの実行に必要なすべての詳細情報を指定します。既存の実行のパラメーター値を変更することもできます。

実行パラメーター値を明示的に設定すると、その値はその特定の実行インスタンスにのみ適用できます。実行値は、サーバーの値または設計上の値の代わりに使用されます。実行値を明示的に設定せず、サーバーの値が指定されている場合は、サーバーの値が使用されます。

パラメーターが必須とマークされている場合、サーバーの値または実行値をそのパラメーターに指定する必要があります。それ以外の場合、対応するパッケージは実行されません。デザイン時にパラメーターに既定値が設定されていても、プロジェクトが配置されると使用されることはありません。

環境変数

パラメーターが環境変数を参照する場合、その変数のリテラル値は、指定した環境参照を通じて解決され、パラメーターに適用されます。パッケージ実行に使用される最終的なリテラルパラメーター値は、実行パラメーター値と呼ばれます。 [実行] ダイアログボックスを使用して、実行の環境参照を指定します。

プロジェクトパラメーターで環境変数を参照していて、変数のリテラル値を実行時に解決できない場合、設計上の値が使用されます。サーバーの値は使用されません。

パラメーター値に割り当てられている環境変数を表示するには、catalog.object_parameters ビューに対してクエリを実行します。詳細については、「catalog.object_parameters (SSISDB データベース)」を参照してください。

実行パラメーター値の決定

次の Transact-SQL ビューとストアドプロシージャを使用して、パラメーター値を表示および設定できます。

catalog.execution_parameter_values (SSISDB データベース) (表示)
特定の実行における実際のパラメーター値を示します。

catalog.get_parameter_values (SSISDB データベース) (ストアドプロシージャ)
指定されたパッケージと環境参照の実際の値を解決して示します。

catalog.object_parameters (SSISDB データベース) (表示)
設計上の既定値とサーバーの既定値を含め、 Integration Services カタログのすべてのパッケージおよびプロジェクトのパラメーターとプロパティを表示します。

catalog.set_execution_parameter_value (SSISDB データベース)
Integration Services カタログの実行のインスタンスにパラメーターの値を設定します。

の [パッケージの実行] SQL Server Data Tools (SSDT) ダイアログボックスを使用してパラメーター値を変更することもできます。詳細については、「 Execute Package Dialog Box」を参照してください。

dtexec の /Parameter オプションを使用してパラメーター値を変更することもできます。詳細については、「dtexec ユーティリティ」を参照してください。

パラメーターの検証

パラメーター値を解決できない場合、対応するパッケージ実行は失敗します。失敗を回避するために、の [検証] SQL Server Data Tools (SSDT)ダイアログボックスを使用してプロジェクトとパッケージを検証できます。検証を使用すると、すべてのパラメーター値に必要な値が設定されているか、または特定の環境参照で必要な値を解決できるかを確認できます。検証では、その他の一般的なパッケージの問題も確認されます。

詳細については、「 Validate Dialog Box」を参照してください。

パラメーターの例

この例では、 pkgOptions という名前のパラメーターについて説明します。これは、このパラメーターが存在するパッケージのオプションを指定するために使用されます。

設計時に、 SQL Server Data Toolsで作成されたパラメーターには、既定値 1 が割り当てられます。この既定値は、設計上の既定値と呼ばれます。プロジェクトが SSISDB カタログに配置され、このパラメーターに他の値が割り当てられなかった場合は、パッケージの実行中に、 pkgOptions パラメーターに対応するパッケージプロパティに値 1 が割り当てられます。設計上の既定値は、プロジェクトと共にライフサイクル全体で保持されます。

特定のパッケージ実行インスタンスの準備中には、 pkgOptions パラメーターに値 5 が割り当てられます。この値は実行値と呼ばれます。これは、その特定の実行インスタンスのパラメーターにのみ適用されるためです。実行が開始されると、 pkgOptions パラメーターに対応するパッケージプロパティに値 5 が割り当てられます。

パラメーターの作成

プロジェクトパラメーターおよびパッケージパラメーターを作成するには、SQL Server Data Tools (SSDT) を使用します。以下の手順では、パッケージ/プロジェクトパラメーターを作成する方法を詳細に説明します。

注意

以前のバージョンの Integration Services を使用して作成したプロジェクトをプロジェクトの配置モデルに変換する場合は、Integration Services プロジェクト変換ウィザードを使用して、構成に基づいたパラメーターを作成できます。詳細については、「Integration Services (SSIS) プロジェクトとパッケージの配置」を参照してください。

パッケージパラメーターを作成する

SQL Server Data Tools でパッケージを開き、SSIS デザイナーの [パラメーター] タブをクリックします。
ツールバーの [パラメーターの追加] ボタンをクリックします。

一覧で直接、または [プロパティ] ウィンドウを使用して、 [名前] 、 [データ型] 、 [値] 、 [区別する] 、 [必須] の各プロパティに値を入力します。次の表では、これらのプロパティについて説明します。

プロパティ	説明
Name	パラメーターの名前。
データ型	パラメーターのデータ型です。
既定値	設計時に割り当てられたパラメーターの既定値。これは設計時の既定値とも呼ばれます。
重要	機密性の高いパラメーター値はカタログ内で暗号化され、Transact-SQL または SQL Server Management Studio で表示する際は NULL 値として表示されます。
必須	パッケージを実行する前に、設計上の既定値以外の値を指定する必要があります。
説明	管理しやすさを考慮した、パラメーターの説明。 SQL Server Data Tools (SSDT) では、該当するパラメーターウィンドウでパラメーターを選択したときに、Visual Studio プロパティウィンドウでパラメーターの説明を設定します。

注意

プロジェクトをカタログに配置すると、いくつかのプロパティがプロジェクトに関連付けられます。カタログ内のすべてのパラメーターのすべてのプロパティを表示するには、catalog.object_parameters (SSISDB Database) ビューを使用します。

プロジェクトを保存して、変更をパラメーターに保存します。パラメーターの値はプロジェクトファイルに格納されます。

警告

リストで直接編集することも、 [プロパティ] ウィンドウを使用してパラメーターのプロパティの値を変更することもできます。 [削除] \(X) ツールバーボタンを使用して、パラメーターを削除できます。ツールバーの最後のボタンを使用すると、SQL Server Data Tools でパッケージを実行するときにのみ使用されるパラメーターの値を指定できます。

注意

SQL Server Data Tools でプロジェクトを開かずに、パッケージファイルをもう一度開くと、[パラメーター] タブは空になり、無効になります。

プロジェクトパラメーターを作成する

SQL Server Data Tools でプロジェクトを開きます。
ソリューションエクスプローラーで [Project.params] を右クリックして [開く] をクリックするか、または [Project.params] をダブルクリックして開きます。
ツールバーの [パラメーターの追加] ボタンをクリックします。

[名前] 、 [データ型] 、 [値] 、 [区別する] 、 [必須] の各プロパティに値を入力します。

プロパティ	説明
Name	パラメーターの名前。
データ型	パラメーターのデータ型です。
既定値	設計時に割り当てられたパラメーターの既定値。これは設計時の既定値とも呼ばれます。
重要	機密性の高いパラメーター値はカタログ内で暗号化され、Transact-SQL または SQL Server Management Studio で表示する際は NULL 値として表示されます。
必須	パッケージを実行する前に、設計上の既定値以外の値を指定する必要があります。
説明	管理しやすさを考慮した、パラメーターの説明。 SQL Server Data Tools では、該当するパラメーターウィンドウでパラメーターを選択したときに、Visual Studio プロパティウィンドウでパラメーターの説明を設定します。

プロジェクトを保存して、変更をパラメーターに保存します。パラメーター値はプロジェクトファイルの構成に格納されます。プロジェクトファイルを保存して、パラメーター値の変更をディスクにコミットしてください。

警告

リストで直接編集することも、 [プロパティ] ウィンドウを使用してパラメーターのプロパティの値を変更することもできます。 [削除] \(X) ツールバーボタンを使用して、パラメーターを削除できます。ツールバーの最後のボタンを使用すると、 [パラメーター値の管理] ダイアログボックスを開いて、SQL Server Data Tools でパッケージを実行するときにのみ使用されるパラメーターの値を指定できます。

Parameterize Dialog Box

[パラメーター化] ダイアログボックスでは、新規または既存のパラメーターをタスクのプロパティと関連付けることができます。このダイアログボックスを開くには、SSIS デザイナーでタスクまたは [制御フロー] タブを右クリックし、 [パラメーター化] をクリックします。次の一覧では、このダイアログボックスの UI 要素について説明します。パラメーターの詳細については、「 Integration Services (SSIS) パラメーター」を参照してください。

オプション

プロパティ
パラメーターと関連付けるタスクのプロパティを選択します。この一覧には、パラメーター化できるすべてのプロパティが表示されます。

既存のパラメーターを使用する
タスクのプロパティを既存のパラメーターと関連付けるには、このオプションを選択し、ドロップダウンリストからパラメーターを選択します。

パラメーターを使用しない
パラメーターへの参照を削除するには、このオプションを選択します。パラメーターは削除されません。

新しいパラメーターを作成する
タスクのプロパティと関連付ける新しいパラメーターを作成するには、このオプションを選択します。

Name
作成するパラメーターの名前を指定します。

説明
パラメーターの説明を指定します。

Value
パラメーターの既定値を指定します。これは設計上の既定値とも呼ばれ、後で配置時にオーバーライドできます。

スコープ
パラメーターのスコープとして、 [プロジェクト] または [パッケージ] オプションを指定します。プロジェクトパラメーターは、プロジェクトが受け取る外部入力をプロジェクト内の 1 つまたは複数のパッケージに指定するために使用します。パッケージパラメーターを使用すると、パッケージを編集したり再配置したりせずにパッケージ実行を変更できます。

機密
チェックボックスをオンまたはオフにして、パラメーターが機密かどうかを指定します。機密性の高いパラメーター値はカタログ内で暗号化され、Transact-SQL または SQL Server Management Studio で表示する際は NULL 値として表示されます。

必須
パッケージを実行する前に、設計上の既定値以外の値をパラメーターに設定する必要があるかどうかを指定します。

プロジェクトを配置した後にパラメーターの値を設定する

配置ウィザードを使用すると、プロジェクトをカタログに配置するときにサーバーの既定のパラメーター値を設定できます。プロジェクトをカタログに配置した後、SQL Server Management Studio (SSMS) オブジェクトエクスプローラーまたは Transact-SQL を使用して、サーバーの既定値を設定できます。

SSMS オブジェクトエクスプローラーを使用してサーバーの既定値を設定する

[Integration Services] ノードでオブジェクトを選択して右クリックします。
[プロパティ] をクリックして、 [プロジェクトのプロパティ] ダイアログウィンドウを開きます。
[ページの選択] の [パラメーター] をクリックして、パラメーターページを開きます。
[パラメーター] の一覧で目的のパラメーターを選択します。注: [コンテナー] 列を使用すると、プロジェクトパラメーターとパッケージパラメーターを区別できます。
[値] 列で、目的のサーバーの既定のパラメーター値を指定します。

Transact-SQL を使用してサーバーの既定値を設定する

Transact-SQL を使用してサーバーの既定値を設定するには、catalog.set_object_parameter_value (SSISDB データベース) ストアドプロシージャを使用します。現在のサーバーの既定値を表示するには、catalog.object_parameters (SSISDB データベース) ビューをクエリします。サーバーの既定値をクリアするには、catalog.clear_object_parameter_value (SSISDB データベース) ストアドプロシージャを使用します。

Integration Services (SSIS) パッケージおよびプロジェクトパラメーター

パラメーターとパッケージ配置モデル