英語で読む

次の方法で共有


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}"

文字列補間を使用すると、結果は常に文字列になります。 たとえば、myNumber42 として、myStringfoo として定義した場合、以下のようになります。

パラメーター値 結果
"@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} が返されます。

式でのパラメーターの使用例

パラメーターの作成と使用

パラメーターを作成するには、パイプライン エディター キャンバスの背景を選択し、下部にあるプロパティ ウィンドウの [パラメーター] タブを選択します。 [+ 新規] ボタンを選択してパイプラインに新しいパラメーターを追加し、名前、データ型、既定値を指定します。

Screenshot showing the Parameters editor on the properties pages for a pipeline.

これで、動的コンテンツがサポートされているパイプライン内の任意の場所でパラメーターを使用できます。 この例では、パラメーターを使用して、Copy アクティビティのプロパティ ページの [ソース] タブにある Lakehouse データ ストアの名前を動的に指定しています。

Screenshot showing the Source tab of a copy activity's property pages, highlighting the Add dynamic content option.

[動的なコンテンツの追加] ウィンドウが表示され、パラメーター、システム変数関数、パイプライン変数など、あらゆる種類の動的コンテンツを指定できます。 この例では、前に定義したパラメーターが選択され、パラメーターを参照する正しい式が動的コンテンツ ウィンドウに自動的に設定されています。

Screenshot showing the Add dynamic content window with a pipeline parameter selected.

複合式の例

次の例は、アクティビティの出力の詳細サブフィールドを参照する複雑な例を示しています。 サブフィールドと評価されるパイプライン パラメーターを参照するには、ドット (.) 演算子ではなく、[] 構文を使用します (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() の後の疑問符に注意してください

注意

トリガー関連の日付/時刻のシステム変数 (パイプラインとトリガーの両方のスコープ) は、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 現在のタイムスタンプを文字列として返します。