Synapse Notebook を実行してデータを変換する

[アーティクル]
03/16/2023

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

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

Synapse パイプラインの Azure Synapse ノートブックアクティビティは、Azure Synapse ワークスペースの Synapse ノートブックを実行します。この記事は、データ変換とサポートされる変換アクティビティの概要を説明する、データ変換アクティビティに関する記事に基づいています。

Synapse ノートブックアクティビティを作成する

Synapse ノートブックアクティビティは、Synapse パイプラインキャンバスまたはノートブックエディターから直接作成できます。 Synapse ノートブックアクティビティは、Synapse ノートブックで選択された Spark プールで実行されます。

パイプラインキャンバスから Synapse ノートブックアクティビティを追加する

[アクティビティ] の下にある Synapse ノートブックを Synapse パイプラインキャンバスにドラッグアンドドロップします。 Synapse ノートブックアクティビティボックス上を選択し、 [設定] で現在のアクティビティのノートブックコンテンツを構成します。現在のワークスペースから既存のノートブックを選択することも、新しいものを追加することもできます。

現在のワークスペースから既存のノートブックを選択した場合は、[開く] ボタンをクリックしてノートブックのページを直接開くことができます。

(省略可能) 設定で [Spark プール]、[Executor のサイズ]、[Executor を動的に割り当てる]、[Executor の最小数]、[Executor の最大数]、[ドライバーのサイズ] を再構成することもできます。ここで再構成した設定により、ノートブックの構成セッションの設定が置き換えられます。現在のノートブックアクティビティの設定に何も設定されていない場合は、そのノートブックの構成セッションの設定で実行されます。

ノートブックアクティビティの作成を示すスクリーンショット

プロパティ	説明	必須
Spark プール	Spark プールへの参照。一覧から Apache Spark プールが選択できます。この設定が空の場合、ノートブック自体の Spark プールで実行されます。	いいえ
Executor size (エグゼキュータのサイズ)	セッションの指定された Apache Spark プール内に割り当てられている Executor で使用されるコアとメモリの数です。	いいえ
エグゼキューターを動的に割り当てる	この設定は、Spark アプリケーションのエグゼキューターの割り当てに対する Spark 構成の動的割り当てプロパティにマップされます。	いいえ
Executor の最小数	ジョブの指定された Spark プール内に割り当てられる Executor の最小数。	いいえ
Executor の最大数	ジョブの指定された Spark プール内に割り当てられる Executor の最大数。	いいえ
Driver size (ドライバーサイズ)	ジョブ用の指定された Apache Spark プール内で提供される、ドライバーに使用するコアとメモリの数。	いいえ

注意

Azure Synapse パイプラインにおける並列 Spark Notebooks の実行はキューに格納されて FIFO 方式で実行されます。キューにおけるジョブの順序は時系列に基づきます。また、キューに格納されるジョブの有効期限は 3 日です。ノートブックのキューは Synapse パイプラインでしか機能しないことに注意してください。

Synapse パイプラインにノートブックを追加する

右上隅にある [パイプラインへの追加] ボタンを選択して、ノートブックを既存のパイプラインに追加するか、新しいパイプラインを作成します。

パイプラインへのノートブックの追加を示すスクリーンショット

パラメーターを渡す

パラメーターセルを指定する

ノートブックをパラメーター化するには、省略記号 (...) を選択して、セルツールバーの [more commands](その他のコマンド) にアクセスします。次に、 [パラメーターセルを切り替えます] を選択して、セルをパラメーターセルとして指定します。

Azure Data Factory によりパラメーターセルが検索され、その値が実行時に渡されるパラメーターの既定値として使用されます。実行エンジンにより、既定値を上書きするために、入力パラメーターを含んだ新しいセルがパラメーターセルの下に追加されます。

パイプラインからパラメーター値を割り当てる

パラメーター付きのノートブックを作成したら、Synapse ノートブックアクティビティを使用して、パイプラインから実行できます。アクティビティをパイプラインキャンバスに追加した後、 [設定] タブの [Base parameters](基本パラメーター) セクションで、パラメーターの値を設定できます。

パラメーター値を割り当てるときは、パイプライン式言語またはシステム変数を使用できます。

Synapse ノートブックのセル出力値を読み取る

下の手順に従って、次のアクティビティ内のノートブックセル出力値を読み取ることができます。

Synapse ノートブックアクティビティで mssparkutils.notebook.exit API を呼び出して、アクティビティの出力に表示する値を返します。次に例を示します。
```
mssparkutils.notebook.exit("hello world") 
```
ノートブックのコンテンツを保存してパイプラインを再トリガーすると、手順 2 の次に続くアクティビティで使用できる exitValue がノートブックアクティビティの出力に含まれます。
ノートブックアクティビティの出力から exitValue プロパティを読み取ります。ノートブックアクティビティの出力から取り込まれた exitValue が「hello world」と等しいかどうかを確認するために使用されるサンプル式を次に示します。

別の Synapse ノートブックを実行する

%run マジックまたは mssparkutils ノートブックユーティリティを呼び出して、Synapse ノートブックアクティビティ内の他のノートブックを参照できます。どちらも、入れ子になっている関数呼び出しをサポートしています。シナリオに基づいて考慮する必要があるこれら 2 つの方法の主な違いは次のとおりです。

%run マジックは、参照されているノートブックのすべてのセルを %run セルにコピーし、変数コンテキストを共有します。 notebook1 が %run notebook2 を使用して notebook2 を参照し、notebook2 が mssparkutils.notebook.exit 関数を呼び出すとき、notebook1 のセルの実行は停止されます。ノートブックファイルを "含める" 必要がある場合は、%run マジックを使用することをお勧めします。
mssparkutils ノートブックユーティリティは、参照されているノートブックをメソッドまたは関数として呼び出します。変数コンテキストは共有されません。 notebook1 が mssparkutils.notebook.run("notebook2") を使用して notebook2 を参照し、notebook2 が mssparkutils.notebook.exit 関数を呼び出すとき、notebook1 のセルの実行は続行されます。ノートブックを "インポート" する必要がある場合は、mssparkutils ノートブックユーティリティを使用することをお勧めします。

ノートブックアクティビティの実行履歴を表示する

[監視] タブで [パイプラインの実行] にアクセスすると、トリガーされたパイプラインが表示されます。ノートブックアクティビティを含むパイプラインを開いて、実行履歴を表示します。

[open notebook](ノートブックを開く) ボタンを選択すると、セルの入力と出力の両方を含む最新のノートブック実行スナップショットを表示できます。

ノートブックアクティビティの履歴を示すスクリーンショット。

ノートブックスナップショットを開きます。

開いているノートブックスナップショットを示すスクリーンショット。

ノートブックアクティビティの入力または出力を表示するには、 [入力] または [出力] ボタンを選択します。ユーザーエラーでパイプラインが失敗した場合は、 [出力] を選択して [result] フィールドを調べて、ユーザーエラーの詳細なトレースバックを確認します。

ユーザーエラーの詳細を示すスクリーンショット。

Synapse ノートブックアクティビティの定義

Synapse ノートブックアクティビティのサンプル JSON 定義を次に示します。

{
    "name": "parameter_test",
    "type": "SynapseNotebook",
    "dependsOn": [],
    "policy": {
        "timeout": "7.00:00:00",
        "retry": 0,
        "retryIntervalInSeconds": 30,
        "secureOutput": false,
        "secureInput": false
    },
    "userProperties": [],
    "typeProperties": {
        "notebook": {
            "referenceName": "parameter_test",
            "type": "NotebookReference"
        },
        "parameters": {
            "input": {
                "value": {
                    "value": "@pipeline().parameters.input",
                    "type": "Expression"
                }
            }
        }
    }
}

Synapse ノートブックアクティビティの出力

Synapse ノートブックアクティビティの出力のサンプル JSON を次に示します。

{
{
    "status": {
        "Status": 1,
        "Output": {
            "status": <livySessionInfo>
            },
            "result": {
                "runId": "<GUID>",
                "runStatus": "Succeed",
                "message": "Notebook execution is in Succeeded state",
                "lastCheckedOn": "2021-03-23T00:40:10.6033333Z",
                "errors": {
                    "ename": "",
                    "evalue": ""
                },
                "sessionId": 4,
                "sparkpool": "sparkpool",
                "snapshotUrl": "https://myworkspace.dev.azuresynapse.net/notebooksnapshot/{guid}",
                "exitCode": "abc" // return value from user notebook via mssparkutils.notebook.exit("abc")
            }
        },
        "Error": null,
        "ExecutionDetails": {}
    },

    "effectiveIntegrationRuntime": "DefaultIntegrationRuntime (West US 2)",
    "executionDuration": 234,
    "durationInQueue": {
        "integrationRuntimeQueue": 0
    },
    "billingReference": {
        "activityType": "ExternalActivity",
        "billableDuration": [
            {
                "meterType": "AzureIR",
                "duration": 0.06666666666666667,
                "unit": "Hours"
            }
        ]
    }
}

既知の問題

Pipeline Notebook アクティビティでノートブック名がパラメーター化されている場合、発行されていない状態のノートブックバージョンはデバッグ実行で参照できません。

次の方法で共有

Synapse Notebook を実行してデータを変換する