Azure Data Factory または Synapse Analytics で Script アクティビティを使用してデータを変換する

[アーティクル]
10/20/2023

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

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

Data Factory または Synapse パイプラインでデータ変換アクティビティを使用して、生データを予測や分析情報に変換して処理します。 Script アクティビティは、パイプラインでサポートされる変換アクティビティの 1 つです。この記事は、データ変換とサポートされている変換アクティビティの概要を説明する、データ変換に関する記事に基づいています。

Script アクティビティを使用すると、データ操作言語 (DML) とデータ定義言語 (DDL) を使用して一般的な操作を実行できます。 INSERT、UPDATE、DELETE、SELECT などの DML ステートメントを使用すると、ユーザーはデータベースのデータを挿入、変更、削除、および取得できます。 CREATE、ALTER、DROP などの DDL ステートメントを使用すると、データベースマネージャーは、テーブル、インデックス、ユーザーなどのデータベースオブジェクトを作成、変更、削除できます。

Script アクティビティを使用して、社内または Azure 仮想マシン (VM) 上の次のいずれかのデータストアで SQL スクリプトを呼び出すことができます。

Azure SQL データベース
Azure Synapse Analytics
SQL Server データベース SQL Server を使用している場合は、データベースをホストしているコンピューター、またはデータベースにアクセスできる別のコンピューターにセルフホステッド統合ランタイムをインストールします。セルフホステッド統合ランタイムは、管理された確実な方法でオンプレミスまたは Azure VM 上のデータソースをクラウドサービスに接続するコンポーネントです。詳細については、セルフホステッド統合ランタイムに関する記事をご覧ください。
Oracle
Snowflake

このスクリプトには、1 つの SQL ステートメントまたは順に実行される複数の SQL ステートメントを含めることができます。スクリプトタスクは、次の目的で使用できます。

データを挿入する準備として、テーブルを切り捨てます。
テーブル、ビューなどのデータベースオブジェクトを、作成、変更、および削除します。
データの読み込みを行う前にファクトテーブルとディメンションテーブルを再作成します。
ストアドプロシージャを実行します。 SQL ステートメントで、一時テーブルから結果を返すストアドプロシージャが呼び出される場合は、WITH RESULT SETS オプションを使用して結果セットのメタデータを定義します。
クエリから返された行セットを、下流で使用するためのアクティビティ出力として保存します。

構文の詳細

Script アクティビティを定義するための JSON 形式を次に示します。

{ 
   "name": "<activity name>", 
   "type": "Script", 
   "linkedServiceName": { 
      "referenceName": "<name>", 
      "type": "LinkedServiceReference" 
    }, 
   "typeProperties": { 
      "scripts" : [ 
         { 
            "text": "<Script Block>", 
            "type": "<Query> or <NonQuery>", 
            "parameters":[ 
               { 
                  "name": "<name>", 
                  "value": "<value>", 
                  "type": "<type>", 
                  "direction": "<Input> or <Output> or <InputOutput>", 
                  "size": 256 
               }, 
               ... 
            ] 
         }, 
         ... 
      ],     
         ... 
         ] 
      }, 
      "scriptBlockExecutionTimeout": "<time>",  
      "logSettings": { 
         "logDestination": "<ActivityOutput> or <ExternalStore>", 
         "logLocationSettings":{ 
            "linkedServiceName":{ 
               "referenceName": "<name>", 
               "type": "<LinkedServiceReference>" 
            }, 
            "path": "<folder path>" 
         } 
      } 
    } 
}

次の表に、JSON のプロパティを示します。

プロパティ名	説明	必須
name	アクティビティの名前。	はい
type	アクティビティの種類。"Script" に設定します。	はい
typeProperties	Script アクティビティを構成するプロパティを指定します。	はい
linkedServiceName	スクリプトが実行されるターゲットデータベース。これは、リンクサービスへの参照である必要があります。	はい
スクリプト	スクリプトを表すオブジェクトの配列。	いいえ
scripts.text	クエリブロックのプレーンテキスト。	いいえ
scripts.type	クエリブロックの種類。 Query または NonQuery を指定できます。既定値: Query。	いいえ
scripts.parameter	スクリプトのパラメーターの配列。	いいえ
scripts.parameter.name	パラメーターの名前。	いいえ
scripts.parameter.value	パラメーターの値。	いいえ
scripts.parameter.type	パラメーターのデータ型です。型は論理型で、各コネクタの型マッピングに従います。	いいえ
scripts.parameter.direction	パラメーターの方向。 Input、Output、InputOutput を指定できます。方向が Output の場合、この値は無視されます。 ReturnValue 型はサポートされていません。 SP の戻り値を出力パラメーターに設定して取得します。	いいえ
scripts.parameter.size	パラメーターの最大サイズ。 string/byte[] 型の Output/InputOutput 方向パラメーターにのみ適用されます。	いいえ
scriptBlockExecutionTimeout	スクリプトブロックの実行操作がタイムアウトするまでの待機時間。	いいえ
logSettings	出力ログを格納する設定。指定しない場合、スクリプトログは無効になります。	いいえ
logSettings.logDestination	ログの出力先。 ActivityOutput または ExternalStore を指定できます。既定値: ActivityOutput。	いいえ
logSettings.logLocationSettings	logDestination が ExternalStore の場合のターゲットの場所の設定。	いいえ
logSettiongs.logLocationSettings.linkedServiceName	ターゲットの場所のリンクサービス。 BLOB ストレージのみがサポートされています。	いいえ
logSettings.logLocationSettings.path	ログを格納するフォルダーパス。	いいえ

アクティビティの出力

サンプル出力:

{ 
    "resultSetCount": 2, 
    "resultSets": [ 
        { 
            "rowCount": 10, 
            "rows":[ 
                { 
                    "<columnName1>": "<value1>", 
                    "<columnName2>": "<value2>", 
                    ... 
                } 
            ] 
        }, 
        ... 
    ], 
    "recordsAffected": 123, 
    "outputParameters":{ 
        "<parameterName1>": "<value1>", 
        "<parameterName2>": "<value2>" 
    }, 
    "outputLogs": "<logs>", 
    "outputLogsLocation": "<folder path>", 
    "outputTruncated": true, 
    ... 
}

プロパティ名	説明	条件
resultSetCount	スクリプトによって返される結果セットの数。	常に表示する
resultSets	すべての結果セットが格納されている配列。	常に表示する
resultSets.rowCount	結果セット内の合計行数。	常に表示する
resultSets.rows	結果セット内の行の配列。	常に表示する
recordsAffected	スクリプトによって影響を受けた行の数。	scriptType が NonQuery の場合。
outputParameters	スクリプトの出力パラメーター。	パラメーターの型が Output または InputOutput の場合。
outputLogs	スクリプトによって書き込まれたログ (print ステートメントなど)。	コネクタが log ステートメントをサポートし、enableScriptLogs が true で logLocationSettings が指定されていない場合。
outputLogsPath	ログファイルの完全なパス。	enableScriptLogs が true で、logLocationSettings が指定されている場合。
outputTruncated	出力が制限を超えて切り捨てられたかどうかを示すインジケーター。	出力が制限を超えた場合。

Note

出力は、スクリプトブロックが実行されるたび収集されます。最終的な出力は、すべてのスクリプトブロック出力のマージされた結果です。異なるスクリプトブロック内の同じ名前の出力パラメーターは上書きされます。
出力にはサイズ/行数の制限があり、出力は logs -> parameters -> rows の順序で切り捨てられます。これは 1 つのスクリプトブロックに適用されます。つまり、次のスクリプトブロックの出力行により、前のログが削除されることはありません。
ログによって発生したエラーによりアクティビティが失敗することはありません。
アクティビティ出力 resultSets をダウンストリームアクティビティで使用する方法については、Lookup アクティビティの結果に関するドキュメントを参照してください。
ログ記録のために 'PRINT' ステートメントを使用している場合は、outputLogs を使用します。クエリが resultSets を返す場合、これをアクティビティ出力で使用できます。5,000 行、サイズ制限 4 MB に制限されます。

UI を使用して Script アクティビティを構成する

[インラインスクリプト]

Screenshot showing the UI to configure an inline script.

インラインスクリプトでは、スクリプトがパイプラインメタデータの一部として格納されるため、パイプライン CI/CD との統合に適しています。

ログ機能

Screenshot showing the UI for the logging settings for a script.

ログオプション:

無効 - 実行出力はログに記録されません。
アクティビティの出力 - スクリプト実行の出力がアクティビティ出力に追加されます。これをダウンストリームアクティビティで使用できます。出力サイズは 4 MB に制限されます。
外部ストレージ - 出力をストレージに保持します。出力サイズが 2 MB を超える場合、または出力を明示的にストレージアカウント保持する場合は、このオプションを使用します。

Note

課金 - Script アクティビティはパイプラインアクティビティとして課金されます。

別の手段でデータを変換する方法を説明している次の記事を参照してください。

次の方法で共有

Azure Data Factory または Synapse Analytics で Script アクティビティを使用してデータを変換する

構文の詳細

アクティビティの出力

UI を使用して Script アクティビティを構成する

[インラインスクリプト]

ログ機能

フィードバック

フィードバック

その他のリソース

次の方法で共有

Azure Data Factory または Synapse Analytics で Script アクティビティを使用してデータを変換する

構文の詳細

アクティビティの出力

UI を使用して Script アクティビティを構成する

[インライン スクリプト]

ログ機能

関連するコンテンツ

フィードバック

フィードバック

その他のリソース

[インラインスクリプト]