Synapse ノートブックの作成、開発、保守

[アーティクル]
09/11/2024

Azure Synapse Analytics のノートブック (Synapse ノートブック) は、ライブコード、視覚化、説明テキストを含むファイルを作成するための Web インターフェイスです。ノートブックは、アイデアを確認し、簡単な実験を使用してデータから分析情報を得るのに最適な場所です。ノートブックは、データの準備、データの視覚化、機械学習、およびその他のビッグデータのシナリオでも広く使用されています。

Synapse ノートブックでは、次のことができます。

設定作業をせずに使用を開始する。
組み込みのエンタープライズセキュリティ機能を使用してデータを安全に保つのに役立ちます。
未加工の形式 (CSV、TXT、JSON など)、処理されたファイル形式 (Parquet、Delta Lake、ORC など)、および Spark と SQL に対する SQL 表形式のデータファイルを分析します。
高度な作成機能と組み込みのデータの視覚化で生産性を高める。

この記事では、Synapse Studio でノートブックを使用する方法について説明します。

ノートブックを作成する

新しいノートブックを作成することも、オブジェクトエクスプローラーから既存のノートブックを Synapse ワークスペースにインポートすることもできます。 [開発] メニューを選びます。 + ボタンを選んで [ノートブック] を選ぶか、[ノートブック] を右クリックしてから、[新しいノートブック] または [インポート] を選びます。 Synapse ノートブックでは、標準の Jupyter Notebook IPYNB ファイルが認識されます。

ノートブックを作成またはインポートするための選択のスクリーンショット。

ノートブックを開発する

ノートブックは、個別にまたはグループとして実行できるコードまたはテキストの個々のブロックである、セルで構成されます。

次のセクションでは、ノートブックを開発するための操作について説明します。

セルを追加する
第一言語を設定する
複数の言語を使用する
一時テーブルを使用して言語間でデータを参照する
IDE スタイルの IntelliSense を使用する
コードスニペットを使用する
ツールバーボタンを使用してテキストセルの書式設定を行う
セル操作を元に戻す、またはやり直す
コードセルにコメントを付ける
セルを移動する
セルをコピーする
セルを削除する
セル入力を折りたたむ
セル出力を折りたたむ
ノートブックアウトラインを使用する

Note

ノートブックでは、SparkSession インスタンスが自動的に作成され、spark という変数に保存されます。 sc と呼ばれる SparkContext の変数もあります。ユーザーはこれらの変数に直接アクセスできますが、これらの変数の値は変更しないでください。

セルを追加する

ノートブックに新しいセルを追加するには、複数の方法があります。

2 つのセル間のスペースをポイントし、 [コード] または [Markdown] を選択します。
コマンドモードのショートカットキーを使用します。現在のセルの上にセルを挿入するには A キーを選択します。現在のセルの下にセルを挿入するには B キーを選択します。

第一言語を設定する

Synapse ノートブックでは、次の 4 つの Apache Spark 言語がサポートされます。

PySpark (Python)
Spark (Scala)
Spark SQL
.NET Spark (C#)
SparkR (R)

上部のコマンドバーにある [言語] ドロップダウンリストから、新しく追加されたセルの第一言語を設定できます。

Synapse ノートブックで言語を選択するためのドロップダウンリストのスクリーンショット。

複数の言語を使用する

1 つのノートブックで、セルの先頭に正しい言語マジックコマンドを指定することで、複数の言語を使用できます。次の表に、セルの言語を切り替えるマジックコマンドを一覧表示します。

マジックコマンド	Language	説明
`%%pyspark`	Python	`SparkContext` に対して Python クエリを実行します。
`%%spark`	Scala	`SparkContext` に対して Scala クエリを実行します。
`%%sql`	Spark SQL	`SparkContext` に対して Spark SQL クエリを実行します。
`%%csharp`	.NET for Spark C#	`SparkContext` に対して .NET for Spark C# クエリを実行します。
`%%sparkr`	R	`SparkContext` に対して R クエリを実行します。

次の図は、%%pyspark マジックコマンドを使用する PySpark クエリ、または Spark (Scala) ノートブックで %%sql マジックコマンドを使用する Spark SQL クエリを記述する方法の例を示します。ノートブックの第一言語は PySpark に設定されています。

Synapse ノートブックの Spark マジックコマンドのスクリーンショット。

一時テーブルを使用して言語間でデータを参照する

Synapse ノートブックでは、異なる言語間でデータや変数を直接参照することはできません。 Spark では、複数の言語で一時テーブルを参照できます。回避策として、Spark 一時テーブルを使用して PySpark と Spark SQL で Scala DataFrame を読み取る方法の例を次に示します。

セル 1 では、Scala を使用して SQL プールコネクタから DataFrame を読み取り、一時テーブルを作成します。

%%spark
val scalaDataFrame = spark.read.sqlanalytics("mySQLPoolDatabase.dbo.mySQLPoolTable")
scalaDataFrame.createOrReplaceTempView( "mydataframetable" )

セル 2 では、Spark SQL を使用してデータに対してクエリを実行します。
```
%%sql
SELECT * FROM mydataframetable
```

セル 3 では、PySpark のデータを使用します。

%%pyspark
myNewPythonDataFrame = spark.sql("SELECT * FROM mydataframetable")

IDE スタイルの IntelliSense を使用する

Synapse ノートブックは、IDE スタイルの IntelliSense をセルエディターに取り込むために、Monaco エディターと統合されています。構文の強調表示、エラーマーカー、自動コード補完の機能は、コード記述と問題の特定をより迅速に行うのに役立ちます。

IntelliSense の機能は、言語によって異なる成熟度レベルにあります。次の表を使用して、サポートされている内容を確認してください。

Languages	シンタックスハイライト	シンタックスエラーマーカー	シンタックスコード完了	変数コード完了	シンタックス関数コード完了	ユーザー関数コード完了	スマートインデント	コードの折りたたみ
PySpark (Python)	はい	イエス	イエス	イエス	イエス	イエス	イエス	はい
Spark (Scala)	はい	イエス	イエス	イエス	イエス	はい	いいえ	はい
Spark SQL	はい	イエス	イエス	イエス	はい	いいえ	いいえ	いいえ
.NET for Spark (C#)	はい	イエス	イエス	イエス	イエス	イエス	イエス	はい

.NET for Spark (C#) の変数コード補完、システム関数コード補完、ユーザー関数コード補完を利用するには、アクティブな Spark セッションが必要です。

コードスニペットを使用する

Synapse ノートブックには、一般的に使用されるコードパターンを簡単に入力できるコードスニペットが用意されています。これらのパターンには、Spark セッションの構成、Spark DataFrame としてのデータの読み取り、Matplotlib を使用したグラフの描画などがあります。

スニペットは、他の候補と一緒に IDE スタイルの IntelliSense のショートカットキーに表示されます。コードスニペットの内容は、コードセル言語に準拠したものとなります。使用可能なスニペットを確認するには、「Snippet」と入力するか、コードセルエディターのスニペットのタイトルに表示されるキーワードを入力します。たとえば、「read」と入力すると、さまざまなデータソースからデータを読み取るスニペットの一覧が表示されます。

Synapse ノートブック内のコードスニペットのアニメーション GIF。

テキストセルツールバーの書式ボタンを使用して、一般的なマークダウンアクションを実行することができます。これらのアクションには、テキストの太字化、テキストの斜体化、ドロップダウンメニューによる段落と見出しの作成、コードの挿入、順序指定されていないリストの挿入、順序指定されたリストの挿入、ハイパーリンクの挿入、URL からの画像の挿入などがあります。

Synapse ノートブックのテキストセルツールバーのスクリーンショット。

セル操作を元に戻す、またはやり直す

最新のセル操作を取り消すには、[元に戻す] または [再実行] ボタンを選択するか、Z キーまたは Shift + Z キーを押します。最新の 10 個までの履歴セル操作を元に戻したり再実行したりできます。

Synapse ノートブックの [元に戻す] ボタンと [再実行] ボタンのスクリーンショット。

サポートされているセル操作は次のとおりです。

セルの挿入または削除。削除操作は、[取り消す] を選択することで取り消すことができます。このアクションでは、テキストの内容がセルと共に保持されます。
セルの順序変更。
パラメーターセルのオンとオフの切り替え。
コードセルと Markdown セルの間での変換。

Note

セル内のテキスト操作やコメント操作を元に戻すことはできません。

コードセルにコメントを付ける

ノートブックのツールバーの [コメント] ボタンを選択して、[コメント] ペインを開きます。
コードセルでコードを選択し、[コメント] ペインで [新規] を選択してコメントを追加し、[コメントを投稿] ボタンを選択します。
必要に応じて、[コメントの編集]、[スレッドの解決]、および [スレッドの削除] アクションを実行するには、コメントの横にある [その他] 省略記号 (...) を選択します。

セルを移動する

セルを移動するには、セルの左側を選択し、目的の位置にセルをドラッグします。

Synapse ノートブック内のセルを移動するアニメーション GIF。

セルをコピーする

セルをコピーするには、最初に新しいセルを作成してから、元のセルのテキストをすべて選択し、テキストをコピーして、新しいセルにテキストを貼り付けます。セルが編集モードの場合、すべてのテキストを選択する従来のキーボードショートカットはセルに限定されます。

ヒント

Synapse ノートブックでは、よく使われるコードパターンのスニペットも提供されています。

セルを削除する

セルを削除するには、セルの右側にある [削除] ボタンを選択します。

コマンドモードのショートカットキーを使用することもできます。現在のセルを削除するには、Shift + D キーを押します。

Synapse ノートブック内のセルを削除するためのボタンのスクリーンショット。

セル入力を折りたたむ

現在のセル入力を折りたたむには、セルのツールバーの [その他のコマンド] 省略記号 (...) を選択し、[入力を非表示にする] を選択します。入力を展開するには、セルが折りたたまれている状態で [入力を表示する] を選択します。

セル出力を折りたたむ

現在のセル出力を折りたたむには、セルのツールバーの [その他のコマンド] 省略記号 (...) を選択し、[出力を非表示にする] を選択します。これを展開するには、セルの出力が非表示になっている状態で [出力を表示する] を選択します。

ノートブックアウトラインを使用する

アウトライン (目次) では、素早くナビゲーションできるようにサイドバーウィンドウ内に任意の Markdown セルの最初の Markdown ヘッダーが表示されます。 [アウトライン] サイドバーは画面に合わせてサイズを調節したり、折りたたんだりできます。ノートブックのコマンドバーにある [アウトライン] ボタンを選択すると、サイドバーを開いたり非表示にしたりできます。

ノートブックの実行

ノートブックのコードセルは、個別に、または一度にすべて実行できます。各セルの状態と進行状況がノートブックに表示されます。

Note

ノートブックを削除しても、現在実行中のジョブは自動的に取り消されません。ジョブを取り消す必要がある場合は、[監視] ハブに移動し、手動で取り消します。

セルを実行する

セル内でコードを実行する方法は複数あります。

実行するセルにカーソルを合わせ、[セルの実行] ボタンを選択するか Ctrl + Enter キーを押します。
コマンドモードのショートカットキーを使用します。現在のセルを実行し、下のセルを選択するには、Shift + Enter キーを押します。現在のセルを実行し、新しいセルを下に挿入するには、Alt + Enter キーを押します。

すべてのセルを実行する

現在のノートブックのすべてのセルを順番に実行するには、[すべて実行] ボタンを選択します。

Synapse ノートブック内のすべてのセルを実行するためのボタンのスクリーンショット。

上または下のすべてのセルを実行する

現在のセルの上にあるすべてのセルを順番に実行するには、[すべて実行] ボタンのドロップダウンリストを展開し [上のセルを実行] を選択します。現在のセルの下にあるものをすべて実行するには、[下のセルを実行] を選択します。

Synapse ノートブックの現在のセルの上下でセルを実行するためのコマンドのスクリーンショット。

実行中のすべてのセルを取り消す

実行中のセルまたはキューで待機しているセルを取り消すには、[すべて取り消し] ボタンを選択します。

Synapse ノートブックで実行中または待機中のすべてのセルを取り消すボタンのスクリーンショット。

ノートブックの参照

%run <notebook path> マジックコマンドを使用して、現在のノートブックのコンテキスト内で別のノートブックを参照することができます。参照ノートブックで定義されているすべての変数を、現在のノートブックで使用できます。

次に例を示します。

%run /<path>/Notebook1 { "parameterInt": 1, "parameterFloat": 2.5, "parameterBool": true, "parameterString": "abc" }

ノートブックの参照は、対話モードとパイプラインの両方で機能します。

%run マジックコマンドには、次の制限があります。

このコマンドでは、入れ子になった呼び出しはサポートされますが、再帰呼び出しはサポートされません。
このコマンドでは、絶対パスまたはノートブック名のみをパラメーターとして渡すことがサポートされています。相対パスはサポートされていません。
このコマンドは現在、int、float、bool、string の最大 4 つのパラメーター値タイプのみをサポートしています。変数置換操作はサポートされていません。
参照先のノートブックは発行されている必要があります。発行されていないノートブックへの参照を有効にするオプションを選択しない限り、ノートブックを参照するにはそれらを発行する必要があります。 Synapse Studio では、Git リポジトリから発行されていないノートブックは認識されません。
参照先のノートブックでは、ステートメントの深さが 5 より大きい場合はサポートされません。

変数エクスプローラーを使用する

Synapse ノートブックには、現在の Spark セッションのPySpark (Python) セルの変数が一覧表示された、テーブル形式の組み込み変数エクスプローラーが用意されています。このテーブルには、変数の名前、型、長さ、および値の列が含まれています。コードセルに定義されている変数が増えると、自動的に表示される変数も増えます。各列ヘッダーをクリックすると、テーブル内の変数を並べ替えられます。

ノートブックのコマンドバーの [変数] ボタンを選択して、変数エクスプローラーを開いたり非表示にしたりできます。

Synapse ノートブックの変数エクスプローラーのスクリーンショット。

Note

変数エクスプローラーでは、Python のみがサポートされます。

セル状態インジケーターを使用する

セル実行のステップバイステップの状態がセルの下に表示され、現在の進行状況を確認できます。セルの実行が完了すると、合計期間と終了時間を含む概要が表示され、今後の参照のためにそこに残ります。

Synapse ノートブックでのセル実行の概要のスクリーンショット。

Spark 進行状況インジケーターを使用する

Synapse ノートブックは、純粋に Spark ベースです。コードセルは、サーバーレス Apache Spark プール上でリモートで実行されます。リアルタイムの進行状況バーを持つ Spark ジョブの進行状況インジケーターは、ジョブの実行状態を理解するのに役立ちます。

ジョブまたはステージごとのタスクの数では、Spark ジョブの並列レベルを特定できます。また、ジョブ (またはステージ) の名前のリンクを選択することで、特定のジョブ (またはステージ) の Spark UI をさらに掘り下げて調べることもできます。

Synapse ノートブックの Spark 進行状況インジケーターのスクリーンショット。

Spark セッションを設定する

ノートブックの上部にある歯車アイコンを選ぶと見つかる [セッションの構成] ペインでは、現在の Spark セッションに対するタイムアウト期間や Executor の数とサイズを指定できます。 Spark セッションを再起動すると、構成の変更が有効になります。キャッシュされたノートブック変数はすべて消去されます。

また、Apache Spark の構成から構成を作成したり、既存の構成を選択したりすることもできます。詳細については、「Apache Spark の構成を管理する」を参照してください。

Spark セッションを構成するためのマジックコマンド

%%configure マジックコマンドを使用して Spark セッションの設定を指定することもできます。設定を有効にするには、Spark セッションを再起動します。

ノートブックの先頭で %%configure を実行することをお勧めします。サンプルを次に示します。有効なパラメーターの完全な一覧については、GitHub 上の Livy 情報を参照してください。

%%configure
{
    //You can get a list of valid parameters to configure the session from https://github.com/cloudera/livy#request-body.
    "driverMemory":"28g", // Recommended values: ["28g", "56g", "112g", "224g", "400g", "472g"]
    "driverCores":4, // Recommended values: [4, 8, 16, 32, 64, 80]
    "executorMemory":"28g",
    "executorCores":4, 
    "jars":["abfs[s]://<file_system>@<account_name>.dfs.core.windows.net/<path>/myjar.jar","wasb[s]://<containername>@<accountname>.blob.core.windows.net/<path>/myjar1.jar"],
    "conf":{
    //Example of a standard Spark property. To find more available properties, go to https://spark.apache.org/docs/latest/configuration.html#application-properties.
        "spark.driver.maxResultSize":"10g",
    //Example of a customized property. You can specify the count of lines that Spark SQL returns by configuring "livy.rsc.sql.num-rows".
        "livy.rsc.sql.num-rows":"3000" 
    }
}

%%configure マジックコマンドの考慮事項を次に示します。

%%configure の driverMemory と executorMemory には同じ値を使用することをお勧めします。また、driverCores と executorCores も同じ値にすることをお勧めします。
Synapse パイプラインでは %%configure を使用できますが、これは最初のコードセルで設定しないと、セッションを再起動できないためパイプラインの実行は失敗します。
mssparkutils.notebook.run で使用される %%configure コマンドは無視されますが、%run <notebook> で使用されるコマンドは引き続き実行されます。
"conf" 本文では標準の Spark 構成プロパティを使用する必要があります。 Spark 構成プロパティの第 1 レベルの参照はサポートされていません。
"spark.driver.cores"、"spark.executor.cores"、"spark.driver.memory"、"spark.executor.memory"、"spark.executor.instances" など、一部の特別な Spark プロパティは、"conf" 本文では有効になりません。

パラメーター化されたパイプラインのセッション構成

パラメーター化されたセッション構成を使用して、%%configure マジックコマンドの値をパイプライン実行 (ノートブックアクティビティ) パラメーターに置き換えることができます。 %%configure コードセルを準備するときは、次のようなオブジェクトを使用して既定値をオーバーライドできます。

{
      "activityParameterName": "parameterNameInPipelineNotebookActivity",
      "defaultValue": "defaultValueIfNoParameterFromPipelineNotebookActivity"
}

次の例は、4 と "2000"の既定値を示しています。これも構成可能です。

%%configure  

{ 
    "driverCores": 
    { 
        "activityParameterName": "driverCoresFromNotebookActivity", 
        "defaultValue": 4 
    }, 
    "conf": 
    { 
        "livy.rsc.sql.num-rows": 
        { 
            "activityParameterName": "rows", 
            "defaultValue": "2000" 
        } 
    } 
}

インタラクティブモードで直接ノートブックを実行している場合、またはパイプラインノートブックアクティビティが "activityParameterName" に一致するパラメーターを提供しない場合、ノートブックはデフォルト値を使用します。

パイプライン実行モードでは、[設定] タブを使用して、パイプラインノートブックアクティビティの設定を構成できます。

Synapse ノートブックのパラメーター化されたセッション構成のスクリーンショット。

セッション構成を変更する場合、パイプラインノートブックのアクティビティパラメーター名はノートブックの activityParameterName と同じである必要があります。この例では、パイプラインの実行中に、%%configure では driverCores が 8 に置き換えられ、livy.rsc.sql.num-rows は 4000 に置き換えられています。

%%configure マジックコマンドを使用した後にパイプラインの実行が失敗した場合は、ノートブックの対話型モードで %%configure マジックセルを実行すると、より多くのエラー情報を取得できます。

データをノートブックに取り込む

次のコードサンプルに示すように、Azure Data Lake Storage Gen 2、Azure Blob Storage、SQL プールからデータを読み込むことができます。

Azure Data Lake Storage Gen2 から CSV ファイルを Spark DataFrame として読み取る

from pyspark.sql import SparkSession
from pyspark.sql.types import *
account_name = "Your account name"
container_name = "Your container name"
relative_path = "Your path"
adls_path = 'abfss://%s@%s.dfs.core.windows.net/%s' % (container_name, account_name, relative_path)

df1 = spark.read.option('header', 'true') \
                .option('delimiter', ',') \
                .csv(adls_path + '/Testfile.csv')

Azure Blob Storage から CSV ファイルを Spark DataFrame として読み取る


from pyspark.sql import SparkSession

# Azure storage access info
blob_account_name = 'Your account name' # replace with your blob name
blob_container_name = 'Your container name' # replace with your container name
blob_relative_path = 'Your path' # replace with your relative folder path
linked_service_name = 'Your linked service name' # replace with your linked service name

blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds(linked_service_name)

# Allow Spark to access from Azure Blob Storage remotely

wasb_path = 'wasbs://%s@%s.blob.core.windows.net/%s' % (blob_container_name, blob_account_name, blob_relative_path)

spark.conf.set('fs.azure.sas.%s.%s.blob.core.windows.net' % (blob_container_name, blob_account_name), blob_sas_token)
print('Remote blob path: ' + wasb_path)

df = spark.read.option("header", "true") \
            .option("delimiter","|") \
            .schema(schema) \
            .csv(wasbs_path)

プライマリストレージアカウントからデータを読み取る

プライマリストレージアカウントのデータに直接アクセスすることができます。秘密鍵を指定する必要はありません。データエクスプローラーで、ファイルを右クリックし、[新しいノートブック] を選択すると、自動生成されたデータエクストラクターを持つノートブックが表示されます。

IPython ウィジェットを使用する

ウィジェットは、多くの場合、スライダーやテキストボックスなどのコントロールとしてブラウザーで表現される、イベントフル Python オブジェクトです。 IPython ウィジェットは Python 環境でのみ機能します。現在、他の言語 (Scala、SQL、C# など) ではサポートされていません。

IPython Widgets を使用する手順

Jupyter Widgets フレームワークを使用するには、ipywidgets モジュールをインポートします。
```
import ipywidgets as widgets
```
最上位の display 関数を使用してウィジェットをレンダリングするか、コードセルの最後の行に widget 型の式を残します。
```
slider = widgets.IntSlider()
display(slider)
```
```
slider = widgets.IntSlider()
slider
```
セルを実行します。ウィジェットが出力領域に表示されます。

複数の display() 呼び出しを使用することで同じウィジェットインスタンスを複数回レンダリングできますが、それらは互いに同期されたままになります。

slider = widgets.IntSlider()
display(slider)
display(slider)

Synapse ノートブック内の複数の IPython ウィジェットスライダーのスクリーンショット。

2 つのウィジェットを互いに独立してレンダリングするには、2 つのウィジェットインスタンスを作成します。

slider1 = widgets.IntSlider()
slider2 = widgets.IntSlider()
display(slider1)
display(slider2)

サポートされているウィジェット

ウィジェットの種類	ウィジェット
数値	`IntSlider`、`FloatSlider`、`FloatLogSlider`、`IntRangeSlider`、`FloatRangeSlider`、`IntProgress`、`FloatProgress`、`BoundedIntText`、`BoundedFloatText`、`IntText`、`FloatText`
Boolean	`ToggleButton`、`Checkbox`、`Valid`
[選択]	`Dropdown`､`RadioButtons`、`Select`、`SelectionSlider`、`SelectionRangeSlider`、`ToggleButtons`、`SelectMultiple`
String	`Text`, `Text area`, `Combobox`, `Password`, `Label`, `HTML`, `HTML Math`, `Image`, `Button`
再生 (アニメーション)	`Date picker`、`Color picker`、`Controller`
コンテナー/レイアウト	`Box`､`HBox`、`VBox`、`GridBox`、`Accordion`、`Tabs`、`Stacked`

既知の制限事項

次の表に、現在サポートされていないウィジェットと回避策を示します。

機能	回避策
`Output` ウィジェット	代わりに `print()` 関数を使用して、`stdout` にテキストを書き込むことができます。
`widgets.jslink()`	`widgets.link()` 関数を使用して、似たような 2 つのウィジェットをリンクできます。
`FileUpload` ウィジェット	使用できるものはありません。

Azure Synapse Analytics が提供するグローバル display 関数では、1 回の呼び出しで複数のウィジェットを表示することはできません (つまり、display(a, b))。この動作は、IPython display 関数とは異なります。
IPython ウィジェットを含むノートブックを閉じると、対応するセルを再度実行するまで、そのノートブックを表示したり操作したりすることはできません。

ノートブックを保存する

ワークスペースには、単一のノートブックまたはすべてのノートブックを保存できます。

単一のノートブックに加えた変更を保存するには、ノートブックのコマンドバーにある [公開] ボタンを選択します。
ワークスペース内のすべてのノートブックを保存するには、ワークスペースのコマンドバーにある [すべて公開] ボタンを選択します。

ノートブックの [プロパティ] ペインでは、保存時にセル出力を含めるかどうかを構成できます。

Synapse ノートブックのプロパティと、保存時にセル出力を含めるチェックボックスのスクリーンショット。

マジックコマンドを使用する

Synapse ノートブックでは、使い慣れた Jupyter マジックコマンドを使用できます。現在使用できるマジックコマンドをまとめた次の一覧をご確認ください。ユーザーのニーズに合ったマジックコマンドを引き続き作成できるよう、GitHub 上でユースケースについてお知らせください。

Note

Synapse パイプラインでは、%%pyspark、%%spark、%%csharp、%%sql のマジックコマンドのみがサポートされます。

行で使用できるマジックコマンド:

%lsmagic、%time、%timeit、%history、%run、%load

セルに使用できるマジックコマンド:

%%time、%%timeit、%%capture、%%writefile、%%sql、%%pyspark、%%spark、%%csharp、%%html、%%configure

発行されていないノートブックを参照する

発行されていないノートブックを参照することは、ローカルでデバッグする場合に役立ちます。この機能を有効にすると、ノートブックの実行によって Web キャッシュ内の現在のコンテンツがフェッチされます。参照ノートブックステートメントを含むセルを実行する場合は、クラスターに保存されているバージョンではなく、現在のノートブックブラウザーで表示されているノートブックを参照します。他のノートブックでは、変更を発行 (ライブモード) またはコミット (Git モード) しなくても、ノートブックエディターで変更を参照できます。この方法を使用すると、開発またはデバッグプロセス中に一般的なライブラリの汚染を防ぐことができます。

[プロパティ] ペインで適切なチェックボックスをオンにすると、発行されていないノートブックへの参照を有効にすることができます。

発行されていない Synapse ノートブックの参照を有効にするためのチェックボックスのスクリーンショット。

下の表では次のケースを比較しています %run と mssparkutils.notebook.run の動作は同じですが、テーブルでは例として %run を使用します。

ケース	Disable	有効化
ライブモード
Nb1 (発行済み) `%run Nb1`	Nb1 の発行済みバージョンを実行する	Nb1 の発行済みバージョンを実行する
Nb1 (新規) `%run Nb1`	エラー	新規の Nb1 を実行する
Nb1 (以前に発行済み、編集済み) `%run Nb1`	Nb1 の発行済みバージョンを実行する	Nb1 の編集済みバージョンを実行する
Git モード
Nb1 (発行済み) `%run Nb1`	Nb1 の発行済みバージョンを実行する	Nb1 の発行済みバージョンを実行する
Nb1 (新規) `%run Nb1`	エラー	新規の Nb1 を実行する
Nb1 (未発行、コミット済み) `%run Nb1`	エラー	コミット済み Nb1 を実行する
Nb1 (以前に発行済み、コミット済み) `%run Nb1`	Nb1 の発行済みバージョンを実行する	Nb1 のコミット済みバージョンを実行する
Nb1 (以前に発行済み、現在のブランチで新規) `%run Nb1`	Nb1 の発行済みバージョンを実行する	新規の Nb1 を実行する
Nb1 (未発行、以前にコミット済み、編集済み) `%run Nb1`	エラー	Nb1 の編集済みバージョンを実行する
Nb1 (以前に発行済みでコミット済み、編集済み) `%run Nb1`	Nb1 の発行済みバージョンを実行する	Nb1 の編集済みバージョンを実行する

要約すると:

発行されていないノートブックの参照を無効にする場合は、常に [発行済] バージョンを実行します。
発行されていないノートブックの参照を有効にした場合、参照実行では、ノートブック UX に表示される現在のバージョンのノートブックが常に採用されます。

アクティブなセッションを管理する

新しいセッションを開始しなくても、ノートブックセッションを便利に再利用できるようになりました。 Synapse ノートブックでは、アクティブなセッションを 1 つのリストで管理できます。一覧を開くには、省略記号 (...) を選択し、セッションの管理を選択します。

アクティブな Synapse ノートブックセッションの一覧を開く選択のスクリーンショット。

[アクティブなセッション] ペインには、ノートブックから開始した現在のワークスペース内のすべてのセッションが一覧表示されます。一覧には、セッション情報と対応するノートブックが表示されます。ここでは、[ノートブックからデタッチする]、[セッションを停止する]、および[監視ビュー] の監視アクションが利用できます。また、選択したノートブックを、別のノートブックから開始したアクティブなセッションに接続することもできます。その後、セッションは前のノートブックからデタッチされ (アイドル状態でない場合)、現在のノートブックにアタッチされます。

Synapse ワークスペース内のアクティブなセッションのペインのスクリーンショット。

ノートブックで Python ログを使用する

次のサンプルコードに従うと、Python ログを検索してさまざまなログレベルと形式を設定できます。

import logging

# Customize the logging format for all loggers
FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
formatter = logging.Formatter(fmt=FORMAT)
for handler in logging.getLogger().handlers:
    handler.setFormatter(formatter)

# Customize the log level for all loggers
logging.getLogger().setLevel(logging.INFO)

# Customize the log level for a specific logger
customizedLogger = logging.getLogger('customized')
customizedLogger.setLevel(logging.WARNING)

# Logger that uses the default global log level
defaultLogger = logging.getLogger('default')
defaultLogger.debug("default debug message")
defaultLogger.info("default info message")
defaultLogger.warning("default warning message")
defaultLogger.error("default error message")
defaultLogger.critical("default critical message")

# Logger that uses the customized log level
customizedLogger.debug("customized debug message")
customizedLogger.info("customized info message")
customizedLogger.warning("customized warning message")
customizedLogger.error("customized error message")
customizedLogger.critical("customized critical message")

入力コマンドの履歴を表示する

Synapse ノートブックでは、現在のセッションの入力コマンド履歴を出力するためのマジックコマンド %history がサポートされています。 %history マジックコマンドは、標準の Jupyter IPython コマンドに似ています。ノートブック内の複数の言語コンテキストに対して機能します。

%history [-n] [range [range ...]]

上記のコードでは、-n は印刷実行番号です。 range 値は次のように設定できます。

N: 実行された Nth セルのコードを出力します。
M-N: Mth から Nth までの実行セルのコードを出力します。

たとえば、1 番目から 2 番目に実行されたセルに入力履歴を出力するには、%history -n 1-2を使用します。

ノートブックを統合する

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

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

既存または新しい Synapse パイプラインにノートブックを追加するためのメニューオプションのスクリーンショット。

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

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

セルをパラメーターセルとして指定するためのメニューオプションのスクリーンショット。

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

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

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

Azure Synapse Analytics でパラメーターを割り当てる領域のスクリーンショット。

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

ショートカットキーを使用する

Jupyter Notebook と同様に、Synapse ノートブックにはモーダルユーザーインターフェイスが採用されています。キーボードの動作は、ノートブックセルのモードによって異なります。 Synapse ノートブックでは、コードセルに対して次の 2 つのモードがサポートされています。

コマンドモード: 入力を求めるテキストカーソルがない場合、セルはコマンドモードです。セルがコマンドモードの場合、ノートブックを全体として編集できますが、個々のセルに入力することはできません。 Esc キーを選択するか、マウスを使用してセルのエディター領域の外側を選択して、コマンドモードに入ります。
編集モード: セルが編集モードの場合、セルに入力するように求めるテキストカーソルが表示されます。 Enter キーを押すか、マウスを使用してセルのエディター領域を選択して、編集モードに入ります。

コマンドモードのショートカットキー

アクション	Synapse ノートブックのショートカット
現在のセルを実行して下のものを選択する	Shift + Enter
現在のセルを実行して下に挿入する	Alt + Enter
現在のセルを実行する	Ctrl + Enter
上のセルを選択する	上へ
下のセルを選択する	[下へ]
前のセルを選択する	K
次のセルを選択する	J
上にセルを挿入する	A
下にセルを挿入する	B
選択されたセルを削除する	Shift + D
編集モードに切り替える	次に、

編集モードのショートカットキー

アクション	Synapse ノートブックのショートカット
カーソルを上に移動する	上へ
カーソルを下に移動する	[下へ]
元に戻す	Ctrl + Z
やり直し	Ctrl + Y
コメント化する/コメントを解除する	Ctrl + /
前の単語を削除する	Ctrl + Backspace
後の単語を削除する	Ctrl + Delete
セルの先頭に移動する	Ctrl + Home
セルの末尾に移動する	Ctrl + End
1 単語左に移動する	Ctrl + ←
1 単語右に移動する	Ctrl + →
すべて選択する	Ctrl + A
インデントする	Ctrl + ]
インデントを解除する	Ctrl + [
コマンドモードに切り替える	Esc

次の方法で共有

Synapse ノートブックの作成、開発、保守

ノートブックを作成する

ノートブックを開発する

セルを追加する

第一言語を設定する

複数の言語を使用する

一時テーブルを使用して言語間でデータを参照する

IDE スタイルの IntelliSense を使用する

コード スニペットを使用する

ツール バー ボタンを使用してテキスト セルの書式設定を行う

セル操作を元に戻す、またはやり直す

コード セルにコメントを付ける

セルを移動する

セルをコピーする

セルを削除する

セル入力を折りたたむ

セル出力を折りたたむ

ノートブック アウトラインを使用する

ノートブックの実行

セルを実行する

すべてのセルを実行する

上または下のすべてのセルを実行する

実行中のすべてのセルを取り消す

ノートブックの参照

変数エクスプローラーを使用する

セル状態インジケーターを使用する

Spark 進行状況インジケーターを使用する

Spark セッションを設定する

Spark セッションを構成するためのマジック コマンド

パラメーター化されたパイプラインのセッション構成

データをノートブックに取り込む

Azure Data Lake Storage Gen2 から CSV ファイルを Spark DataFrame として読み取る

Azure Blob Storage から CSV ファイルを Spark DataFrame として読み取る

プライマリ ストレージ アカウントからデータを読み取る

IPython ウィジェットを使用する

IPython Widgets を使用する手順

サポートされているウィジェット

既知の制限事項

ノートブックを保存する

マジックコマンドを使用する

発行されていないノートブックを参照する

アクティブなセッションを管理する

ノートブックで Python ログを使用する

入力コマンドの履歴を表示する

ノートブックを統合する

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

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

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

ショートカット キーを使用する

コマンド モードのショートカット キー

編集モードのショートカット キー

関連するコンテンツ

フィードバック

その他のリソース

コードスニペットを使用する

ツールバーボタンを使用してテキストセルの書式設定を行う

コードセルにコメントを付ける

ノートブックアウトラインを使用する

Spark セッションを構成するためのマジックコマンド

プライマリストレージアカウントからデータを読み取る

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

ショートカットキーを使用する

コマンドモードのショートカットキー

編集モードのショートカットキー