Microsoft Fabric の Data Factory のパラメーター

このガイドでは、Fabric の Data Factory パイプラインでパラメーターを使用する方法について説明します。 ワークフローの柔軟性を高め、管理しやすくする簡単な方法です。

Fabric の Data Factory のパイプラインでパラメーター、式、関数を使用する方法

このガイドでは、Data Factory for Fabric でパラメーター化されたパイプラインを作成する方法の基本について説明します。その過程で明確な例を使用します。 パラメーターと動的式を使用すると、時間を大幅に節約し、柔軟な ETL (抽出、変換、読み込み) または ELT (抽出、読み込み、変換) ソリューションを構築できます。 これらの手法はハード コーディングを削減し、オブジェクトとプロセスを再利用するのに役立ちます。これにより、パイプラインの維持と新機能のロールアウトが簡単になります。

パラメーターと式の概念

パラメーターを使用して、外部値をパイプラインに渡すことができます。 パラメーターが設定されると、そのパラメーターは実行全体で同じままであり、変更することはできません。 パラメーターを使用すると、毎回異なる値を持つ同じパイプラインを再利用できます。 これらは独自の式または式内で使用できます。これらの値は、パイプラインの実行時に固定または計算できます。

式は文字列値の任意の場所に移動し、常に別の文字列値を返すことができます。 たとえば、 @passwordを使用する場合、パイプラインはパスワードをパラメーターとして扱います。 値が式の場合は、@ を削除して実際のコンテンツを取得します。 @で始まる文字列が必要な場合は、「@@」と入力するだけでエスケープできます。 これが実際にどのように機能するかを示す例をいくつか次に示します。

パラメーター値	Result
"parameters"	文字 "parameters" が返されます。
"parameters[1]"	文字 "parameters[1]" が返されます。
"@@"	\"\@\" を含む 1 文字の文字列が返されます。
" @"	" \@\" を含む 2 文字の文字列が返されます。

また、式が にラップされる@{ ... }と呼ばれる機能を使用して、式を文字列の内部に指定することもできます。 たとえば、次の文字列にはパラメーター値とリテラル文字列値が含まれます。

"名: @{pipeline().parameters.firstName} 姓: @{pipeline().parameters.lastName}"

文字列補間を使用すると、結果は常に文字列になります。 たとえば、myNumberを 42 として定義し、myStringとしてfooした場合は、次のようになります。

パラメーター値	Result
"@pipeline().parameters.myString"	foo が文字列として返されます。
"@{pipeline().parameters.myString}"	foo が文字列として返されます。
"@pipeline().parameters.myNumber"	42 が "数値" として返されます。
"@{pipeline().parameters.myNumber}"	42 が "string" として返されます。
答えは:@{pipeline().parameters.myNumber}	string Answer is: 42 が返されます。
"@concat('Answer is: ', string(pipeline().parameters.myNumber)) // これはパラメーターmyNumberの値を文字列で連結した結果です。"	string Answer is: 42 が返されます。
答えは: @@{pipeline().parameters.myNumber}	string Answer is: @{pipeline().parameters.myNumber} が返されます。

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

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

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

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

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

接続をパラメーター化する方法

パイプラインで接続をパラメーター化するには、動的に置き換える接続 GUID を使用する必要があります。

1. パイプライン内の接続を動的に変更する前に、設定する接続の GUID を取得する必要があります
2. [設定] に移動 |接続とゲートウェイを管理する
3. 接続の名前を見つけて、接続名の横にある elipses をクリックします
4. [設定] を選択し、接続 ID をコピーします
5. 文字列パラメーターを使用して、動的式で使用するためにそのパラメーターに GUID を貼り付けます

複合式の例

次の例は、アクティビティ出力の深いサブフィールドを参照する複雑な例を示しています。 サブフィールドに評価されるパイプライン パラメーターを参照するには、dot(.) 演算子の代わりに [] 構文を使用します (subfield1 および subfield2 と同様)。

@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*

動的コンテンツ エディター

編集が完了すると、動的コンテンツ エディターによってコンテンツ内の文字が自動的にエスケープされます。 たとえば、コンテンツ エディターの次のコンテンツは、式関数を使用した文字列補間です。

@{toUpper('myData')}

動的コンテンツ エディターは、前のコンテンツを次の式に変換します。

MYDATA

式での関数と変数の使用

関数を呼び出し、式内で変数を使用できます。 以降のセクションでは、式で使用できる関数に関する情報を提供します。

パイプライン スコープ変数

これらのシステム変数は、パイプライン JSON 内の任意の場所で参照できます。

変数名	Description
@pipeline().DataFactory	パイプライン実行が実行されているデータまたは Synapse ワークスペースの名前
@pipeline().Pipeline	パイプラインの名前
@pipeline().RunId	特定のパイプライン実行の ID
@pipeline().TriggerId	パイプラインを呼び出したトリガーの ID
@pipeline().TriggerName	パイプラインを呼び出したトリガーの名前
@pipeline().TriggerTime	パイプラインを呼び出したトリガーの実行時刻。 これは、トリガーが 実際に 発生してパイプラインの実行を呼び出す時刻であり、トリガーのスケジュールされた時刻とは若干異なる場合があります。
@pipeline().GroupId	パイプラインの実行が属するグループの ID。 Microsoft Fabric では、"グループ" とは、一緒に管理できる関連リソースのコレクションを指します。 グループは、リソースへのアクセスを整理および制御するために使用され、複数のパイプラインにわたるアクセス許可の管理とアクティビティの監視が容易になります。
@pipeline()?.TriggeredByPipelineName	パイプラインの実行をトリガーするパイプラインの名前。 ExecutePipeline アクティビティによってパイプラインの実行がトリガーされる場合に関係します。 他の状況で使用する場合は Null に評価されます。 @pipeline() の後の疑問符に注意してください
@pipeline()?.TriggeredByPipelineRunId	パイプラインの実行をトリガーするパイプラインの実行 ID。 ExecutePipeline アクティビティによってパイプラインの実行がトリガーされる場合に関係します。 他の状況で使用する場合は Null に評価されます。 @pipeline() の後の疑問符に注意してください

Note

トリガー関連の日付/時刻のシステム変数 (パイプラインとトリガーの両方のスコープ) は、ISO 8601 形式で UTC 日付を返します (例: 2017-06-01T22:20:00.4061448Z)。

文字列関数

文字列を処理するには、以下の文字列関数および一部のコレクション関数も使用できます。 文字列関数は文字列でのみ機能します。

String 関数	Task
concat	2 つ以上の文字列を結合し、結合された文字列を返します。
endsWith	文字列が指定された部分文字列で終わっているかどうかを調べます。
guid	文字列としてグローバル一意識別子 (GUID) を生成します。
indexOf	部分文字列の開始位置を返します。
lastIndexOf	部分文字列の最後の出現箇所の開始位置を返します。
replace	部分文字列を指定した文字列で置換し、更新された文字列を返します。
split	元の文字列で指定された区切り文字に基づいたより大きい文字列から、コンマで区切られた部分文字列を含む配列を返します。
startsWith	文字列が特定の部分文字列で始まっているかどうかを調べます。
substring	文字列から、指定された位置から始まる文字を返します。
toLower	小文字の形式で文字列を返します。
toUpper	大文字の形式で文字列を返します。
trim	文字列から先頭と末尾の空白を削除し、更新された文字列を返します。

コレクション関数

コレクション (通常は配列や文字列、場合によってはディクショナリ) を操作するには、以下のコレクション関数を使用できます。

コレクション関数	Task
contains	コレクションに特定の項目があるかどうかを確認します。
empty	コレクションが空かどうかを調べます。
first	コレクションから最初の項目を返します。
intersection	指定したコレクションすべてに共通する項目 "のみ" を含むコレクションを返します。
join	配列の "すべて" の項目を含み、指定された区切り記号で各項目が区切られた、文字列を返します。
last	コレクションから最後の項目を返します。
length	文字列または配列内の項目の数を返します。
skip	コレクションの先頭から項目を削除し、"他のすべて" の項目を返します。
take	コレクションの先頭から項目を返します。
union	指定した複数のコレクションの "すべての" 項目を含む 1 つのコレクションを返します。

論理関数

これらの関数は条件の内部で役立ち、任意の種類のロジックを評価するために使用できます。

論理比較関数	Task
and	すべての式が true かどうかを調べます。
equals	両方の値が等しいかどうかを調べます。
greater	1 番目の値が 2 番目の値より大きいかどうかを調べます。
greaterOrEquals	1 番目の値が 2 番目の値以上かどうかを調べます。
if	式が true か false かを調べます。 結果に基づき、指定された値を返します。
less	1 番目の値が 2 番目の値より小さいかどうかを調べます。
lessOrEquals	1 番目の値が 2 番目の値以下かどうかを調べます。
not	式が false かどうかを調べます。
or	少なくとも 1 つの式が true かどうかを調べます。

変換関数

これらの関数は、言語の各ネイティブ型の間の変換に使われます。

• 文字列
• 整数
• float
• boolean
• arrays
• dictionaries

変換関数	Task
array	指定した 1 つの入力から配列を返します。 複数の入力の場合は、createArray をご覧ください。
base64	文字列の base64 エンコード バージョンを返します。
base64ToBinary	base64 エンコード文字列のバイナリ バージョンを返します。
base64ToString	base64 エンコード文字列の文字列バージョンを返します。
binary	入力値のバイナリ バージョンを返します。
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 型の値に使うことができます。

算術関数	Task
add	2 つの数値を加算した結果を返します。
div	2 つの数値を除算した結果を返します。
max	数値のセットまたは配列から最大の値を返します。
min	数値のセットまたは配列から最小の値を返します。
mod	2 つの数値を除算した剰余を返します。
mul	2 つの数値を乗算した積を返します。
rand	指定された範囲からランダムな整数を返します。
range	指定した整数から始まる整数の配列を返します。
sub	1 番目の数値から 2 番目の数値を減算して、結果を返します。

データ関数

日付または時刻の関数	Task
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	現在のタイムスタンプを文字列として返します。

関連コンテンツ

• 式言語