Microsoft Fabric ノートブックの開発、実行、管理

Microsoft Fabric ノートブックは Apache Spark ジョブや機械学習テストを開発するためのプライマリ コード アイテムです。 これは、データ サイエンティストやデータ エンジニアが、豊富な視覚化と Markdown テキストの恩恵を受けながらコードを記述するために使用する、Web ベースの対話型サーフェスです。 この記事では、コード セル操作を使用してノートブックを開発し、それらを実行する方法について説明します。

ノートブックを開発する

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

ノートブックを開発するための豊富な操作が提供されます。

• セルを追加する
• 第一言語を設定する
• 複数の言語を使用する
• IDE スタイルの IntelliSense
• コード スニペット
• ドラッグ アンド ドロップしてスニペットを挿入する
• ドラッグ アンド ドロップして画像を挿入する
• ツールバー ボタンを使用してテキスト セルを書式設定する
• セル操作を元に戻す、またはやり直す
• セルを移動する
• セルを削除する
• セル入力を折りたたむ
• セル出力を折りたたむ
• セル出力のセキュリティ
• セルをロックまたは固定する
• Notebook のコンテンツ
• Markdown の折りたたみ
• 検索と置換

セルを追加する

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

1. 2 つのセル間のスペースをポイントし、 [コード] または [Markdown] を選択します。

2. コマンド モードのショートカット キーを使用します。 現在のセルの上にセルを挿入するには、A キーを押します。 現在のセルの下にセルを挿入するには、B キーを押します。

第一言語を設定する

Fabric ノートブックは現在、4 つの Apache Spark 言語をサポートしています。

• PySpark (Python)
• Spark (Scala)
• Spark SQL
• SparkR

上部のコマンド バーのドロップダウン リストで、新しく追加されたセルのプライマリ言語を設定できます。

複数の言語を使用する

セルの冒頭で言語マジック コマンドを指定すると、ノートブックで複数の言語を使用できます。 また、言語ピッカーからセル言語を切り替えることもできます。 次のテーブルに、セル言語を切り替えるマジック コマンドの一覧を示します。

IDE スタイルの IntelliSense

Fabric ノートブックは Monaco エディターと統合され、セル エディターに IDE スタイルの IntelliSense を提供します。 シンタックス ハイライト、エラー マーカー、自動コード完了を使用して迅速にコードを書き、問題を特定できます。

IntelliSense の機能は、言語によって異なる成熟度レベルにあります。 次のテーブルに Fabric のサポート内容を示します。

コード スニペット

Fabric ノートブックは、一般的に使用されるコード パターンを簡単に書けるようになるコード スニペットを提供します。これには次のようなものがあります。

• Apache Spark DataFrame としてデータを読み込む
• Matplotlib を使用してグラフを作成する

スニペットは、他の候補と一緒に IDE スタイルの IntelliSense のショートカット キーに表示されます。 コード スニペット コンテンツはコードのセル言語に対応します。 「スニペット」と入力すると、使用可能なスニペットを確認できます。 また、任意のキーワードを入力すると該当のスニペットの一覧を確認できます。 たとえば「読み込み」と入力すると、さまざまなデータ ソースからデータを読み込むスニペットの一覧が表示されます。

ドラッグ アンド ドロップしてスニペットを挿入する

ドラッグ アンド ドロップを使用して Lakehouse エクスプローラーからデータを簡単に読み込むことができます。 こちらではテキスト ファイル、テーブル、画像など複数のファイル形式がサポートされています。既存のセルまたは新しいセルにドロップできます。 ノートブックは、データをプレビューするために、それに応じてコード スニペットを生成します。

ドラッグ アンド ドロップして画像を挿入する

ドラッグ アンド ドロップを使用すると、ブラウザやローカル コンピューターから画像を簡単にマークダウン セルに挿入できます。

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

一般的なマークダウン操作を完了するには、テキスト セル ツールバーの形式ボタンを使用します。

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

[元に戻す] または [やり直す] を選択するか、Z キーまたは Shift+Z キーを押して、最新のセル操作を取り消します。 最大 10 件のセル操作の最新履歴を元に戻すか、やり直すことができます。

サポートされているセルを元に戻す操作:

• セルを挿入または削除します。 [元に戻す] を選択すると、削除操作を取り消すことができます (テキスト コンテンツはセルに沿って維持されます)。
• セルの順序を変更する。
• パラメーターを切り替える。
• コード セルと Markdown セルの間で変換を行う。

セルを移動する

セルの空の部分からドラッグし、目的の位置にドロップできます。

リボン上の [上へ移動] と [下へ移動] を使って選択したセルを移動することもできます。

セルを削除する

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

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

セル入力を折りたたむ

現在のセルの入力を折りたたむには、セル ツールバーのその他のコマンド省略記号 (...) と [入力を非表示] を選択します。 セルが折りたたまれている場合、再度デプロイするには [入力を表示] を選択します。

セル出力を折りたたむ

現在のセルの出力を折りたたむには、セル ツールバーのその他のコマンド省略記号 (...) と [出力を非表示] を選択します。 セルの出力が折りたたまれている場合、再度デプロイするには [出力を表示] を選択します。

セル出力のセキュリティ

OneLake データ アクセス ロール (プレビュー) を使用すると、ユーザーはノートブック クエリ中に Lakehouse 内の特定のフォルダーにのみアクセスを構成できます。 フォルダーまたはテーブルにアクセスしないユーザーには、クエリの実行中に未承認のエラーが表示されます。

セルをロックまたは固定する

セルのロックと固定操作を使用すると、セルを読み取り専用にしたり、個々ベースでのコード セルの実行を停止したりできます。

セルを統合、分割する

[前のセルと結合] または [次のセルと結合] を使用すると、簡単に関連セルを結合できます。

[セルを分割] では関係のない文を複数のセルに分割できます。 この操作では、カーソルの行位置に応じてコードを分割します。

Notebook のコンテンツ

[概要] または [目次] を選択すると、サイドバー ウィンドウで任意のマークダウン セルの 1 つ目のマークダウン ヘッダーが表示され、簡単に移動できます。 [概要] サイドバーは画面に合わせてサイズを調節したり、折りたたんだりできます。 サイドバーを開いたり非表示にしたりするには、ノートブック コマンド バーの [コンテンツ] ボタンを選択します。

Markdown の折りたたみ

マークダウン折りたたみオプションを使用すると、見出しを含むマークダウン セルの下でセルを非表示にできます。 Markdown セルとその非表示セルは、セル操作の実行時に連続する複数選択セルのセットと同じように扱われます。

検索および置換

検索および置換オプションを使用すると、ノートブック コンテンツ内のキーワードまたは表現を一致させ、見つけることができます。 また、新しい文字列を使用して対象の文字列を簡単に置き換えることもできます。

ノートブックを実行する

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

セルを実行する

セルでコードを実行するには、いくつかの方法があります。

• 実行するセルにカーソルを合わせて、[セルを実行] ボタンまたは Ctrl+Enter キーを押します。

• コマンド モードのショートカット キーを使用します。 現在のセルを実行し、次のセルを選択するには、Shift + Enter キーを押します。 現在のセルを実行し、新しいセルを挿入するには、Alt + Enter キーを押します。

すべてのセルを実行する

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

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

[すべて実行] でドロップダウン リストをデプロイし、[上でセルを実行] を選択して現在の順序ですべてのセルを実行します。 現在のセルと下にあるすべてのセルを実行するには、[以下のセル実行] を選択します。

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

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

セッションの停止

セッションを停止すると、実行中のセルと待機中のセルが取り消され、現在のセッションが停止されます。 実行オプションを再度選択すると、新しいセッションを再開できます。

参照を実行する

Notebook の参照を実行する

mssparkutils reference run API に加え、%run <notebook name> マジック コマンドを使用して現在のノートブックのコンテキスト内で別のノートブックを参照できます。 参照ノートブックで定義されているすべての変数を、現在のノートブックで使用できます。 %run マジック コマンドはネストされているセルをサポートしていますが、再帰セルはサポートしていません。 ステートメントの深度が 5 を超えると、例外が発生します。

例: %run Notebook1 { "parameterInt": 1, "parameterFloat": 2.5, "parameterBool": true, "parameterString": "abc" }。

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

スクリプトの参照を実行する

また、この %run コマンドを使用すると、ノートブックの組み込みリソースに格納されている Python または SQL ファイルを実行できるため、ノートブック内のソース コード ファイルを簡単に実行できます。

%run [-b/--builtin -c/--current] [script_file.py/.sql] [variables ...]

オプション:

• -b/--builtin: このオプションは、コマンドがノートブックの組み込みリソースから指定されたスクリプト ファイルを検索して実行することを示します。
• -c/--current: このオプションにより、現在のノートブックが他のノートブックによって参照されている場合でも、コマンドは常に現在のノートブックの組み込みリソースを使用します。

例 :

• 組み込みリソースから script_file.py を実行するには: %run -b script_file.py

• 組み込みリソースから script_file.sql を実行するには: %run -b script_file.sql

• 特定の変数を含む組み込みリソースから script_file.py を実行するには: %run -b script_file.py { "parameterInt": 1, "parameterFloat": 2.5, "parameterBool": true, "parameterString": "abc" }

入れ子になった実行ケースの使用例:

• 2 つのノートブックがあるとします。
  • Notebook1: 組み込みのリソースに script_file1.py が含まれています
  • Notebook2: 組み込みのリソースに script_file2.py が含まれています
• Notebook1 の作業をルート ノートブックとしてコンテンツ %run Notebook2 と共に使用してみましょう。
• 次に、Notebook2 の使用手順は次のとおりです。
  • Notebook1 (ルート Notebook) で script_file1.py を実行するときのコードは %run -b script_file1.py です
  • Notebook2 (現在の Notebook) で script_file2.py を実行するときのコードは %run -b -c script_file2.py です

変数エクスプローラー

Fabric ノートブックには、PySpark (Python) セルに対して現在の Spark セッションで変数の名前、タイプ、長さ、値のリストを表示する変数エクスプローラーが組み込まれています。 コード セルに定義されている変数が増えると、自動的に表示される変数も増えます。 各列ヘッダーをクリックすると、テーブル内の変数が並べ替えられます。

変数エクスプローラーを開く、または非表示にするにはノートブック リボンの [表示] で [変数] を選択します。

セルの状態インジケーター

セルの下に詳細なセルの実行の状態が表示されます。これは、現在の進行状況を確認するのに役立ちます。 セルの実行が完了すると、合計時間と終了時間を含む実行概要が表示され、後で参照できるように保存されます。

インライン Apache Spark ジョブ インジケーター

Fabric ノートブックは Apache Spark ベースです。 コード セルは Apache Spark クラスターでリモートで実行されます。 Spark ジョブの進行状況インジケーターが提供されます。このインジケーターにはリアルタイムの進行状況バーが含まれており、ジョブ実行のステータスを確認できます。 ジョブまたはステージごとのタスクの数では、Spark ジョブの並列レベルを特定できます。 また、ジョブ (またはステージ) の名前のリンクを選択することで、特定のジョブ (またはステージ) の Spark UI をさらに掘り下げて調べることもできます。

また、進行状況インジケーターの横にある [セル レベルのリアルタイム ログ] を見つけることもできます。また、[診断] では、コードの絞り込みとデバッグに役立つ便利な提案を提供できます。

[その他のアクション] では、[Spark アプリケーションの詳細] ページと [Spark Web UI] ページに簡単に移動できます。

シークレットの編集

ノートブックの実行中に認証情報が誤って漏洩することを避けるため、Fabric ノートブックではセル出力で表示されるシークレット値と [REDACTED] を置き換える [シークレット削除] をサポートしています。 シークレット削除は Python、Scala、R に対応しています。

ノートブックのマジック コマンド

組み込みのマジック コマンド

Fabric ノートブックでは、使い慣れた Ipython マジック コマンドを使用できます。 現在使用できるマジック コマンドをまとめた次の一覧をご確認ください。

使用可能なライン マジック コマンド: %lsmagic、%time、%timeit、%history、%run、%load、%alias、%alias_magic、%autoawait、%autocall、%automagic、%bookmark、%cd、%colors、%dhist、%dirs、%doctest_mode、%killbgscripts、%load_ext、%logoff、%logon、%logstart、%logstate、%logstop、%magic、%matplotlib、%page、%pastebin、%pdef、%pfile、%pinfo、%pinfo2、%popd、%pprint、%precision、%prun、%psearch、%psource、%pushd、%pwd、%pycat、%quickref、%rehashx、%reload_ext、%reset、%reset_selective、%sx、%system、%tb、%unalias、%unload_ext、%who、%who_ls、%whos、%xdel、%xmode。

Fabric ノートブックは、改善されたライブラリ管理コマンド %pip と %conda もサポートしています。 使用について詳しくは、Microsoft Fabric で Apache Spark ライブラリを管理するをご覧ください。

使用可能なセル マジック コマンド: %%time、%%timeit、%%capture、%%writefile、%%sql、%%pyspark、%%spark、%%csharp、%%configure、%%html、%%bash、%%markdown、%%perl、%%script、%%sh。

カスタム マジック コマンド

独自のニーズに合わせてさらにカスタム マジック コマンドを構築することもできます。 次に例を示します。

1. "MyLakehouseModule" という名前のノートブックを作成します。

   

2. 別のノートブックで、"MyLakehouseModule" とそのマジック コマンドを参照します。 このプロセスは、異なる言語を使用するノートブックを用いてプロジェクトをわかりやすく整理する仕組みです。

   

IPython ウィジェット

IPython Widgets は、ブラウザで表示される eventful Python オブジェクトです。 Jupyter ノートブックと同様、IPython Widgets をローコード管理として (スライダーまたはテキスト ボックスなど) ノートブックで使用できます。 現在、Python コンテキストでのみ動作します。

IPython Widgets を使用するには:

1. Jupyter Widget フレームワークを使用するには、まず ipywidgets モジュールをインポートします。

   import ipywidgets as widgets
   

2. 最上位の display 関数を使用してウィジェットをレンダリングするか、コード セルの最終行にウィジェット タイプの式を置きます。

   slider = widgets.IntSlider()
   display(slider)
   

3. セルを実行します。 出力領域にウィジェットが表示されます。

   slider = widgets.IntSlider()
   display(slider)
   

   

4. 複数の display() コールを使用して、同じウィジェット インスタンスを複数回レンダリングします。 相互の同期が維持されます。

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

   

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

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

   

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

既知の制限事項

• 次のウィジェットはまだサポートされていません。 次の回避策を使用できます。

  機能	回避策
  出力 ウィジェット	代わりに print() 関数を使用して、stdout にテキストを書き込むことができます。
  widgets.jslink()	widget.link() 関数を使用して、似たような 2 つのウィジェットをリンクできます。
  FileUpload ウィジェット	まだサポートされていません。

• Fabric グローバル display 関数は 1 つのセルでの複数ウィジェットの表示をサポートしていません (display(a, b) など)。 この動作は、IPython display 関数とは異なります。

• IPython ウィジェットを含むノートブックを閉じると、対応するセルをサイド実行するまで、そのノートブックを表示したり通信したりすることはできません。

• 相互作用関数 (ipywidgets.interact) はサポートされていません。

ノートブックを統合する

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

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

パラメーター セルは、パイプラインにノートブックを統合する場合に便利です。 パイプライン アクティビティはパラメータ セルを探し、このセルを実行時に渡されるパラメータの既定値として扱います。 実行エンジンは、既定値を上書きするために、入力パラメーターを含んだ新しいセルをパラメーター セルの下に追加します。

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

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

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

Spark セッション構成のマジック コマンド

マジック コマンド %%configure を使用して Spark セッションをカスタマイズできます。 Fabric ノートブックはカスタマイズされた vCore、Driver および Executor のメモリ、Apache Spark プロパティ、マウント ポイント、プール、ノートブック セッションのデフォルトのレイクハウスをサポートしています。 インタラクティブなノートブックおよびパイプライン ノートブックのアクティビティの両方で使用できます。 ノートブックの冒頭で %%configure コマンドを実行することをお勧めします。実行しない場合、設定が適用されるよう Spark セッションを再起動する必要があります。

%%configure
{
    // You can get a list of valid parameters to config 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 customized property, you can specify count of lines that Spark SQL returns by configuring "livy.rsc.sql.num-rows".
        "livy.rsc.sql.num-rows": "3000",
        "spark.log.level": "ALL"
    }
    "defaultLakehouse": {  // This overwrites the default lakehouse for current session
        "name": "<lakehouse-name>",
        "id": "<lakehouse-id>",
        "workspaceId": "<(optional) workspace-id-that-contains-the-lakehouse>" // Add workspace ID if it's from another workspace
    },
    "mountPoints": [
        {
            "mountPoint": "/myMountPoint",
            "source": "abfs[s]://<file_system>@<account_name>.dfs.core.windows.net/<path>"
        },
        {
            "mountPoint": "/myMountPoint1",
            "source": "abfs[s]://<file_system>@<account_name>.dfs.core.windows.net/<path1>"
        },
    ],
    "useStarterPool": false,  // Set to true to force using starter pool
    "useWorkspacePool": "<workspace-pool-name>"
}

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

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

{
      "parameterName": "paramterNameInPipelineNotebookActivity",
      "defaultValue": "defaultValueIfNoParamterFromPipelineNotebookActivity"
} 

%%configure  

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

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

パイプラインの実行中、次のようにパイプライン ノートブック アクティビティ設定を構成できます。

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

ノートブックへの 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 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 use 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 use 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")

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

Fabric Notebook では、現在のセッションで実行された入力コマンド履歴を出力するマジック コマンド %history がサポートされています。標準の Jupyter Ipython コマンドと比較して、%history はノートブック内の複数の言語コンテキストで機能します。

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

オプション:

• -n: 実行番号を出力します。

指定できる範囲は次のとおりです。

• N: N 番目に実行されたセルのコードを出力します。
• M-N: M 番目から N 番目に実行されたセルにコードを出力します。

例:

• 1 番目から 2 番目に実行されたセルまでの入力履歴を出力: %history -n 1-2

ショートカット キー

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

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

  

• 編集モードは、テキスト カーソルがエディター領域での入力を促すことで示される。 セルが編集モードの場合、セルに入力することができます。 Enter キーを押すか、マウスを使用してセルのエディターを選択して [編集] モードに入ります。

  

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

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

次のキーストローク ショートカットを使用すると、編集モードのときに Fabric ノートブックのコードを簡単に移動して実行できます。

ショートカット キーを見つけるには、ノートブック リボンの [表示] を選択してから [Keybindings] を選択します。

関連するコンテンツ

• Notebook の視覚化
• Fabric MSSparkUtils の概要