Azure Data Factory でパラメーター、式、関数を使用する方法

  • [アーティクル]

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

企業向けのオールインワン分析ソリューション、Microsoft Fabric の Data Factory をお試しください。 Microsoft Fabric は、データ移動からデータ サイエンス、リアルタイム分析、ビジネス インテリジェンス、レポートまで、あらゆるものをカバーしています。 無料で新たに試用を開始する方法については、こちらをご覧ください。

このドキュメントでは、Azure Data Factory 内でパラメーター化されたデータ パイプラインを作成する機能を紹介するさまざまな例を使用して、基本的な概念を学習することに主に焦点を当てます。 パラメーター化と動的式は、ADF に追加された注目すべき機能です。これらを使用すると、膨大な時間を節約し、より柔軟な抽出、変換、読み込み (ETL) または 抽出、読み込み、変換 (ELT) ソリューションを実現できます。これにより、ソリューションのメンテナンス コストが大幅に削減され、既存パイプラインへの新機能実装を高速化できるようになります。 これらの利点は、パラメーター化によってハード コーディングの量が最小限に抑えられ、ソリューション内の再利用可能なオブジェクトとプロセスの数が増えるからです。

Azure Data Factory UI とパラメーター

ADF ユーザー インターフェイスで Azure Data Factory パラメーターを初めて使用する場合は、視覚的な説明としてリンクされたサービス用の Data Factory UI とパラメーターを備えたメタデータ ドリブン パイプライン用の Data Factory UI に関するページをご覧ください。

パラメーターと式の概念

パラメーターを使用して、パイプライン、データセット、リンクされたサービス、およびデータ フローに外部の値を渡すことができます。 パラメーターは、リソースに渡されると変更できません。 リソースをパラメーター化することで、毎回異なる値を使用してリソースを再利用できます。 パラメーターは、個別に、または式の一部として使用できます。 定義内の JSON 値には、実行時に評価されるリテラルまたは式を指定できます。

次に例を示します。

"name": "value"

or

"name": "@pipeline().parameters.password"

式は、JSON string 値内の任意の場所で使うことができ、常に別の JSON 値になります。 ここで、password は式のパイプライン パラメーターです。 JSON 値が式である場合は、アットマーク (@) を削除することによって式の本体が抽出されます。 @ で始まるリテラル文字列が必要な場合は、@@ を使用して文字列をエスケープする必要があります。 式の評価方法の例を次に示します。

JSON 値 結果
"parameters" 文字 "parameters" が返されます。
"parameters [1]" 文字 "parameters[1]" が返されます。
\"\@\" を含む 1 文字の文字列が返されます。
" \@\" を含む 2 文字の文字列が返されます。

また、式が @{ ... } にラップされる文字列補間と呼ばれる機能を使用して、式を文字列の内部に指定することもできます。 例: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

文字列補間を使用すると、結果は常に文字列になります。 myNumber を 42 として、myString を foo として定義したとします。

JSON 値 結果
"@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} が返されます。

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

複合式の例

次の例は、アクティビティの出力の詳細サブフィールドを参照する複雑な例を示しています。 サブフィールドと評価されるパイプライン パラメーターを参照するには、ドット (.) 演算子ではなく、[] 構文を使用します (subfield1 と subfield2 の場合と同様)

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

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

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

{ 
  "type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
  "name": "@{toUpper('myData')}"
}

動的コンテンツ エディターは、上記のコンテンツを式 "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}" に変換します。 この式の結果は、次に示す JSON 形式の文字列になります。

{
  "type": "Table",
  "name": "MYDATA"
}

パラメーターが使用されるデータセット

次の例では、BlobDataset は path という名前のパラメーターを受け取ります。 その値は、dataset().path という式を使用して folderPath プロパティの値を設定するために使用されます。

{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "@dataset().path"
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}

パラメーターが使用されるパイプライン

次の例では、パイプラインは inputPath パラメーターと outputPath パラメーターを受け取ります。 パラメーター化された BLOB データセットの path は、これらのパラメーターの値を使用して設定されます。 ここで使用する構文は pipeline().parameters.parametername です。

{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "inputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.inputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.outputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                }
            }
        ],
        "parameters": {
            "inputPath": {
                "type": "String"
            },
            "outputPath": {
                "type": "String"
            }
        }
    }
}

式の中で関数を呼び出す

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

文字列関数

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

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

コレクション関数

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

コレクション関数 タスク
contains コレクションに特定の項目があるかどうかを確認します。
empty コレクションが空かどうかを調べます。
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 指定された範囲からランダムな整数を返します。
range 指定した整数から始まる整数の配列を返します。
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 現在のタイムスタンプを文字列として返します。

実践のための詳細な例

パラメーターを備えた Azure Data Factory コピー パイプラインの詳細

このAzure Data Factory コピー パイプラインでのパラメーター受け渡しに関するチュートリアルでは、パイプラインとアクティビティの間、およびアクティビティ間でパラメーターを渡す方法について説明します。

パラメーターが使用されるマッピング データ フロー パイプラインの詳細

データ フローでパラメーターを使用する方法の包括的な例については、パラメーターを備えたマッピング データ フローに関するページをご覧ください。

パラメーターを備えたメタデータ ドリブン パイプラインの詳細

パラメーターを使用してメタデータ ドリブン パイプラインを設計する方法の詳細については、パラメーターを備えたメタデータ ドリブン パイプラインに関するページをご覧ください。 これは、パラメーターの一般的なユース ケースです。

関連するコンテンツ

式で使用できるシステム変数の一覧については、「システム変数」を参照してください。