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

適用対象: 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 アクティビティを構成する

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

インライン スクリプトを構成するための UI を示すスクリーンショット。

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

ログ記録

スクリプトのログ設定の UI を示すスクリーンショット。

ログ オプション:

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

Note

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

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