notebookutils.notebookを使用して、Microsoft Fabric でプログラムによってノートブック項目を管理します。 ノートブック項目の作成、取得、更新、削除、リスト作成により、デプロイ、ライフサイクル管理、CI/CDワークフローの自動化が可能です。
注
これらの API は、Azure Synapse ではなく、Fabric ノートブックでのみサポートされます。 操作ごとに、ターゲット ワークスペースに適切なアクセス許可が必要です。
次の表に、使用可能なノートブック管理方法を示します。
| メソッド | 署名 | 説明 |
|---|---|---|
create |
create(name, description, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId): Artifact |
新しいノートブックを作成します。 |
get |
get(name, workspaceId): Artifact |
名前または ID でノートブックを取得します。 |
getDefinition |
getDefinition(name, workspaceId, format): String |
ノートブック定義 (コンテンツ) を取得します。 |
update |
update(name, newName, description, workspaceId): Artifact |
ノートブックのメタデータを更新します。 |
updateDefinition |
updateDefinition(name, content, defaultLakehouse, defaultLakehouseWorkspace, workspaceId, environmentId, environmentWorkspaceId): bool |
ノートブックの定義と lakehouse を更新します。 |
delete |
delete(name, workspaceId): Boolean |
ノートブックを削除する。 |
list |
list(workspaceId, maxResults): Array[Artifact] |
ワークスペース内のすべてのノートブックを一覧表示します。 |
ノートブックを作成する
notebookutils.notebook.create()を使って、現在のワークスペースや指定されたワークスペースで新しいノートブック項目を作成します。
注
ファイルの読み取りまたは書き込み .ipynb この記事のワークフローの例では、ファイル I/O に Python を使用します。 特に明記されていない限り、コア notebookutils.notebook API は Python、PySpark、Scala、R で使用できます。
パラメーター
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
name |
糸 | はい | 新しいノートブックの表示名。 ワークスペース内で一意である必要があります。 |
description |
糸 | いいえ | ノートブックの説明。 既定値は空です。 |
content |
文字列、バイト、またはディクショナリ | はい | 有効な .ipynb JSON 形式のノートブック コンテンツ。 生バイトまたは dict オブジェクトを指定することもできます。
空にすることはできません。 |
defaultLakehouse |
糸 | いいえ | アタッチする既定のレイクハウスの名前または ID。 |
defaultLakehouseWorkspace |
糸 | いいえ | 既定のレイクハウスのワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
workspaceId |
糸 | いいえ | ターゲット ワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
Important
content パラメーターを空にすることはできません。 ノートブックを作成するときは、有効な .ipynb 形式のコンテンツを指定する必要があります。 少なくとも、有効な空のノートブック構造を指定します。
{
"cells": [],
"metadata": {},
"nbformat": 4,
"nbformat_minor": 5
}
テンプレートからノートブックを作成する
# Read notebook template from a file
with open("/path/to/template.ipynb", "r") as f:
notebook_content = f.read()
# Create the notebook
notebook = notebookutils.notebook.create(
name="ProcessingNotebook",
description="Data processing notebook from template",
content=notebook_content
)
print(f"Created notebook: {notebook.displayName} (ID: {notebook.id})")
既定の lakehouse を使用してノートブックを作成する
# Minimum valid notebook content - content cannot be empty
minimal_content = '''{
"cells": [],
"metadata": {},
"nbformat": 4,
"nbformat_minor": 5
}'''
# Create notebook with default lakehouse configuration
notebook = notebookutils.notebook.create(
name="DataAnalysis",
description="Analysis notebook with lakehouse access",
content=minimal_content,
defaultLakehouse="MyLakehouse",
defaultLakehouseWorkspace="" # Current workspace
)
print(f"Created notebook with lakehouse: {notebook.displayName}")
値を返す
create() メソッドは、次のプロパティを持つArtifact オブジェクトを返します。
-
displayName: ノートブックの表示名。 -
id: 作成されたノートブックの一意の識別子。 -
description: ノートブックの説明。
別のワークスペースにノートブックを作成する
with open("/path/to/notebook.ipynb", "r") as f:
content = f.read()
notebook = notebookutils.notebook.create(
name="SharedNotebook",
description="Notebook for the shared workspace",
content=content,
workspaceId="bbbbbbbb-2222-3333-4444-cccccccccccc"
)
print(f"Created in remote workspace: {notebook.displayName}")
テンプレートから複数のノートブックを作成する
# Load template content (must be valid .ipynb)
with open("/path/to/template.ipynb", "r") as f:
template_content = f.read()
regions = ["US", "EU", "Asia"]
created_notebooks = []
for region in regions:
notebook = notebookutils.notebook.create(
name=f"Process_{region}",
description=f"Processing notebook for {region} region",
content=template_content,
defaultLakehouse=f"Lakehouse_{region}"
)
created_notebooks.append(notebook)
print(f"Created: {notebook.displayName}")
print(f"\nCreated {len(created_notebooks)} notebooks")
ヒント
ノートブックを見つけやすくするために、わかりやすい名前と説明を入力します。 自動デプロイには、 <Project>_<Purpose>_<Region> などの一貫した名前付け規則を使用します。
ノートブックを取得する
notebookutils.notebook.get()を使用して、名前または ID でノートブックのメタデータを取得します。
Artifact、displayName、idなどのプロパティを持つdescription オブジェクトを返します。
パラメーター
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
name |
糸 | はい | 取得するノートブックの名前または ID。 |
workspaceId |
糸 | いいえ | ワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
現在のワークスペースからノートブックを取得する
notebook = notebookutils.notebook.get("MyNotebook")
print(f"Notebook Name: {notebook.displayName}")
print(f"Notebook ID: {notebook.id}")
print(f"Description: {notebook.description}")
別のワークスペースからノートブックを取得する
workspace_id = "bbbbbbbb-2222-3333-4444-cccccccccccc"
notebook = notebookutils.notebook.get("SharedNotebook", workspaceId=workspace_id)
print(f"Retrieved: {notebook.displayName} from workspace {workspace_id}")
値を返す
get() メソッドは、次のプロパティを持つArtifact オブジェクトを返します。
-
displayName: ノートブックの表示名。 -
id: 一意の識別子。 -
description: ノートブックの説明。
ヒント
更新操作または削除操作の前に get() を使用して、ターゲット ノートブックが存在することを確認します。 また、新しいノートブック名を作成する前に、ノートブック名が既に使用されているかどうかを確認することもできます。
ノートブック定義を取得する
notebookutils.notebook.getDefinition()を使用して、完全なノートブック コンテンツを.ipynb形式で取得します。 バックアップ、移行、バージョン管理、またはコンテンツ分析に使用します。
パラメーター
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
name |
糸 | はい | ノートブックの名前または ID。 |
workspaceId |
糸 | いいえ | ワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
format |
糸 | いいえ | 出力フォーマット。 既定値は "ipynb" です。 |
ノートブック定義を取得して保存する
# Retrieve notebook definition as .ipynb content
notebook_content = notebookutils.notebook.getDefinition("MyNotebook")
# Save to a file for backup
with open("/path/to/backup/MyNotebook.ipynb", "w") as f:
f.write(notebook_content)
print("Notebook definition retrieved and saved")
別のワークスペースからノートブック定義を取得する
workspace_id = "cccccccc-3333-4444-5555-dddddddddddd"
notebook_content = notebookutils.notebook.getDefinition(
name="SharedNotebook",
workspaceId=workspace_id,
format="ipynb"
)
print(f"Retrieved definition from workspace {workspace_id}")
値を返す
getDefinition() メソッドは、ノートブックの内容を含む文字列.ipynb JSON 形式で返します。
バックアップ用のすべてのノートブックをエクスポートする
import os
from datetime import datetime
def export_all_notebooks(backup_dir="/path/to/backups"):
"""Export all notebooks in the workspace for backup."""
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
export_dir = f"{backup_dir}/backup_{timestamp}"
os.makedirs(export_dir, exist_ok=True)
notebooks = notebookutils.notebook.list()
print(f"Exporting {len(notebooks)} notebooks to {export_dir}")
exported_count = 0
for nb in notebooks:
try:
content = notebookutils.notebook.getDefinition(nb.displayName)
filename = f"{export_dir}/{nb.displayName}.ipynb"
with open(filename, "w") as f:
f.write(content)
exported_count += 1
print(f"Exported: {nb.displayName}")
except Exception as e:
print(f"Failed to export {nb.displayName}: {e}")
print(f"\nExported {exported_count} of {len(notebooks)} notebooks")
return export_dir
backup_location = export_all_notebooks()
ノートブックを更新する
notebookutils.notebook.update()を使用して、ノートブックのメタデータ (表示名や説明など) を変更します。 ノートブックのコンテンツや lakehouse の構成は変更されません。
パラメーター
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
name |
糸 | はい | ノートブックの現在の名前または ID。 |
newName |
糸 | はい | ノートブックの新しい表示名。 |
description |
糸 | いいえ | 更新された説明。 |
workspaceId |
糸 | いいえ | ワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
ノートブックの名前を変更する
updated_notebook = notebookutils.notebook.update(
name="OldNotebookName",
newName="NewNotebookName",
description="Updated description with more details"
)
print(f"Updated notebook: {updated_notebook.displayName}")
値を返す
update() メソッドは、更新されたプロパティを持つArtifact オブジェクトを返します。
ノートブック定義を更新する
notebookutils.notebook.updateDefinition()を使用して、ノートブックのコンテンツ、既定のレイクハウス、またはその両方を変更します。 メタデータではなくノートブック定義を変更する必要がある場合に使用します。
パラメーター
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
name |
糸 | はい | 更新するノートブックの名前または ID。 |
content |
糸 | いいえ |
.ipynb形式の新しいノートブック コンテンツ。 |
defaultLakehouse |
糸 | いいえ | 新しい既定のレイクハウス名。 |
defaultLakehouseWorkspace |
糸 | いいえ | 新しい既定のレイクハウスのワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
workspaceId |
糸 | いいえ | ワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
environmentId |
糸 | いいえ | ノートブックに接続する環境 ID。 |
environmentWorkspaceId |
糸 | いいえ | 環境のワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
注
environmentIdパラメーターとenvironmentWorkspaceId パラメーターは、Spark ノートブック ランタイムでのみ使用できます。 Python ノートブックでは、これらのパラメーターはサポートされていません。
ノートブックのコンテンツを更新する
# Load new content
with open("/path/to/updated_notebook.ipynb", "r") as f:
new_content = f.read()
is_updated = notebookutils.notebook.updateDefinition(
name="MyNotebook",
content=new_content
)
print(f"Notebook definition updated: {is_updated}")
既定のレイクハウスを変更する
is_updated = notebookutils.notebook.updateDefinition(
name="MyNotebook",
defaultLakehouse="NewLakehouse",
defaultLakehouseWorkspace="" # Current workspace
)
print(f"Default lakehouse updated: {is_updated}")
コンテンツと lakehouse の両方を更新する
with open("/path/to/new_version.ipynb", "r") as f:
new_content = f.read()
is_updated = notebookutils.notebook.updateDefinition(
name="MyNotebook",
content=new_content,
defaultLakehouse="ProductionLakehouse",
defaultLakehouseWorkspace=""
)
print(f"Notebook fully updated: {is_updated}")
値を返す
updateDefinition() メソッドは、更新が成功した場合はTrueを返し、失敗した場合はFalseします。
ヒント
メタデータの変更 (名前、説明) に update() を使用し、コンテンツと lakehouse の変更に updateDefinition() します。 メタデータとコンテンツの両方を完全に更新する必要がある場合は、両方のメソッドを順番に呼び出します。
ノートブックを削除する
notebookutils.notebook.delete()を使用して、ワークスペースからノートブックを完全に削除します。 削除が成功した場合は True を返し、それ以外の場合は Falseを返します。
パラメーター
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
name |
糸 | はい | 削除するノートブックの名前または ID。 |
workspaceId |
糸 | いいえ | ワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
Important
削除は永続的です。 削除されたノートブックは回復できません。 削除する前に必ずノートブック名を確認し、最初に getDefinition() を使用してノートブック定義をバックアップすることを検討してください。
値を返す
delete() メソッドは、削除が成功した場合はTrueを返し、失敗した場合はFalseします。
ノートブックを削除する
is_deleted = notebookutils.notebook.delete("ObsoleteNotebook")
if is_deleted:
print("Notebook deleted successfully")
else:
print("Failed to delete notebook")
パターンによってノートブックを安全にクリーンアップする
def cleanup_notebooks(name_pattern, dry_run=True):
"""Delete notebooks matching a name pattern."""
notebooks = notebookutils.notebook.list()
to_delete = [nb for nb in notebooks if name_pattern in nb.displayName]
print(f"Found {len(to_delete)} notebooks matching '{name_pattern}':")
for nb in to_delete:
print(f" - {nb.displayName}")
if dry_run:
print("\nDRY RUN - No notebooks deleted")
return
deleted_count = 0
for nb in to_delete:
if notebookutils.notebook.delete(nb.displayName):
deleted_count += 1
print(f"Deleted: {nb.displayName}")
else:
print(f"Failed to delete: {nb.displayName}")
print(f"\nDeleted {deleted_count} of {len(to_delete)} notebooks")
# Always run with dry_run=True first to preview
cleanup_notebooks("temp_", dry_run=True)
ヒント
安全な一括削除を行うには、最初に dry_run=True を使用して実行し、どのノートブックが削除されるのかをプレビューします。 必要に応じて回復できるように、直ちに削除するのではなく、 _TO_DELETE プレフィックスを持つノートブックの名前を変更することを検討してください。
ノートブックを一覧表示する
notebookutils.notebook.list()を使用して、ワークスペース内のノートブックを列挙します。
Artifactオブジェクトの配列を返します。
パラメーター
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
workspaceId |
糸 | いいえ | ワークスペース ID。 現在のワークスペースの場合は空のままにします。 |
maxResults |
int（整数） | いいえ | 返される結果の最大数。 デフォルト値は1000です。 |
現在のワークスペース内のすべてのノートブックを一覧表示する
notebooks = notebookutils.notebook.list()
print(f"Found {len(notebooks)} notebooks:")
for nb in notebooks:
print(f" - {nb.displayName} (ID: {nb.id})")
別のワークスペースのノートブックを一覧表示する
workspace_id = "cccccccc-3333-4444-5555-dddddddddddd"
notebooks = notebookutils.notebook.list(workspaceId=workspace_id)
print(f"Found {len(notebooks)} notebooks in workspace {workspace_id}")
値を返す
list() メソッドは、Artifact オブジェクトの配列を返します。 各オブジェクトには、 displayName、 id、および description プロパティが含まれています。
名前パターンでノートブックをフィルター処理する
all_notebooks = notebookutils.notebook.list()
# Filter for notebooks that start with a specific prefix
processing_notebooks = [nb for nb in all_notebooks if nb.displayName.startswith("Process_")]
print(f"Found {len(processing_notebooks)} processing notebooks:")
for nb in processing_notebooks:
print(f" - {nb.displayName}")
ノートブックを複製する
list()とgetDefinition()を一緒に使用して、同じワークスペース内または別のワークスペースにノートブックを複製します。
def clone_notebook(source_name, target_name, target_workspace=""):
"""Clone a notebook by retrieving its content and creating a copy."""
source = notebookutils.notebook.get(source_name)
content = notebookutils.notebook.getDefinition(source_name)
cloned = notebookutils.notebook.create(
name=target_name,
description=f"Clone of {source_name}",
content=content,
workspaceId=target_workspace
)
print(f"Cloned {source_name} to {cloned.displayName}")
return cloned
cloned_notebook = clone_notebook("TemplateNotebook", "NewInstance")
ノートブックを別のワークスペースに移行する
def migrate_notebook(name, target_workspace_id, new_name=None):
"""Migrate a notebook from the current workspace to another workspace."""
content = notebookutils.notebook.getDefinition(name)
target_name = new_name if new_name else name
migrated = notebookutils.notebook.create(
name=target_name,
description=f"Migrated from {name}",
content=content,
workspaceId=target_workspace_id
)
print(f"Migrated {name} to workspace {target_workspace_id} as {target_name}")
return migrated
target_ws = "dddddddd-4444-5555-6666-eeeeeeeeeeee"
migrated_nb = migrate_notebook("DataPipeline", target_ws, "DataPipeline_v2")