11 筆記本

本章提供有關使用和管理工作區中記事本的資訊。

主題：

在記事本中開發程式碼

資料工程師和資料科學家可以在他們的 Oracle AI Data Platform Workbench 中使用筆記型電腦，作為互動開發程式碼和探索資料的通用工具。

Oracle AI Data Platform Workbench 目前在筆記型電腦中支援 Python、SQL 和 Scala 語言。您可以排定記事本，或將記事本設定為在工作流程中執行。若要執行記事本，您必須連附運算叢集。

您的 AI Data Platform Workbench 隨附整合式受管理筆記型電腦，提供直觀的開發人員體驗。

您可以使用 Oracle AI Data Platform Workbench 範例 Git 儲存區域中的範例程式碼，取得可與您的筆記型電腦搭配使用的程式碼範例。

自動節省

記事本每兩分鐘會自動儲存一次。

匯入和匯出記事本

您目前可以從本機機器將記事本檔案 (*.ipynb) 匯入您的工作區。

目前不支援匯出記事本。

建立記事本

您可以在您具有管理員權限的任何工作區中建立記事本。

  1. 在首頁上，瀏覽至您的工作區。
  2. 按一下建立，然後按一下記事本。
  3. 填入名稱與說明，然後按一下「建立」。

將現有叢集連附至記事本

記事本需要連附的叢集，才能提供已開發程式碼的運算能力。

  1. 在首頁上，瀏覽至您的工作區並開啟您的記事本。
  2. 按一下動作，然後按一下附加現有叢集。
  3. 從清單中按一下您要使用的叢集。
    您的記事本將顯示順利連附的叢集：(ClusterName) 執行中。這可能需要數分鐘的時間。

建立記事本的叢集

您可以直接從記事本介面建立新叢集，然後立即附加。

如需詳細資訊，請參閱關於運算叢集。
  1. 在首頁上，瀏覽至您的工作區並開啟您的記事本。
  2. 按一下「動作」，然後按一下「建立叢集」。
  3. 選取程式實際執行版本。
  4. 選取叢集的驅動程式選項。
  5. 選取叢集的工作者選項。這些選項適用於所有叢集工作者。
  6. 選取職工人數為靜態或自動調整。
    • 如果是靜態金額，請指定工作程式的數目。
    • 如果是自動調整，請指定叢集可調整的工作程式數目下限和上限。
  7. 在執行持續時間中，選取叢集是否將在設定的無活動持續時間後停止執行。如果選取閒置逾時，請指定叢集逾時之前的閒置時間 (分鐘)。
  8. 按一下建立。

預設語言

您可以使用筆記本來開發及執行 Python、SQL 或 Scala 中的 Apache Spark 程式碼。

記事本的預設語言為 Python。您可以將整個記事本或個別儲存格的預設語言變更為 SQL、Scala、Markdown 或 raw 文字。您可以在同一記事本內的不同儲存格中結合 Python、SQL 和 Scala 程式碼。

記事本包含 Python、SQL 和 Scala 的語法突顯功能。將根據記事本的預設語言建立新的記事本儲存格。

管理記事本

您可以自行重新命名和刪除記事本。您也可以複製記事本以複製其內容，並在新的記事本中使用其程式碼。

您可以重新命名並刪除工作區中記事本的動作功能表。若要複製記事本，請開啟記事本，然後從「檔案」功能表中選取複製選項。

重新命名記事簿

如果您的筆記型電腦名稱不再有幫助或相關，您可以隨時進行變更。

  1. 在首頁上，瀏覽至您的工作區。
  2. 在您要重新命名的記事本旁邊，按一下動作，然後按一下重新命名。
  3. 輸入新名稱，然後按一下「儲存」。
  4. 選擇性：您也可以按一下名稱並輸入新記事本，來變更已開啟記事本的名稱。

刪除筆記本

您可以刪除您具有管理員權限的記事本。

  1. 瀏覽至您的工作區。
  2. 在您要刪除的記事本旁邊，按一下動作，然後按一下刪除。
  3. 按一下「刪除」。

複製記事簿

您可以複製現有的記事本來建立該記事本內容的複本，您可以在保留原始記事本的同時進行修改。

  1. 開啟您要複製的記事本。
  2. 在記事本工具列中，按一下檔案，然後按一下複製。
  3. 輸入複製的筆記型電腦的新名稱。
  4. 按一下瀏覽，選取要儲存複製記事本的工作區資料夾。如果未選取任何資料夾，複製的記事本就會建立在與您正在複製之記事本相同的資料夾中。
  5. 選取是要包含還是不包含輸出。依預設會包含輸出。清除選擇項目即可排除輸出。
  6. 按一下「複製」。複製的記事本會建立在您指定的工作區資料夾中。

編輯記事本時瀏覽資源

當您在記事本中時，您可以瀏覽左側的「目錄」或工作區物件，而無需離開您的記事本。

如果您將任何物件從左側窗格拖放至記事本，物件名稱或完整路徑會複製並貼至記事本儲存格 (視相關資訊環境而定)。


開啟的記事本具有將物件拖放至記事本中的物件

您也可以在左側窗格中，為每個目錄或工作區物件提供按鈕和相關內容功能表選項。左側導覽中的內容功能表具有複製範例代碼、複製名稱或複製路徑的選項，可讓您貼至您的記事本儲存格。


顯示在記事本左窗格中的內容功能表選項

執行記事簿

您可以在您擁有的筆記型電腦或與您共用的筆記型電腦中執行程式碼。

程式碼可以使用下列三種方法從記事本執行：視需要執行、以單次手動執行方式執行，或建立排定的記事本工作。隨選執行的工作只會執行一次。

在記事本內執行終端機命令

您可以在記事本中執行基本終端機命令或 Shell 命令，方法是在前面加上 '!'。例如，您可以使用 unzip 指令從工作區的 ZIP 檔案中擷取。


使用中的 unzip 命令範例

您也可以使用 Python 中的 subprocess 模組來執行 Shell 命令檔。


使用中的子處理程序指令範例

您也可以將原生 Python 模組 (例如 zipfile) 用於將檔案解壓縮為 Shell 指令替代的作業。

限制

Oracle AI Data Platform Workbench 目前不支援管線安裝、CI/CD、Git 或版本控制系統。

記事本儲存格的執行選項

記事本中的「執行」功能表提供在記事本中執行儲存格的選項。

< 在此處輸入區段標題 >

您可以從記事本頂端的執行功能表，找到記事本中執行儲存格的所有選項。


開啟記事本中的「執行」功能表，並顯示在記事本中執行儲存格的選項

表格 11-1 記事本儲存格的執行選項

選項 描述
全部執行 依序執行記事本中的所有儲存格。
執行選取的儲存格 執行目前選取的儲存格或儲存格 。
執行以上所有項目 執行目前選取的儲存格以及記事本中目前所選儲存格上方的任何儲存格。
執行下方所有項目 執行目前選取的儲存格以及記事本中目前所選儲存格下方的任何儲存格。
執行選取的內容 在儲存格中執行選取的程式碼區段。
跳到最後執行的儲存格 導覽至記事本中最近執行的儲存格。
清除所有的儲存格輸出 移除記事本中所有儲存格的輸出。

從記事本執行代碼

您可以選擇一次執行所有在記事本中開發的程式碼，或一次執行一個儲存格。

在記事本中執行程式碼的鍵盤快速鍵為：
  • MacOS : Cmd + Return
  • Windows : Ctrl + Enter

您可以按一下 筆記型電腦播放按鈕 播放按鈕以在單一儲存格中執行程式碼，或按一下全部執行以執行整個記事本。

  1. 在「首頁」上，按一下工作區。
  2. 導覽至您的筆記型電腦。
  3. 按一下「全部執行」。
  4. 依序按一下工作流程和工作執行，以檢查記事本工作執行的狀態。

從其他記事本執行代碼

您可以在記事本中使用 %run 魔術命令來包含來自其他記事本的程式碼。

在下列範例中，您將代碼從名為 called-notebook.ipynb 的筆記型電腦引入至筆記型電腦 caller-notebook.ipynb 。
  1. 安裝 nbconvert Python 程式庫。
  2. 在儲存格中使用 %run 命令，如下列範例所示：
    %run /Workspace/folder1/called-notebook.ipynb

遵循這些步驟之後，名為 called-notebook.ipynb 的筆記型電腦會立即使用您的使用者委派人 (即 caller-notebook.ipynb) 執行，並且使用附加的 caller-notebook.ipynb 叢集。called-notebook.ipynb 中定義的所有函式和變數都會立即出現在名為 caller-notebook.ipynb 的筆記型電腦中。

使用 oidlUtils 共用記事本輸出

您可以使用 oidlUtils 中可用的公用程式，擷取及共用筆記型電腦作業的內容輸出。

oidlUtils 是一組可供 Oracle AI Data Platform Workbench 所有使用者使用的公用程式。在記事本之間共用內容時，可以呼叫 oidlUtils 將引數傳送給一個記事本，然後將輸出傳回給呼叫者記事本，也可以在記事本的工作工作中呼叫 oidlUtils，以將輸出傳回給父項工作，也就是呼叫記事本的工作。使用這種方式，您可以擷取及使用由筆記型電腦任務傳回的結構化輸出。

這些 oidlUtils 模組可用於記事本：

模組 描述 範例
筆記本 協調記事本作業會執行，並將單一結構化結果 (通常是 JSON 字串) 傳回給呼叫者。 
oidlUtils.notebook.run(
    notebook_path: str,
    timeout_seconds: int = 0, (Optional)
    parameters: dict (Optional)
) -> str
筆記本 允許記事本結束作業執行，並將單一字串結果 (通常只有 JSON 有效負載) 傳回給呼叫端記事本或工作 / 作業輸出 API。 
oidlUtils.notebook.exit(value: str)

範例 1：記事本共用記事本

在此範例中，您可以使用記事本 A 來呼叫記事本 B。記事本 B 會傳回將記事本 A 設定為擷取與使用的結果有效負載。

筆記本 A

result = oidlUtils.notebook.run("NotebookB", 0)
print("Output from Notebook B:", result)
筆記本 B
import json

payload = {
"status": "SUCCESS",
"rows_processed": 1234,
"output_table": "sales_gold",
"run_id": "run_2026_02_11"
}

json_payload = json.dumps(payload)
oidlUtils.notebook.exit(str(json_payload))

記事本 B 的輸出

{"status": "SUCCESS", "rows_processed": 1234, "output_table": "sales_gold", "run_id": "run_2026_02_11"}

範例 2：透過工作任務傳送輸出

在此範例中，當您的記事本以工作方式執行時，會傳回 JSON 檔案：oidlUtils.notebook.exit(json.dumps(payload))。 

import json

payload = {
    "status": "SUCCESS",
    "output_table": "sales_gold",
    "rows_processed": 1234
}

oidlUtils.notebook.exit(json.dumps(payload))

接下來，您使用記事本工作執行工作，並透過 API 呼叫取得工作輸出：endpoint = f"https://<workspace-url>/jobs/runs/get-output?run_id={task_run_id}" and response = requests.get(endpoint, headers=headers).json()。 

import requests

task_run_id = "<task_run_id>"

endpoint = f"https://<workspace-url>/jobs/runs/get-output?run_id={task_run_id}"
response = requests.get(endpoint, headers=headers).json()

最後，您可以使用 job_result = response['notebook_output']['result'] 擷取記事本傳回的輸出。 

job_result = response["notebook_output"]["result"]
payload = json.loads(job_result)

print(payload["output_table"])   # Output : sales_gold
print(payload["rows_processed"]) # Output : 1234

筆記本導覽

您可以建立並維護可用來組織及瀏覽記事本的目錄。

您可以按一下記事本左上方的目錄圖示，以顯示記事本大綱。系統會根據您可建立的減價標題自動產生目錄，讓您輕鬆進行組織與瀏覽。

您可以將格式化文字、標題、清單和文件新增為 Markdown，以組織和說明您自己和其他使用者的筆記型電腦內容。

建立 Markdown 儲存格

您可以建立減價儲存格，以便在記事本目錄中提供標題，方便組織與瀏覽。

  1. 從首頁瀏覽至您的筆記型電腦。
  2. 從儲存格類型下拉清單中，選取標記。
  3. 將您的減價新增至儲存格。
    • 減價儲存格可包含格式化文字、標題、清單及其他文件。
    • 若要建立標題，請以 # 開始一行，後面接著一個空格。標題 1 使用一個 # ，標題 2 使用 ## 。為每個額外的標題層次新增額外的 # 。

記事本輸出與結果

您可以看到記事本輸出，結果會出現在含有程式碼的儲存格後方的新儲存格。

儲存格正在進行時，您可以取消儲存格的執行。如果記事本是以工作流程工作的方式執行，則相同的記事本中不會顯示輸出。在這種情況下，輸出會顯示在對應的工作流程工作執行的輸出區域中。

您可以將輸出儲存格的輸出下載為 CSV 或 Excel 檔案。您也可以將輸出儲存格的內容直接複製到剪貼簿。


顯示之記事本中的輸出儲存格，其中標示了「複製」和「下載」按鈕。已開啟「下載」功能表並顯示「下載 CSV 與下載 Excel」選項。

下載記事本輸出

您可以直接從結果面板下載記事本儲存格的結果輸出。

  1. 在您要下載輸出來源儲存格的右上方，按一下下載。
  2. 從功能表中，選取要下載輸出的格式。

複製記事本輸出

您可以直接從結果面板複製記事本儲存格的結果輸出。

  1. 在您要下載輸出的儲存格右上角，按一下複製。
  2. 輸出儲存格的內容會直接複製到您的剪貼簿。您可以將它貼到筆記型電腦中的其他位置或外部位置。

筆記本外觀

您可以將左側的導覽面板最小化或展開記事本檢視，以更改可在記事本中使用的畫面空間。

您可以按一下導覽面板右下方的最小化面板，將 Oracle AI Data Platform Workbench 左側導覽面板最小化，同時使用筆記型電腦來增加可用的畫面空間。


醒目提示「最小化面板」圖示的 AI Data Platform Workbench 左側導覽窗格

您也可以按一下記事本右上方的展開來展開記事本，展開可用空間，讓較大的儲存格和輸出更容易閱讀。


記事本開啟時會反白顯示「展開」圖示

儲存格執行編號

每個記事本儲存格都會顯示一個執行編號，指示儲存格的執行順序。此數字會在每次執行儲存格時更新。您可以依任何順序執行儲存格，因此執行編號可能不符合筆記型電腦中儲存格的實體順序。

管理工作批次

您可以建立工作執行，以管理從筆記型電腦執行程式碼的方式與時間。

手動工作執行可以再次執行，或稍後設定為在排程上執行。排定的工作執行會根據您設定的排程自動觸發。除非有設定排程，否則手動工作只會執行一次。

從記事本建立手動執行工作

您可以建立未排定的工作，從您在筆記型電腦中開發的程式碼手動執行。

  1. 在「首頁」上，按一下工作區。
  2. 導覽至您的筆記型電腦。
  3. 按一下動作，然後按一下排程。
  4. 提供工作的名稱與描述。
  5. 按一下瀏覽，然後選取儲存工作的位置。按一下「選取」。
  6. 從「叢集」下拉式清單中選取運算叢集。
  7. 若為排程，請選取手動執行。
  8. 按一下建立。

從記事本建立排定的工作執行

您可以建立從您已在筆記型電腦中開發的程式碼自動執行的排定工作。

  1. 在「首頁」上，按一下工作區。
  2. 導覽至您的筆記型電腦。
  3. 按一下動作，然後按一下排程。
  4. 提供工作的名稱與描述。
  5. 按一下瀏覽，然後選取儲存工作的位置。按一下「選取」。
  6. 從「叢集」下拉式清單中選取運算叢集。
  7. 在排程中，選取排程。
  8. 選取排程狀態。
    • 若要立即啟用排程，請選取作用中。
    • 如果您想要稍後手動啟用排定的執行，請選取已暫停。
  9. 提供排程所依據的時區。
  10. 選取排程類型。
    • 對於行事曆，您必須指定排程將重複的頻率和時數或天數。
    • 對於 Cron 表示式，您必須以 cron 表示式的形式提供排程。
  11. 請檢查底部列出的執行時間，確認您的排程是否正確。按一下建立。

筆記本鍵盤快速鍵

您可以使用鍵盤快速鍵，在記事本中使用指令來簡化。

Windows macOS 動作
Ctrl + Enter 控制 + 退貨 執行單元
Shift + Enter 班次 + 退回 執行儲存格並前進到下一個儲存格
Ctrl + S Cmd + S 儲存筆記本
Ctrl + N Ctrl + N 新建記事本
Ctrl + Z 控制 + Z 還原
Ctrl + Y 控制 + Y 重做
Ctrl + C 控制 + C 複製
Ctrl + X 控制 +X 剪下
Ctrl + V 控制 + V 貼上
Ctrl + Alt + F Ctrl + 選項 + F 尋找並取代
Ctrl + Shift + A Ctrl + Shift + A 在上方插入儲存格
Ctrl + Shift + B Ctrl + Shift + B 在下方插入儲存格
Ctrl + Alt + 向上 Ctrl + 選項 + 上移 將儲存格上移
Ctrl + Alt + 向下 Ctrl + 選項 + 向下鍵 將儲存格下移
Ctrl + D Ctrl + D 刪除單元
Alt + Shift + Enter 選項 + 班次 + 退回 全部執行
Alt + Shift + 向上 選項 + 班次 + 向上 執行以上所有儲存格

將現有的 Apache Spark 程式碼移轉至 Oracle AI Data Platform Workbench

您可以調整 Apache Spark 程式碼以移轉它以用於 Oracle AI Data Platform Workbench 筆記型電腦。

如果您要從其他平台移轉現有的 Spark 程式碼，可以使用下列準則來調整程式碼，以在筆記型電腦中使用。

表格 11-2 AI Data Platform 移轉準則的 Apache Spark

準則 詳細資訊
移除 SparkSession 建立命令 AI Data Platform Workbench 會自動為每個運算叢集建立 SparkContext。建議您移除階段作業建立命令，或以 SparkSession.builder().getOrCreate() 取代。
移除階段作業終止命令，例如 sys.exit() 或 spark.stop() 所有目的運算叢集都是共用叢集，因此如果任何使用者都停止 SparkSession (例如使用 sys.exit() 或 spark.stop())，就必須為所有人重新啟動叢集。為了避免發生中斷的情況，建議您避免筆記型電腦中的指令。