notebookutils.udf モジュールには、ノートブック コードとユーザー データ関数 (UDF) 項目を統合するためのユーティリティが用意されています。 同じワークスペース内または異なるワークスペース間で UDF 項目から関数にアクセスし、必要に応じてそれらの関数を呼び出すことができます。 UDF 項目は、コードの再利用性、一元的なメンテナンス、チームコラボレーションを促進します。
UDF ユーティリティを使用して、次の手順を実行します。
- 関数の取得 – UDF 項目から名前で関数にアクセスします。
- ワークスペース間アクセス – 他のワークスペース の UDF 項目の関数を使用します。
- 関数の検出 – 使用可能な関数とそのシグネチャを検査します。
- 柔軟な呼び出し – 言語に適したパラメーターを使用して関数を呼び出します。
注
関数を取得するには、ターゲット ワークスペース内の UDF 項目への読み取りアクセス権が必要です。 UDF 関数からの例外は、呼び出し元のノートブックに反映されます。
次の表に、使用可能な UDF メソッドの一覧を示します。
| メソッド | 署名 | 説明 |
|---|---|---|
getFunctions |
getFunctions(udf: String, workspaceId: String = ""): UDF |
アーティファクト ID または名前を使用して、UDF 項目からすべての関数を取得します。 呼び出し可能な関数属性を持つオブジェクトを返します。 |
返されるオブジェクトは、次のプロパティを公開します。
| 財産 | タイプ | 説明 |
|---|---|---|
functionDetails |
一覧 | 関数メタデータ ディクショナリの一覧。 各ディクショナリには、 Name (関数名)、 Description (関数の説明)、 Parameters (パラメーター定義の一覧)、 FunctionReturnType (戻り値の型)、および DataSourceConnections (使用されるデータ ソース接続) が含まれます。 |
itemDetails |
辞書 | キー ( Id (アーティファクト ID)、 Name (項目名)、 WorkspaceId (ワークスペース ID)、および CapacityId (容量 ID) を含む UDF 項目メタデータのディクショナリ。 |
<functionName> |
Callable | UDF 項目内の各関数は、返されたオブジェクトの呼び出し可能なメソッドになります。
myFunctions.functionName(...)を使用して呼び出します。 |
ヒント
UDF 関数を 1 回取得し、ラッパー オブジェクトをキャッシュします。 ループ内で getFunctions() を繰り返し呼び出すのを避け、代わりに結果をキャッシュしてオーバーヘッドを最小限に抑えます。
UDF から関数を取得する
notebookutils.udf.getFunctions()を使用して、UDF 項目からすべての関数を取得します。 必要に応じて、ワークスペース間アクセスのワークスペース ID を指定できます。
# Get functions from a UDF item in the current workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName')
# Get functions from a UDF item in another workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')
関数を呼び出す
UDF 項目から関数を取得した後、名前で呼び出します。 Python では、位置指定パラメーターと名前付きパラメーターがサポートされています。 Scala と R の例では、位置パラメーターを使用します。
# Positional parameters
myFunctions.functionName('value1', 'value2')
# Named parameters (recommended for clarity)
myFunctions.functionName(parameter1='value1', parameter2='value2')
既定のパラメーター値
Fabricユーザー データ関数は、既定の引数値をサポートします。
notebookutils.udf.getFunctionsを使用して取得した関数を呼び出すと、既定のパラメーターが定義されているすべてのパラメーターを省略できます。ランタイムは既定値を自動的に使用します。 名前付き引数を指定して、特定の既定値をオーバーライドし、他の引数を既定値のままにすることもできます。
# Assume the UDF item defines a function like:
# def score_customer(customerId: str, startDate: datetime = "2025-01-01T00:00:00Z", isActive: bool = True, maxRecords: int = 100) -> dict
# The datetime defaults are specified as strings in the signature; the runtime parses them to datetime at invocation time.
# 1. Call without optional parameters — defaults are used for startDate, isActive, and maxRecords
result = myFunctions.scoreCustomer(customerId='C001')
# 2. Override one default via a named argument, keep the others at their defaults
result = myFunctions.scoreCustomer(customerId='C001', maxRecords=50)
# 3. Pass a date/time in ISO 8601 format for reliable parsing
result = myFunctions.scoreCustomer(customerId='C001', startDate='2025-12-31T23:59:59Z')
サポートされている既定の入力の種類
既定のパラメーター値として、次の型がサポートされています。
| 既定の型 | Notes |
|---|---|
| String | JSON でシリアル化可能な任意の文字列。 |
| Datetime 文字列 | 関数シグネチャで文字列として指定します。 ランタイムは、それを解析して、呼び出し時に datetime します。 ISO 8601 などの一貫性のある形式 (たとえば、 2025-12-31T23:59:59Z) を使用します。 |
| ブール値 |
True または False。 |
| Integer | 任意の整数値。 |
| Float | 任意の浮動小数点値。 |
| 一覧 | JSON シリアル化可能である必要があります。シグネチャの None を優先し、変更可能な既定の落とし穴を避けるために関数内で割り当てます。 |
| 辞書 | JSON シリアル化可能である必要があります。シグネチャ None を優先し、関数内で割り当てます。 |
| pandasデータフレーム | SDK が pandas 型に変換する JSON オブジェクトとして提供されます。 バージョン 1.0.0 以降 fabric-user-data-functions 必要です。 |
| pandas シリーズ | SDK が pandas 型に変換するオブジェクトの JSON 配列として提供されます。 バージョン 1.0.0 以降 fabric-user-data-functions 必要です。 |
制限事項とガイダンス
既定値は JSON シリアル化可能である必要があります (セットとタプルはサポートされていません)。 リストまたはディクショナリの既定値の場合は、シグネチャで None を使用し、関数内で実際の既定値を割り当てて、変更可能な共有の既定値を回避します。 datetime の既定値には ISO 8601 形式 ( 2025-12-31T23:59:59Z など) を使用します。 pandas DataFrame または Series を既定として使用するには、バージョン 1.0.0 以降 fabric-user-data-functions 必要があります。
詳細を表示する
UDF 項目のメタデータと関数シグネチャをプログラムで調べることができます。
UDF 項目の詳細を表示する
関数の詳細を表示する
ヒント
新しい UDF 項目を使用する場合は、常に functionDetails を検査します。 これは、呼び出し前に使用可能な関数とその予期されるパラメーター型を確認するのに役立ちます。
エラー処理
UDF 呼び出しを言語に適したエラー処理でラップして、不足している関数または予期しないパラメーター型を適切に管理します。 関数を呼び出す前に、必ず UDF 項目に関数が存在することを確認してください。
import json
try:
validators = notebookutils.udf.getFunctions('DataValidators')
# Check if function exists before calling
functions_info = json.loads(validators.functionDetails)
function_names = [f['Name'] for f in functions_info]
if 'validateSchema' in function_names:
is_valid = validators.validateSchema(
schema='sales_schema',
data_path='Files/data/sales.csv'
)
print(f"Schema validation: {'passed' if is_valid else 'failed'}")
else:
print("validateSchema function not available in this UDF item")
print(f"Available functions: {', '.join(function_names)}")
except AttributeError as e:
print(f"Function not found: {e}")
except TypeError as e:
print(f"Parameter type mismatch: {e}")
except Exception as e:
print(f"Error invoking UDF: {e}")
データ パイプラインで UDF 関数を使用する
UDF 関数を作成して、再利用可能な ETL ステップを作成できます。
etl_functions = notebookutils.udf.getFunctions('ETLUtilities')
df = spark.read.csv('Files/raw/sales.csv', header=True)
cleaned_df = etl_functions.removeOutliers(df, columns=['amount'])
enriched_df = etl_functions.addCalculatedColumns(cleaned_df)
validated_df = etl_functions.validateAndFilter(enriched_df)
validated_df.write.mode('overwrite').parquet('Files/processed/sales.parquet')
print("ETL pipeline completed using UDF functions")
Important
UDF 呼び出しにはオーバーヘッドがあります。 同じパラメーターで同じ関数を繰り返し呼び出す場合は、結果をキャッシュすることを検討してください。 可能な場合は、タイト ループで UDF 関数を呼び出さないようにします。