変数ライブラリは、ノートブック コードでの値のハードコーディングを回避するのに役立ちます。 コードを編集する代わりに、ライブラリ内の値を更新し、実行時に取得します。 このパターンは、構成を一元化することで、チームやプロジェクト間でノートブックを再利用するのに役立ちます。
次の表に、使用可能な変数ライブラリ メソッドの一覧を示します。
| メソッド | 署名 | 説明 |
|---|---|---|
getLibrary |
getLibrary(variableLibraryName: String): VariableLibrary |
変数ライブラリ オブジェクトを取得します。
library.variableNameなど、返されたオブジェクトのプロパティとして変数にアクセスします。 動的アクセスには、 getVariable('name') 構文または角かっこ構文 library['name'] を使用できます。 |
get |
get(variableReference: String): Any |
$(/**/libraryName/variableName)形式の参照パスによって 1 つの変数値を取得します。
/**/ プレフィックスが必要です。 値は変数定義に基づいて自動的に型指定されます。 |
変数の定義
notebookutils.variableLibraryを使用する前に、変数ライブラリで変数を定義します。 Fabric UI を使用して変数ライブラリを作成および管理できます。
変数ライブラリを取得する
getLibrary()を使用してライブラリ全体をオブジェクトとして取得し、変数にプロパティとしてアクセスします。 動的アクセスが必要な場合は、 getVariable('name') 構文または角かっこ構文 library['name'] を使用します。
samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")
# Property access
samplevl.test_int
samplevl.test_str
# Method access (useful for dynamic variable names)
samplevl.getVariable("test_int")
# Bracket access
samplevl["test_int"]
次の例は、変数ライブラリ値を使用してファイル パスを動的に構築する方法を示しています。
samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")
file_path = f"abfss://{samplevl.Workspace_name}@onelake.dfs.fabric.microsoft.com/{samplevl.Lakehouse_name}.Lakehouse/Files/<FileName>.csv"
df = spark.read.format("csv").option("header","true").load(file_path)
display(df)
参照で 1 つの変数にアクセスする
1 つの変数値を取得するには、 get() メソッドを参照パターン $(/**/libraryName/variableName) と共に使用します。 値は変数定義に基づいて自動的に型指定されます。
Important
参照パターンでは、 /**/ プレフィックスが必要です。 完全なパターンは $(/**/libraryName/variableName)する必要があります。ここで、 libraryName は正確な変数ライブラリ項目名、 variableName はそのライブラリで定義された変数です。 名前は大文字と小文字が区別されます。
notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")
サポートされている変数型
変数ライブラリでは、次のデータ型がサポートされています。 値は取得時に自動的に型指定されます。ほとんどの場合、明示的にキャストする必要はありません。
| タイプ | 説明 | 例 |
|---|---|---|
| ストリング | テキスト値。 | "my_connection_string" |
| 整数 | 整数。 | 42 |
| ブーリアン | ブール値 真/偽。 | true |
| 数値 | 10 進数。 | 3.14 |
| DateTime | ISO 8601 形式の日付と時刻の値。 | "2025-01-15T08:30:00Z" |
| Guid | グローバルに一意の識別子。 | "123e4567-e89b-12d3-a456-426614174000" |
| 項目参照 | サポートされている Fabric 項目への参照。 | "workspace/item" |
環境固有の構成
変数ライブラリでは 値セットがサポートされています。このセットを使用すると、開発、テスト、prod など、同じ変数の値の代替セットを定義できます。各ワークスペースには一度に 1 つのアクティブな値が設定されており、デプロイ パイプラインはステージごとに適切な値セットを自動的にアクティブ化できます。
環境間でノートブックを移行する際にコードを変更する必要がなくなるこのパターンです。
# These values change based on the active value set (dev/test/prod)
app_config = notebookutils.variableLibrary.getLibrary("app_config")
api_endpoint = app_config.api_endpoint
batch_size = app_config.batch_size
debug_mode = app_config.debug_enabled
print(f"API Endpoint: {api_endpoint}")
print(f"Batch Size: {batch_size}")
print(f"Debug Mode: {debug_mode}")
if debug_mode:
print("Running in debug mode")
考慮事項
以下の考慮事項に留意してください。
-
notebookutils.variableLibraryAPI では、同じワークスペース内の変数ライブラリへのアクセスのみがサポートされます。 ワークスペース間アクセスはサポートされていません。 - 参照の実行中に、子ノートブック内のワークスペース間で変数ライブラリを取得することはできません。
- ノートブック コードは、変数ライブラリのアクティブな値セットで定義されている変数を参照します。 異なる値を使用するには、ワークスペースで異なる値セットをアクティブ化するか、デプロイ パイプラインを使用して環境ごとに値セットを管理します。
- サービス プリンシパル (SPN) は、変数ライブラリ ユーティリティでは現在サポートされていません。
- 変数ライブラリは、ノートブックから読み取り専用です。 Fabric UI または API を使用して変更を加えます。
- 各ライブラリでは、最大 1,000 個の変数と 1,000 個の値セットがサポートされ、最大 10,000 個のセルと 1 MB のサイズ制限があります。
- 変数名とライブラリ名では大文字と小文字が区別されます。 変数を参照する場合は、正確な名前の一致を使用します。
ヒント
デプロイ パイプラインを使用して、ステージ (開発、テスト、prod) ごとに適切な値セットを自動的にアクティブ化します。 これにより、ノートブックを環境間で移行する際に、値セットを手動で切り替えたり、コードを変更したりする必要がなくなります。