开发、执行和管理 Microsoft Fabric 笔记本

Microsoft Fabric 笔记本是用于开发 Apache Spark 作业和机器学习试验的主要代码项。 它是一个基于 Web 的交互式图面，数据科学家和数据工程师可使用它来编写受益于丰富可视化效果和 Markdown 文本的代码。 本文介绍如何使用代码单元格操作开发笔记本并运行它们。

开发笔记本

笔记本由单元格组成，单元格是单独的代码块或可单独运行或作为组运行的文本块。

我们提供有丰富的操作供你开发笔记本：

• 添加单元格
• 设置主要语言
• 使用多种语言
• IDE 样式 IntelliSense
• 代码片段
• 拖放以插入代码片段
• 拖放以插入图像
• 通过工具栏按钮设置文本单元格的格式
• 撤消或重做单元格操作
• 移动单元格
• 删除单元格
• 折叠单元格输入
• 折叠单元格输出
• 单元格输出安全性
• 锁定或冻结单元格
• 笔记本内容
• Markdown 折叠
• 查找和替换

添加单元格

有多种方法可向笔记本添加新单元格。

1. 将鼠标悬停在两个单元格之间的空白地方，然后选择“代码”或“Markdown” 。

2. 使用命令模式下的快捷键。 按 A 在当前单元格上方插入单元格。 按 B 在当前单元格下方插入单元格。

设置主要语言

Fabric 笔记本当前支持 4 种 Apache Spark 语言：

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

可以从顶部命令栏中的下拉列表为新添加的单元格设置主要语言。

使用多种语言

可以通过在单元格开始位置指定语言 magic 命令，在一个笔记本中使用多种语言。 还可以从语言选取器切换单元格语言。 下表列出了用于切换单元格语言的 magic 命令。

magic 命令	语言	说明
%%pyspark	Python	针对 Spark 上下文执行 Python 查询。
%%spark	Scala	针对 Spark 上下文执行 Scala 查询。
%%sql	SparkSQL	针对 Spark 上下文执行 SparkSQL 查询。
%%html	Html	针对 Spark 上下文执行 HTML 查询。
%%sparkr	R	针对 Spark 上下文执行 R 查询。

IDE 样式 IntelliSense

Fabric 笔记本集成了 Monaco 编辑器，将 IDE 样式的 IntelliSense 引入到了单元格编辑器中。 语法突出显示、错误标记和自动代码补全功能有助于你快速编写代码并找出问题。

对于不同的语言，IntelliSense 功能处于不同的成熟度级别。 下表显示了 Fabric 支持的功能：

语言	语法突出显示	语法错误标记	语法代码补全	变量代码补全	系统函数代码补全	用户函数代码补全	智能缩进	代码折叠
PySpark (Python)	是	是	是	是	是	是	是	是
Spark (Scala)	是	是	是	是	是	是	是	是
SparkSQL	是	是	是	是	是	No	是	是
SparkR	是	是	是	是	是	是	是	是

注意

必须具有有效的 Spark 会话才能使用 IntelliSense 代码补全。

代码片段

Microsoft Fabric 笔记本提供代码片段，以帮助你轻松编写常用代码模式，例如：

• 以 Spark 数据帧的形式读取数据
• 使用 Matplotlib 绘制图表

代码片段与其他建议混合在一起显示在 IDE 样式 IntelliSense 的快捷键中。 代码片段内容与代码单元格语言一致。 你可以通过键入 Snippet 来查看可用的代码段。 还可以键入任何关键字以查看相关代码片段的列表。 例如，如果键入 read，则会看到用于从各种数据源读取数据的代码段列表。

拖放以插入代码片段

使用拖放功能轻松地从湖屋资源管理器读取数据。 此处支持多种文件类型；可以对文本文件、表、图像等进行操作。可以拖放到现有单元格，也可以拖放到新单元格。 笔记本会相应地生成代码片段来预览数据。

拖放以插入图像

使用拖放轻松地将浏览器或本地计算机中的图像插入到 Markdown 单元格中。

通过工具栏按钮设置文本单元格的格式

要完成常见的 Markdown 操作，请使用文本单元格工具栏中的格式按钮。

撤消或重做单元格操作

单击“撤消”或“恢复”，或者按 Z 或 Shift+Z 可撤消最近执行的单元格操作。 最多可以撤消或重做最近执行的 10 次历史单元格操作。

支持的撤消单元格操作：

• 插入或删除单元格。 可以通过选择“撤消”来撤消删除操作（文本内容与单元格一起保留）。
• 对单元格进行重新排序。
• 切换参数。
• 在代码单元格和 Markdown 单元格之间转换。

注意

无法撤销单元格内文本操作和代码单元格注释操作。 最多可以撤消或重做最近执行的 10 次历史单元格操作。

移动单元格

可以从单元格的空白部分拖动，并将其拖放到所需的位置。

还可使用功能区上的“上移”和“下移”来移动所选单元格。

删除单元格

若要删除单元格，请选择单元格右侧的删除按钮。

还可以使用命令模式中的快捷键。 按 Shift+D 删除当前单元格。

折叠单元格输入

在单元格工具栏上选择“更多命令”省略号 (...) 和“隐藏输入”以折叠当前单元格的输入。 若要展开它，请在单元格处于折叠状态时选择“显示输入”。

折叠单元格输出

在单元格工具栏上选择“更多命令”省略号 (...) 和“隐藏输出”以折叠当前单元格的输出。 若要再次展开，请在单元格输出处于折叠状态时选择“显示输出”。

单元格输出安全性

用户可以使用 OneLake 数据访问角色（预览版）配置仅对笔记本查询过程中的某个 lakehouse 中的特定文件夹进行访问。 无权访问文件夹或表的用户在查询执行期间将看到未经授权的错误。

重要

安全性仅在查询执行期间适用，任何包含查询结果的笔记本单元都可以由无权直接对数据运行查询的用户查看。

锁定或冻结单元格

通过锁定和冻结单元格操作，可以将单元格设置为只读，或停止在单个单元格上运行代码单元格。

合并和拆分单元格

你可以使用“与上一个单元格合并”或“与下一个单元格合并”来方便地合并相关单元格。

选择“拆分单元格”有助于将无关的语句拆分为多个单元格。 该操作根据光标的行位置拆分代码。

笔记本内容

如果选择大纲（也称为“目录”），则会在边栏窗口中显示任何 markdown 单元格的第一个 markdown 标题，便于快速导航。 大纲边栏可根据最适合屏幕的方式调整大小和折叠。 选择笔记本命令栏上的“内容”按钮，来打开或隐藏边栏。

Markdown 折叠

通过 Markdown 折叠选项，可隐藏包含标题的 Markdown 单元格下的单元格。 执行单元格操作时，Markdown 单元格及其隐藏单元格的处理与一组连续多选单元格相同。

查找和替换

查找和替换选项可以帮助你匹配和查找笔记本内容中的关键字或表达式。 还可以将目标字符串轻松替换为新字符串。

运行笔记本

你可以逐个或同时在笔记本中运行代码单元格。 每个单元格的状态和进度都显示在笔记本中。

运行单元格

可以通过多种方法在单元格中运行代码。

• 将鼠标悬停在要运行的单元格上，并选择“运行单元格”按钮，或按 Ctrl+Enter。

• 使用命令模式下的快捷键。 按 Shift+Enter 运行当前单元格并选择下一个单元格。 按 Alt+Enter 运行当前单元格并插入一个新单元格。

运行所有单元格

选择“全部运行”按钮，按顺序运行当前笔记本中的所有单元格。

运行上方或下方的所有单元格

展开“全部运行”中的下拉列表，然后选择“运行上面的单元”，按顺序运行当前单元格上方的所有单元格。 选择“运行下方的单元格”，按顺序运行当前单元格及其下方的所有单元格。

取消所有正在运行的单元格

选择“全部取消”可取消正在运行的单元格或在队列中等待的单元格。

停止会话

“停止会话”将取消正在运行和等待的单元格，并停止当前会话。 可再次选择“运行”选项来重启全新的会话。

引用运行

引用运行笔记本

除了 mssparkutils 引用运行 API，还可使用 %run <notebook name> magic 命令在当前笔记本的上下文中引用另一个笔记本。 引用笔记本中定义的所有变量在当前笔记本中都可用。 %run magic 命令支持嵌套调用，但不支持递归调用。 如果语句超过 5 行，你会收到异常。

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

可以在交互模式和管道中使用笔记本引用。

注意

• %run 命令当前仅支持引用当前笔记本所在的工作区中的笔记本。
• %run 命令目前最多只支持四种参数值类型：int、float、bool 和 string。 不支持变量替换操作。
• %run 命令不支持深度大于五的嵌套引用。

引用运行脚本

该 %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" }

注意

如果命令不包含 -b/--builtin，它将尝试在同一工作区中而不是内置资源中查找和执行笔记本项。

嵌套运行用例的用法示例：

• 假设我们有两个笔记本。
  • Notebook1：其内置资源中包含 script_file1.py
  • Notebook2：其内置资源中包含 script_file2.py
• 让我们使用 Notebook1 作为根笔记本，其包含以下内容：%run Notebook2。
• 然后在 Notebook2 中，使用说明为：
  • 若要在 Notebook1（根笔记本）中运行 script_file1.py，代码将为：%run -b script_file1.py
  • 若要在 Notebook2（当前笔记本）中运行 script_file2.py，代码将为：%run -b -c script_file2.py

变量资源管理器

Fabric 笔记本提供了一个内置的变量浏览器，可以显示 PySpark (Python) 单元格的当前 Spark 会话中的变量名称、类型、长度和值的列表。 在代码单元格中定义变量时，系统会自动显示这些变量。 单击每个列标题时，会对表中的变量进行排序。

要打开或隐藏变量资源管理器，请在记事本功能区“视图”上选择“变量”。

注意

变量资源管理器仅支持 Python。

单元格状态指示器

逐步单元格执行状态显示在单元格下方，有助于你查看其当前进度。 单元格运行完成后，会显示具有总持续时间和结束时间的执行摘要，并将其保存在此处供将来参考。

内联 Spark 作业指示器

Fabric 笔记本是基于 Spark。 代码单元格在 Spark 群集上远程执行。 Spark 作业进度指示器提供有实时进度栏，可帮助你了解作业执行状态。 每个作业或阶段的任务数有助于识别 spark 作业的并行级别。 还可选择作业（或阶段）名称上的链接，来更深入地了解特定作业（或阶段）的 Spark UI。

还可在进度指示器旁边找到单元格级实时日志，诊断可以为你提供有用的建议，来帮助优化和调试代码。

在“更多操作”中，可以轻松导航到“Spark 应用程序详细信息”页和“Spark Web UI”页。

机密编修

为防止凭据在运行笔记本电脑时意外泄露，Fabric 笔记本电脑支持机密修订，可将单元格输出中显示的机密值替换为 [REDACTED]。 机密修订适用于 Python、Scala 和 R。

笔记本中的 Magic 命令

内置 magic 命令

可以在 Fabric 笔记本中使用熟悉的 Ipython magic 命令。 查看以下列表，其中列出了目前可用的 magic 命令。

注意

Fabric 管道中仅支持以下几条 magic 命令：%%pyspark、%%spark、%%csharp、%%sql、%%configure。

可用行 magics 命令：%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 库。

可用单元格 magic 命令：%%time、%%timeit、%%capture、%%writefile、%%sql、%%pyspark、%%spark、%%csharp、%%configure、%%html、%%bash、%%markdown、%%perl、%%script、%%sh。

自定义 magic 命令

还可以构建更多自定义 magic 命令以满足特定需求。 下面是一个示例：

1. 创建名为“MyLakehouseModule”笔记本。

   

2. 在另一个笔记本中，参考 "MyLakehouseModule" 及其 magic 命令。 此过程介绍如何使用使用不同语言的笔记本方便地组织项目。

   

IPython 小组件

IPython 小组件是事件化的 python 对象，它们在浏览器中具有表示形式。 你可以在笔记本中使用 IPython 小部件作为低代码控件（例如，滑块或文本框），就像 Jupyter 笔记本一样。 目前仅适用于 Python 上下文。

使用 IPython 小组件

1. 首先导入 ipywidgets 模块才能使用 Jupyter 小部件框架。

   import ipywidgets as widgets
   

2. 使用顶级 display 函数来呈现小组件，或者在代码单元格的最后一行保留 widget 类型的表达式。

   slider = widgets.IntSlider()
   display(slider)
   

3. 运行该单元。 小组件显示在输出区域中。

   slider = widgets.IntSlider()
   display(slider)
   

   

4. 使用多个 display() 调用来多次呈现同一个小部件实例。 它们彼此保持同步。

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

   

5. 若要呈现两个彼此独立的小组件，请创建两个小组件实例：

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

   

支持的小组件

小组件类型	小组件
数字小组件	IntSlider、FloatSlider、FloatLogSlider、IntRangeSlider、FloatRangeSlider、IntProgress、FloatProgress、BoundedIntText、BoundedFloatText、IntText、FloatText
布尔小组件	ToggleButton、Checkbox、Valid
选择小组件	Dropdown、RadioButtons、Select、SelectionSlider、SelectionRangeSlider、ToggleButtons、SelectMultiple
字符串小组件	Text、TextArea、Combobox、Password、Label、HTML、HTML Math、Image、Button
播放（动画）小组件	DatePicker、ColorPicker、Controller
容器或布局小组件	Box、HBox、VBox、GridBox、Accordion、Tabs、Stacked

已知的限制

• 尚不支持以下小组件。 可采用以下解决方法：

  功能	解决方法
  输出小组件	可改为使用 print() 函数来将文本写入 stdout。
  widgets.jslink()	可使用 widgets.link() 函数来链接两个相似的小组件。
  FileUpload 小组件	尚不支持。

• Fabric 全局 display 函数不支持在一个调用中显示多个小部件（例如，display(a, b)）。 此行为不同于 IPython 的 display 函数。

• 如果关闭包含 IPython 小组件的笔记本，则在再次执行相应的单元格之前，你无法看到它，也无法与之交互。

集成笔记本

指定参数单元格

若要将笔记本参数化，请选择省略号 (…) 来访问单元格工具栏上的“更多”命令。 然后选择“切换参数单元格”，将该单元格指定为参数单元格。

在管道中集成笔记本时，参数单元格非常有用。 管道活动会查找参数单元格，并将此单元格作为执行时传入的参数的默认单元格。 执行引擎会使用输入参数在参数单元格下面添加新的单元格，以覆盖默认值。

从管道分配参数值

使用参数创建笔记本后，可以使用 Fabric 笔记本活动从管道中执行该笔记本。 将活动添加到管道画布后，便可以在“设置”选项卡的“基参数”部分设置参数值。

分配参数值时，可以使用管道表达式语言或函数和变量。

Spark 会话配置 magic 命令

可以使用 magic 命令 %%configure 来个性化你的 Spark 会话。 Fabric 笔记本支持自定义 vCore、驱动程序和执行程序的内存、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 中为“DriverMemory”和“ExecutorMemory”设置相同的值。 “driverCores”和“executorCores”值也应相同。
• “defaultLakehouse”将覆盖湖屋资源管理器中固定的湖屋，但仅适用于当前笔记本会话。
• 可以在 Fabric 管道中使用 %%configure，但如果未在第一个代码单元格中设置它，管道运行将因无法重新启动会话而失败。
• 在 mssparkutils.notebook.run 中使用的 %%configure 将被忽略，但在 %run 笔记本中使用的将继续执行。
• 必须在“conf”正文中使用标准 Spark 配置属性。 Fabric 不支持 Spark 配置属性的第一级引用。
• 包括“spark.driver.cores”、“spark.executor.cores”、“spark.driver.memory”、“spark.executor.memory”和“spark.executor.instances”在内等某些特殊的 spark 属性不会在“conf”正文中生效。

管道中的参数化会话配置

参数化会话配置使你能够将 %%configure magic 中的值替换为管道运行（笔记本活动）参数。 在准备 %%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。

注意

• 如果管道运行失败，因为使用了 %%configure magic 命令，请在笔记本的交互模式下运行 %%configure magic 单元格来查找更多错误信息。
• 笔记本计划运行不支持参数化会话配置。

笔记本中的 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 笔记本支持 magic 命令 %history 来打印在当前会话中执行的输入命令历史记录，与标准 Jupyter Ipython 命令相比，%history 适用于笔记本中的多种语言上下文。

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

相关选项：

• -n：打印执行编号。

其中范围可以为：

• N：打印 第 N 个执行单元格的代码。
• M-N：打印从第 M 个到第 N 个执行单元格的代码。

示例：

• 打印从第 1 个到第 2 个执行的单元格的输入历史记录：%history -n 1-2

快捷键

与 Jupyter 笔记本类似，Fabric 笔记本具有模式用户界面。 键盘根据笔记本单元格的具体模式执行不同的任务。 Fabric 笔记本支持对给定代码单元格使用两种模式：命令模式和编辑模式。

• 当没有文本光标提示你键入时，单元格处于命令模式。 当单元格处于命令模式时，可以将笔记本作为一个整体进行编辑，但不能键入单独的单元格。 按 ESC 或使用鼠标选择单元格编辑器区域外部，进入命令模式。

  

• 编辑模式可由文本光标指示，提示你在编辑器区域中键入内容。 当单元格处于编辑模式时，可以在单元格中键入内容。 按 Enter 或使用鼠标选择单元格的编辑器区域，进入编辑模式。

  

命令模式下的快捷键

Action	笔记本快捷方式
运行当前单元格并选择下方的单元格	Shift+Enter
运行当前单元格并在下方插入	Alt+Enter
运行当前单元格	Ctrl+Enter
选择上方的单元格	向上
选择下方的单元格	向下
选择上一个单元格	K
选择下一个单元格	J
在上方插入单元格	A
在下方插入单元格	B
删除所选单元格	Shift + D
切换到编辑模式	Enter

编辑模式下的快捷键

使用以下击键快捷方式，可以在编辑模式下轻松地在 Fabric 笔记本中导航并运行代码。

操作	笔记本快捷方式
上移光标	向上
下移光标	向下
撤消	Ctrl+Z
重做	Ctrl+Y
注释或取消注释	Ctrl+/ 注释：Ctrl + K + C 取消注释：Ctrl + K + U
删除插入提示之前的字	Ctrl+Backspace
删除插入提示之后的字	Ctrl+Delete
转到单元格开头	Ctrl+Home
转到单元格末尾	Ctrl+End
左移一个字	Ctrl+Left
右移一个字	Ctrl+Right
全选	Ctrl+A
缩进	Ctrl+]
取消缩进	Ctrl+[
切换到命令模式	Esc

若要查找所有快捷键，请选择笔记本功能区上的“视图”，然后选择“键绑定”。

相关内容

• 笔记本可视化效果
• Fabric MSSparkUtils 简介