次の方法で共有

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

  • [アーティクル]

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

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

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 ノートブックのパラメーター切り換えを示すスクリーンショット

このセルでパラメーターを定義します。 これは、次のように単純なものになる可能性があります。

a = 1
b = 3
c = "Default Value"

これらのパラメーターを他のセルで参照したり、ノートブックを実行するときに、このパラメーター セルで指定した既定値を使用したりすることができます。

このノートブックをパイプラインから実行すると、Azure Data Factory によってパラメーター セルが検索され、指定した値が、実行時に渡されるパラメーターの既定値として使用されます。 パイプラインからパラメーター値を割り当てる場合、実行エンジンにより、入力パラメーターを含む新しいセルがパラメーター セルの下に追加され、既定値が上書きされます。

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

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

パラメーターの割り当てを示すスクリーンショット

ヒント

Data Factory によってパラメーターが自動的に設定されることはありません。 手動で追加する必要があります。 ノートブックのパラメーター セルとパイプラインの基本パラメーターの両方で、まったく同じ名前を必ず使用してください。

アクティビティにパラメーターを追加すると、Data Factory によって、アクティビティで指定した値がノートブックに渡され、ノートブックは、パラメーター セルで指定した既定値ではなく新しいパラメーター値を使用して実行されます。

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

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

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

  1. Synapse ノートブック アクティビティで mssparkutils.notebook.exit API を呼び出して、アクティビティの出力に表示する値を返します。次に例を示します。

    mssparkutils.notebook.exit("hello world")

    ノートブックのコンテンツを保存してパイプラインを再トリガーすると、手順 2 の次に続くアクティビティで使用できる exitValue がノートブック アクティビティの出力に含まれます。

  2. ノートブック アクティビティの出力から exitValue プロパティを読み取ります。 ノートブック アクティビティの出力から取り込まれた exitValue が「hello world」と等しいかどうかを確認するために使用されるサンプル式を次に示します。

    exitValue の読み取りを示すスクリーンショット

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