笔记本电脑软件工程最佳实践
本文提供了一个动手演练,演示了如何将软件工程最佳实践应用到Databricks笔记本,包括版本控制、代码共享、测试,以及可选的持续集成和持续交付或部署(CI/CD)。
在本演练中,您将:
将笔记本添加到Databricks Repos进行版本控制。
从一个笔记本中提取部分代码到一个可共享的模块中。
测试共享代码。
运行Databricks作业中的笔记本。
可选地将CI/CD应用于共享代码。
需求
要完成此演练,必须提供以下资源:
控件的远程存储库Git提供者Databricks支持的。本文的演练使用GitHub。本演练假设您有一个名为
best-notebooks
可用。(您可以给您的存储库一个不同的名称。如果有,那就换掉best-notebooks
在本演练中使用您的回购名称。)创建一个GitHub回购如果你还没有。请注意
如果您创建了一个新的repo,请确保使用至少一个文件初始化存储库,例如a
自述
文件。一个砖通用的集群在工作空间中。要在设计阶段运行笔记本电脑,您将笔记本连接到正在运行的通用集群.稍后,本演练将使用Databricks工作在此集群上自动运行笔记本电脑。(也可以在上面运行作业工作的集群它们只存在于工作的一生中。)创建通用集群如果你还没有。
请注意
要使用Databricks Repos中的文件,参与集群必须安装Databricks Runtime 8.4或更高版本。Databricks建议这些集群安装最新的长期支持(LTS)版本,即Databricks Runtime 10.4 LTS。
预排
在本演练中,您将:
将现有的GitHub回购连接到Databricks回购。
将现有的笔记本添加到回购中,然后第一次运行该笔记本。
将一些代码从笔记本移动到共享模块中。第二次运行notebook以确保notebook按预期调用共享代码。
使用第二个笔记本分别测试共享代码,而无需再次运行第一个笔记本。
创建Databricks作业以自动运行两个笔记本,可以按需运行,也可以定期运行。
设置repo以在repo中创建拉取请求时运行第二个notebook来测试共享代码。
发出更改共享代码的拉取请求,这将触发测试自动运行。
下面的步骤将引导您完成这些活动。
步骤
步骤1:设置Databricks Repos
在这一步中,您将现有的GitHub回购连接到现有Databricks工作区中的Databricks回购。
为了使您的工作空间连接到您的GitHub回购,您必须首先向您的工作空间提供您的GitHub凭据,如果您还没有这样做的话。
步骤1.1:提供你的GitHub凭证
在你的工作空间里侧边栏在数据科学与工程或Databricks机器学习环境中,点击>用户设置.
在用户设置页面,点击Git集成.
在Git集成选项卡,Git提供者中,选择GitHub.
为Git提供商用户名或电子邮件,输入你的GitHub用户名。
为令牌,进入你的GitHub个人访问令牌.标记必须具有回购许可。
点击保存.
步骤1.2:连接到你的GitHub回购
的侧栏上数据科学与工程或Databricks机器学习环境中,点击回购.
在回购窗格中,单击添加回购.
在添加回购对话框:
点击克隆远程Git回购.
为Git存储库URL,进入GitHub使用HTTPS克隆URL为您的GitHub回购。本文假设您的URL以
best-notebooks.git
例如,https://github.com/ < your-GitHub-username > / best-notebooks.git
.的下拉列表中Git存储库URL中,选择GitHub.
离开回购的名字例如,设置为您的回购的名称
best-notebooks
.点击创建.
步骤2:导入并运行笔记本
在这一步中,您将一个现有的外部笔记本导入到您的repo中。您可以为本演练创建自己的笔记本,但为了加快速度,我们在这里为您提供了笔记本。
步骤2.1:在回购中创建一个工作分支
在此子步骤中,您将创建一个名为eda
在你的回购中。这个分支使您能够独立于您的repo处理文件和代码主要
分支,这是软件工程的最佳实践。(你可以给你的分支一个不同的名字。)
请注意
在一些回购中主要
分支可以命名为主
代替。如果是,替换主要
与主
在本演练中。
提示
如果您不熟悉在Git分支中工作,请参见Git分支-果壳中的分支在Git网站上。
如果回购窗格未显示,则在侧栏中数据科学与工程或Databricks机器学习环境中,点击回购.
属性中未显示在上一步中连接的回购回购窗格,然后选择您的工作区用户名,并选择您在上一步中连接到的repo的名称。
单击回购名称旁边的下拉箭头,然后单击Git.
在best-notebooks对话框,单击+(创建分支)按钮。
请注意
如果你的回购标的不是
best-notebooks
,这个对话框的标题在这里和整个演练过程中都是不同的。输入
eda
然后按“Enter”。关闭对话框。
步骤2.2:将笔记本导入到repo中
在此子步骤中,您将从另一个回购中导入现有笔记本到您的回购中。这个笔记本有以下功能:
文件中复制CSV文件owid / covid-19-dataGitHub存储库到您工作空间中的集群。此CSV文件包含来自世界各地的关于COVID-19住院和重症监护指标的公开数据。
过滤数据以只包含来自美国的指标。
显示数据的图形。
将熊猫数据帧保存为Spark上的Pandas APIDataFrame.
在Spark DataFrame的Pandas API上执行数据清理。
在Spark DataFrame上写入Pandas API差值表在你的工作空间。
显示Delta表的内容。
虽然您可以在这里的repo中创建自己的笔记本,但在这里导入现有笔记本有助于加快本演练的速度。若要在此分支中创建笔记本,或将现有笔记本移动到此分支中而不是导入笔记本,请参见文件基本用法.
在回购窗格的回购,单击回购名称旁边的下拉箭头,然后单击创建文件夹>.
在新文件夹名称对话框中,输入
笔记本电脑
,然后按创建文件夹.在回购窗格中,单击您的回购名称,单击旁边的下拉箭头笔记本电脑文件夹,然后单击进口.
在进口笔记本电脑对话框:
为进口的中,选择URL.
的原始内容的URL
covid_eda_raw
笔记本电脑砖/ notebook-best-practices
在GitHub repo。获取此URL:单击
笔记本电脑
文件夹中。单击
covid_eda_raw.py
文件。点击生.
复制完整的URL从您的网络浏览器的地址栏到进口笔记本电脑对话框。
请注意
的进口笔记本电脑对话框只适用于公共存储库的Git url。
点击进口.
步骤2.3:运行笔记本
如果笔记本尚未显示,则在回购窗格,双击covid_eda_raw笔记本电脑在笔记本电脑文件夹打开它。
在笔记本上,在下拉列表旁边文件,选择要附加此笔记本的集群。
点击运行所有.
如果出现提示,请单击连接&运行或启动,连接&运行.
等一下,让笔记本运行起来。
在笔记本完成运行后,您应该在笔记本中看到一个数据图,以及Delta表中的600多行原始数据。如果在开始运行此笔记本时集群尚未运行,则在显示结果之前集群可能需要几分钟才能启动。
步骤2.4:签入并合并笔记本
在此子步骤中,您将迄今为止的工作保存到GitHub回购中。然后将工作分支中的笔记本合并到回购分支中主要
分支。
在回购窗格,单击eda分支。
在best-notebooks对话,在变化Tab,确保笔记本/ covid_eda_raw.py选中“文件”。
为总结(必需),输入
添加生笔记本
.为描述(可选),输入
这是的第一个版本的的笔记本。
点击提交&推送.
点击历史,或按在git提供程序上创建一个pull请求链接在弹出窗口。
在GitHub中,单击把请求选项卡,创建拉取请求,然后将拉取请求合并到
主要
分支。回到Databricks工作空间,关闭best-notebooks对话框,如果它仍然显示。
步骤5:创建一个作业来运行这些笔记本
在前面的步骤中,您手动测试了共享代码并手动运行了笔记本电脑。在这一步中,您将使用Databricks作业来测试您的共享代码并自动运行您的笔记本,可以按需运行,也可以定期运行。
步骤5.1:创建一个作业任务来运行测试笔记本
的侧栏上数据科学与工程或Databricks机器学习环境中,点击工作流.
在工作选项卡上,单击创建工作.
为为你的工作添加一个名称(就在运行而且任务标签),输入
covid_report
.为任务名称,输入
run_notebook_tests
.为类型中,选择笔记本.
为源中,选择Git.
点击添加git引用.
在Git信息对话框:
为Git存储库URL,进入GitHub使用HTTPS克隆URL为您的GitHub回购。本文假设您的URL以
best-notebooks.git
例如,https://github.com/ < your-GitHub-username > / best-notebooks.git
.为Git提供者中,选择GitHub.
为Git引用(分支/标签/提交),输入
主要
.旁边Git引用(分支/标签/提交)中,选择分支.
点击确认.
为路径,输入
笔记本/ run_unit_tests
.不要添加. py
文件扩展名。为集群,选择上一步中的集群。
点击创建.
请注意
在此情况下,Databricks不建议您使用中所述的笔记本中的日程按钮创建和管理定时笔记本作业计划一个作业定期运行此笔记本。这是因为计划按钮通过使用最新的操作来创建作业工作在工作区中复制笔记本的副本。相反,Databricks建议您按照上述说明创建使用最新版本的作业承诺回购中笔记本的版本。
步骤5.2:创建一个作业任务来运行主笔记本
单击+(在这里为你的工作添加更多的任务)图标。
为任务名称,输入
run_main_notebook
.为类型中,选择笔记本.
为路径,输入
笔记本/ covid_eda_modular
.不要添加. py
文件扩展名。为集群,选择上一步中的集群。
点击创建任务.
步骤5.3运行job
点击现在运行.
在弹出窗口中单击查看运行.
请注意
如果弹出窗口消失得太快,请执行以下操作:
的侧栏上数据科学与工程或Databricks机器学习环境中,点击工作流.
在工作运行选项卡,单击开始时间值为最新的工作与covid_report在工作列。
要查看作业结果,请单击run_notebook_tests瓷砖,run_main_notebook瓷砖,或者两者都有。每个磁贴的结果与您自己逐一运行笔记本的结果相同。
请注意
这项工作按需进行。要设置此作业以定期运行,请参见安排一份工作.
(可选)步骤6:设置repo以测试代码,并在代码更改时自动运行笔记本
在前面的步骤中,您使用了一个作业来自动测试共享代码,并在某个时间点或周期性地运行您的笔记本。但是,您可能更喜欢在更改合并到GitHub回购时自动触发测试。您可以通过使用CI/CD平台来执行这种自动化,例如bob体育客户端下载GitHub的行为.
步骤6.1:设置GitHub对工作区的访问
在此子步骤中,您将设置一个GitHub Actions工作流,每当更改合并到存储库中时,该工作流将在工作区中运行作业。你可以通过给GitHub一个唯一的Databricks令牌来访问。
出于安全原因,Databricks不建议您将Databricks工作区用户的个人访问令牌提供给GitHub。相反,Databricks建议您给GitHub一个Databricks访问令牌,该令牌与Databricks服务主体相关联。有关说明,请参见AWS部份运行Databricks Notebook GitHub Action页面在GitHub行动市场。
重要的
笔记本使用与令牌关联的标识的所有工作区权限运行,因此Databricks建议使用服务主体。如果您真的想将Databricks工作区用户的个人访问令牌提供给GitHub,仅用于个人探索目的,并且您理解出于安全原因Databricks不鼓励这种做法,请参阅说明创建工作区用户的个人访问令牌.
步骤6.2:添加GitHub Actions工作流
在此子步骤中,您将添加一个GitHub Actions工作流来运行run_unit_tests
笔记本每当有一个拉请求到回购。
此子步骤将GitHub Actions工作流存储在一个文件中,该文件存储在你的GitHub repo的多个文件夹级别中。GitHub Actions要求在你的repo中存在一个特定的嵌套文件夹层次结构,以便正常工作。要完成此步骤,您必须使用GitHub回购的网站,因为Databricks回购用户界面不支持创建嵌套的文件夹层次结构。
在GitHub回购的网站上,单击代码选项卡。
在切换分支或标签下拉列表,选择主要,如果尚未选中。
如果切换分支或标签下拉列表中不显示查找或创建一个分支框中,单击主要一次。
在查找或创建一个分支框中,输入
adding_github_actions
.点击创建分支:adding_github_actions from ' main '.
点击新建文件>.
为为文件命名,输入
.github /工作流/ databricks_pull_request_tests.yml
.在编辑器窗口中,输入以下代码。此代码使用声明pull_request钩子来使用运行Databricks Notebook GitHub Action运行
run_unit_tests
笔记本。在下面的代码中,替换:
< your-workspace-instance-URL >
用你的数据库实例名.< your-access-token >
使用前面生成的令牌。< your-cluster-id >
有了目标集群ID.
的名字:运行合并前数据库测试在:pull_request:env:将此值替换为您的工作空间实例名。DATABRICKS_HOST:https:// < your-workspace-instance-name >工作:unit-test-notebook:运行在:ubuntu-latesttimeout-minutes:15步骤:-的名字:检验回购使用:行动/ checkout@v2-的名字:运行测试笔记本使用:砖/ run-notebook@main与:databricks-token:< your-access-token >local-notebook-path:笔记本/ run_unit_tests.pyexisting-cluster-id:< your-cluster-id >git-commit:“$ {{github.event.pull_request.head.sha}}”#授予所有用户查看笔记本结果的权限,这样他们就可以#查看结果的笔记本,如果他们有相关的访问权限。access-control-list-json:>[{“group_name”:“用户”,:“permission_level CAN_VIEW”}]run-name:“EDA转换助手模块单位测试”
选择为这个提交创建一个新的分支,并开始一个拉请求.
点击提出新文件.
单击把请求选项卡,然后创建拉取请求。
在拉取请求页面上,等待旁边的图标运行预合并Databricks测试/ unit-test-notebook (pull_request)显示绿色复选标记。(图标可能需要一段时间才能出现。)如果选中的是红色的X,而不是绿色的,请单击细节找出原因。如果图标或细节不再显示,点击显示所有检查.
如果出现绿色复选标记,则将拉取请求合并到
主要
分支。