Microsoft Fabric の Data Factory 用パラメーター
このドキュメントでは、Fabric の Data Factory のパイプラインでパラメーターを使用する方法について説明します。
Fabric の Data Factory のパイプラインでパラメーター、式、関数を使用する方法
このドキュメントでは、Fabric の Data Factory 内でパラメーター化されたデータ パイプラインを作成する機能を紹介するさまざまな例を使用して、基本的な概念を学習することに焦点を当てます。 パラメーター化と動的式は、膨大な時間を節約し、より柔軟な抽出、変換、読み込み (ETL) または抽出、読み込み、変換 (ELT) ソリューションを実現できます。これにより、ソリューションのメンテナンス コストが大幅に削減され、既存パイプラインへの新機能実装を高速化できるようになります。 これらの利点は、パラメーター化によってハード コーディングの量が最小限に抑えられ、ソリューション内の再利用可能なオブジェクトとプロセスの数が増えるからです。
パラメーターと式の概念
パラメーターを使用して、外部の値をパイプラインに渡すことができます。 パラメーターは、リソースに渡されると変更できません。 リソースをパラメーター化することで、毎回異なる値を使用してリソースを再利用できます。 パラメーターは、個別に、または式の一部として使用できます。 定義内のパラメーター値には、実行時に評価されるリテラルまたは式を指定できます。
式は、文字列値内の任意の場所に配置でき、常に別の文字列値を生成します。 ここで、password は式のパイプライン パラメーターです。 パラメーター値が式である場合は、アットマーク (@) を削除することによって式の本体が抽出されます。 @ で始まるリテラル文字列が必要な場合は、@@ を使用して文字列をエスケープする必要があります。 式の評価方法の例を次に示します。
| パラメーター値 | 結果 |
|---|---|
| "parameters" | 文字 "parameters" が返されます。 |
| "parameters [1]" | 文字 "parameters[1]" が返されます。 |
| "@@" | \"\@\" を含む 1 文字の文字列が返されます。 |
| " @" | " \@\" を含む 2 文字の文字列が返されます。 |
また、式が @{ ... } にラップされる文字列補間と呼ばれる機能を使用して、式を文字列の内部に指定することもできます。 たとえば、次の文字列には、パラメーター値とリテラル文字列値が含まれています。
"First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"
文字列補間を使用すると、結果は常に文字列になります。 たとえば、myNumber を 42 として、myString を foo として定義した場合、以下のようになります。
| パラメーター値 | 結果 |
|---|---|
| "@pipeline().parameters.myString" | foo が文字列として返されます。 |
| "@{pipeline().parameters.myString}" | foo が文字列として返されます。 |
| "@pipeline().parameters.myNumber" | 42 が "数値" として返されます。 |
| "@{pipeline().parameters.myNumber}" | 42 が "string" として返されます。 |
| "Answer is: @{pipeline().parameters.myNumber}" | string Answer is: 42 が返されます。 |
| "@concat('Answer is: ', string(pipeline().parameters.myNumber))" | string Answer is: 42 が返されます。 |
| "Answer is: @@{pipeline().parameters.myNumber}" | string Answer is: @{pipeline().parameters.myNumber} が返されます。 |
式でのパラメーターの使用例
パラメーターの作成と使用
パラメーターを作成するには、パイプライン エディター キャンバスの背景を選択し、下部にあるプロパティ ウィンドウの [パラメーター] タブを選択します。 [+ 新規] ボタンを選択してパイプラインに新しいパラメーターを追加し、名前、データ型、既定値を指定します。
これで、動的コンテンツがサポートされているパイプライン内の任意の場所でパラメーターを使用できます。 この例では、パラメーターを使用して、Copy アクティビティのプロパティ ページの [ソース] タブにある Lakehouse データ ストアの名前を動的に指定しています。
[動的なコンテンツの追加] ウィンドウが表示され、パラメーター、システム変数、関数、パイプライン変数など、あらゆる種類の動的コンテンツを指定できます。 この例では、前に定義したパラメーターが選択され、パラメーターを参照する正しい式が動的コンテンツ ウィンドウに自動的に設定されています。
複合式の例
次の例は、アクティビティの出力の詳細サブフィールドを参照する複雑な例を示しています。 サブフィールドと評価されるパイプライン パラメーターを参照するには、ドット (.) 演算子ではなく、[] 構文を使用します (subfield1 と subfield2 の場合と同様)
@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*
動的コンテンツ エディター
編集が完了すると、動的コンテンツ エディターによってコンテンツ内の文字が自動的にエスケープされます。 たとえば、コンテンツ エディター内の次のコンテンツは、式関数を使用する文字列補間です。
@{toUpper('myData')}
動的コンテンツ エディターは、上記のコンテンツを次の式に変換します。
MYDATA
式での関数と変数の使用
式の中で関数を呼び出したり、変数を使用したりすることができます。 以降のセクションでは、式で使用できる関数に関する情報を提供します。
パイプライン スコープ変数
これらのシステム変数は、パイプライン JSON 内の任意の場所で参照できます。
| 変数名 | 説明 |
|---|---|
| @pipeline().DataFactory | パイプライン実行が実行されているデータまたは Synapse ワークスペースの名前 |
| @pipeline().Pipeline | パイプラインの名前 |
| @pipeline().RunId | 特定のパイプライン実行の ID |
| @pipeline().TriggerId | パイプラインを呼び出したトリガーの ID |
| @pipeline().TriggerName | パイプラインを呼び出したトリガーの名前 |
| @pipeline().TriggerTime | パイプラインを呼び出したトリガーの実行時刻。 これは、トリガーがパイプライン実行を呼び出すために実際に起動した時刻であり、トリガーのスケジュールされた時刻とはやや異なる場合があります。 |
| @pipeline().GroupId | パイプラインの実行が属するグループの ID。 |
| @pipeline()?.TriggeredByPipelineName | パイプラインの実行をトリガーするパイプラインの名前。 ExecutePipeline アクティビティによってパイプラインの実行がトリガーされる場合に関係します。 その他の状況で使用された場合は、Null に評価されます。 @pipeline() の後の疑問符に注意してください |
| @pipeline()?.TriggeredByPipelineRunId | パイプラインの実行をトリガーするパイプラインの実行 ID。 ExecutePipeline アクティビティによってパイプラインの実行がトリガーされる場合に関係します。 その他の状況で使用された場合は、Null に評価されます。 @pipeline() の後の疑問符に注意してください |
Note
トリガー関連の日付/時刻のシステム変数 (パイプラインとトリガーの両方のスコープ) は、ISO 8601 形式で UTC 日付を返します (例: 2017-06-01T22:20:00.4061448Z)。
文字列関数
文字列を処理するには、以下の文字列関数および一部のコレクション関数も使用できます。 文字列関数は文字列でのみ機能します。
| 文字列関数 | タスク |
|---|---|
| concat | 2 つ以上の文字列を結合し、結合された文字列を返します。 |
| endsWith | 文字列が指定された部分文字列で終わっているかどうかを調べます。 |
| guid | 文字列としてグローバル一意識別子 (GUID) を生成します。 |
| indexOf | 部分文字列の開始位置を返します。 |
| lastIndexOf | 部分文字列の最後の出現箇所の開始位置を返します。 |
| replace | 部分文字列を指定した文字列で置換し、更新された文字列を返します。 |
| split | 元の文字列で指定された区切り文字に基づいたより大きい文字列から、コンマで区切られた部分文字列を含む配列を返します。 |
| startsWith | 文字列が特定の部分文字列で始まっているかどうかを調べます。 |
| substring | 文字列から、指定された位置から始まる文字を返します。 |
| toLower | 小文字の形式で文字列を返します。 |
| toUpper | 大文字の形式で文字列を返します。 |
| trim | 文字列から先頭と末尾の空白を削除し、更新された文字列を返します。 |
コレクション関数
コレクション (通常は配列や文字列、場合によってはディクショナリ) を操作するには、以下のコレクション関数を使用できます。
| コレクション関数 | タスク |
|---|---|
| contains | コレクションに特定の項目があるかどうかを確認します。 |
| 空 | コレクションが空かどうかを調べます。 |
| first | コレクションから最初の項目を返します。 |
| intersection | 指定したコレクションすべてに共通する項目 "のみ" を含むコレクションを返します。 |
| join | 配列の "すべて" の項目を含み、指定された区切り記号で各項目が区切られた、文字列を返します。 |
| last | コレクションから最後の項目を返します。 |
| length | 文字列または配列内の項目の数を返します。 |
| skip | コレクションの先頭から項目を削除し、"他のすべて" の項目を返します。 |
| take | コレクションの先頭から項目を返します。 |
| union | 指定した複数のコレクションの "すべての" 項目を含む 1 つのコレクションを返します。 |
論理関数
これらの関数は条件の内部で役立ち、任意の種類のロジックを評価するために使用できます。
| 論理比較関数 | タスク |
|---|---|
| and | すべての式が true かどうかを調べます。 |
| equals | 両方の値が等しいかどうかを調べます。 |
| greater | 1 番目の値が 2 番目の値より大きいかどうかを調べます。 |
| greaterOrEquals | 1 番目の値が 2 番目の値以上かどうかを調べます。 |
| if | 式が true か false かを調べます。 結果に基づき、指定された値を返します。 |
| less | 1 番目の値が 2 番目の値より小さいかどうかを調べます。 |
| lessOrEquals | 1 番目の値が 2 番目の値以下かどうかを調べます。 |
| not | 式が false かどうかを調べます。 |
| or | 少なくとも 1 つの式が true かどうかを調べます。 |
変換関数
これらの関数は、言語の各ネイティブ型の間の変換に使われます。
- string
- 整数 (integer)
- float
- boolean
- arrays
- dictionaries
| 変換関数 | タスク |
|---|---|
| array | 指定した 1 つの入力から配列を返します。 複数の入力の場合は、createArray をご覧ください。 |
| base64 | 文字列の base64 エンコード バージョンを返します。 |
| base64ToBinary | base64 エンコード文字列のバイナリ バージョンを返します。 |
| base64ToString | base64 エンコード文字列の文字列バージョンを返します。 |
| [バイナリ] | 入力値のバイナリ バージョンを返します。 |
| bool | 入力値のブール値バージョンを返します。 |
| coalesce | 1 つまたは複数のパラメーターから、最初の null 以外の値を返します。 |
| createArray | 複数の入力から配列を作成して返します。 |
| dataUri | 入力値のデータ URI を返します。 |
| dataUriToBinary | データ URI のバイナリ バージョンを返します。 |
| dataUriToString | データ URI の文字列バージョンを返します。 |
| decodeBase64 | base64 エンコード文字列の文字列バージョンを返します。 |
| decodeDataUri | データ URI のバイナリ バージョンを返します。 |
| decodeUriComponent | エスケープ文字をデコード バージョンに置き換えた文字列を返します。 |
| encodeUriComponent | URL の安全でない文字をエスケープ文字に置き換えた文字列を返します。 |
| float | 入力値の浮動小数点数を返します。 |
| int | 文字列の整数バージョンを返します。 |
| json | 文字列または XML に対する JSON (JavaScript Object Notation) 型の値またはオブジェクトを返します。 |
| string | 入力値の文字列バージョンを返します。 |
| uriComponent | URL の安全でない文字がエスケープ文字に置き換えられた、入力値の URI エンコード バージョンを返します。 |
| uriComponentToBinary | URI エンコード文字列のバイナリ バージョンを返します。 |
| uriComponentToString | URI エンコード文字列の文字列バージョンを返します。 |
| xml | 文字列の XML バージョンを返します。 |
| xpath | XML で XPath (XML Path Language) 式と一致するノードまたは値を調べて、一致するノードまたは値を返します。 |
算術関数
これらの関数は、integer 型および float 型の値に使うことができます。
| 算術関数 | タスク |
|---|---|
| add | 2 つの数値を加算した結果を返します。 |
| div | 2 つの数値を除算した結果を返します。 |
| max | 数値のセットまたは配列から最大の値を返します。 |
| min | 数値のセットまたは配列から最小の値を返します。 |
| mod | 2 つの数値を除算した剰余を返します。 |
| mul | 2 つの数値を乗算した積を返します。 |
| rand | 指定された範囲からランダムな整数を返します。 |
| 範囲 | 指定した整数から始まる整数の配列を返します。 |
| sub | 1 番目の数値から 2 番目の数値を減算して、結果を返します。 |
データ関数
| 日付または時刻の関数 | タスク |
|---|---|
| addDays | タイムスタンプに日数を加算します。 |
| addHours | タイムスタンプに時間数を加算します。 |
| addMinutes | タイムスタンプに分数を加算します。 |
| addSeconds | タイムスタンプに秒数を加算します。 |
| addToTime | タイムスタンプに時間単位数を加算します。 getFutureTime もご覧ください。 |
| convertFromUtc | タイムスタンプを協定世界時 (UTC) からターゲット タイム ゾーンに変換します。 |
| convertTimeZone | タイムスタンプをソース タイム ゾーンからターゲット タイム ゾーンに変換します。 |
| convertToUtc | タイムスタンプをソース タイム ゾーンから協定世界時 (UTC) に変換します。 |
| dayOfMonth | タイムスタンプから月コンポーネントの日付を返します。 |
| dayOfWeek | タイムスタンプから曜日を返します。 |
| dayOfYear | タイムスタンプから年の何日目かを返します。 |
| formatDateTime | 任意の形式でタイムスタンプを文字列として返します。 |
| getFutureTime | 現在のタイムスタンプに指定した時刻単位を加えて返します。 addToTime もご覧ください。 |
| getPastTime | 現在のタイムスタンプから指定した時刻単位を引いて返します。 subtractFromTime もご覧ください。 |
| startOfDay | タイムスタンプの日の開始日時を返します。 |
| startOfHour | タイムスタンプの時刻の開始を返します。 |
| startOfMonth | タイムスタンプの月の開始を返します。 |
| subtractFromTime | タイムスタンプから時間単位数を減算します。 getPastTime もご覧ください。 |
| ticks | 指定したタイムスタンプの ticks プロパティの値を返します。 |
| utcNow | 現在のタイムスタンプを文字列として返します。 |