一、概述
| 类型 | 说明 | 适用范围 |
| DLCUtils 函数库 | 与 Notebook 配套的 Python 工具库，简化参数、密钥、任务通信等操作。 | 所有 Notebook 文件。 |
| 魔法命令 | Jupyter 提供的特殊指令，用于切换语法、引用其他 Notebook、安装依赖等。 | 所有 Notebook 文件。 |
二、前提条件
·Notebook 已连接 Kernel。
·你具备当前 Notebook 的「运行」「编辑」或「管理」权限。
四、常用模块概览
| 模块 | 主要函数 | 用途 |
| dlcutils.widgets | text(name, defaultValue, label)、get(name)、remove(name)、removeAll()、getAll() | 定义与获取动态参数。 |
| dlcutils.notebook | exit(value)、run(path, timeout, parameters) | Notebook 间退出参数传递与跨文件执行。 |
| dlcutils.jobs.taskValues | set(key, value)、get(taskKey, key, debugValue) | Workflow 任务间通过 taskValues 传递结果。 |
| dlcutils.secrets | get(secretName, secretVersion, region) | 从腾讯云 SSM 凭据管理服务获取加密凭据。 |
完整模块、函数清单详见 腾讯云产品文档：dlcutils 工具库及魔法命令使用指南。
六、1. 在文件内定义并获取参数
# 定义文本参数dlcutils.widgets.text(name='your_name', defaultValue='Ricky', label='Your name')# 获取参数print(dlcutils.widgets.get('your_name'))# 输出: Ricky
七、2. 在 Workflow 任务中获取上层参数（带容错）
# 获取任务参数try: task_value = dlcutils.widgets.get('task_param') if not task_value: task_value = 'default_value'except Exception: task_value = 'default_value'print(task_value)# 获取工作流参数try: workflow_value = dlcutils.widgets.get('workflow_param') if not workflow_value: workflow_value = 'default_value'except Exception: workflow_value = 'default_value'print(workflow_value)
九、上游 Notebook 退出并输出参数
# upstream.ipynbdlcutils.notebook.exit('12345')
十、下游 Notebook 接收参数
# downstream.ipynbresult = dlcutils.notebook.run('/folder/upstream.ipynb', 60)print(result)# 输出: 12345
十一、Workflow 任务间通过 taskValues 传递
# 上游任务 notebook_upstreamdlcutils.jobs.taskValues.set(key='favorite_food', value='apple')
# 下游任务 notebook_downstream（已配置上游为 notebook_upstream）value = dlcutils.jobs.taskValues.get( taskKey='notebook_upstream', key='favorite_food', debugValue='banana')print(value)# Studio 调试时输出: banana# Workflow 调度时输出: apple
注意：说明：
注意：taskValues.get 仅在 Workflow 调度运行场景下能取到上游 set 的值；在 Studio 调试运行时取的是 debugValue。
十二、通过 SSM 获取密钥
避免在代码中明文写入 AK/SK、数据库密码：
1. 前往 腾讯云 SSM 控制台 创建凭据，记录凭据名称、版本与地域。
2. 在 Notebook 中获取：
secret = dlcutils.secrets.get('my_secret', 'v1', 'ap-guangzhou')print(secret)
3. 使用密钥后续调用 SDK 或访问数据库。
十四、单元格语法切换
| 命令 | 作用 |
| %sql | 将当前单元格切换为 Spark SQL 语法。 |
| %md | 将当前单元格切换为 Markdown，仅作展示用。 |
| %scala | 将当前单元格切换为 Scala 语法（依赖引擎）。 |
%sqlSELECT count(*) FROM your_catalog.your_schema.your_table;
十五、跨文件运行
%run /path/to/another_notebook.ipynb
执行另一个 Notebook 的所有单元格，等价于将其内容内联到当前单元格。常用于公共变量与函数定义共享。
十六、依赖安装
%pip install pandas==2.2.0 jieba
在当前 Spark 会话中安装依赖。新建会话或重置环境后失效，需要重新安装。
十八、步骤 1：在 Notebook 中调用 DLCUtils
1. 确认当前 Notebook 已连接 Kernel。
2. 直接在 Python 单元格中调用 dlcutils.widgets.text(…)、dlcutils.notebook.exit(…) 等函数，无需额外 import。
十九、步骤 2：使用魔法命令切换语法
1. 在 Python 单元格的首行输入 %sql / %md / %scala。
2. 之后的代码按对应语法解释执行。
20、步骤 3：调试参数
1. 单击操作栏 参数 按钮，弹窗显示当前 Notebook 已识别的参数（含通过 dlcutils.widgets.text 定义的与可视化定义的）。
2. 在弹窗中调整参数值用于本次调试运行。
21、使用限制
·dlcutils.notebook.run / dlcutils.jobs.taskValues 在 Studio 调试运行时返回 debugValue；只有在 Workflow 调度运行场景下能取到真实上下游传递值。
·%pip install 安装的依赖不持久化；新建会话或重置环境后失效。
·Notebook 中获取参数请统一使用 dlcutils.widgets.get；不支持 ${param_key} 占位符语法（该语法仅适用于 SQL）。
22、常见问题
Q1：调用 dlcutils.widgets.get('xxx') 返回 NameError？
通常是该参数名称未被定义，可以使用dlcutils.widgets.widgets() 函数进行参数名和参数值的定义，或者在界面上点击参数 按钮，在弹窗中定义参数名称和取值。
Q2：%run 引用的 Notebook 路径怎么写？
·使用绝对路径：/workspace_1/your_username/folder/upstream.ipynb。
·使用相对路径：folder/upstream.ipynb（相对当前文件）。
·在目录中右键 复制路径 直接粘贴。
Q3：SSM 密钥的地域参数如何确定？
SSM 凭据按地域隔离，需要传入凭据创建时所在地域，例如 ap-guangzhou / ap-shanghai。可在 SSM 控制台查看凭据归属地域。
23、相关文档
·Notebook IDE 基础操作
·Notebook 运行
·参数化实现
·腾讯云产品文档：使用 dlcutils 函数库和魔法命令