NotebookUtils Fabric için Kullanıcı Verileri İşlevleri (UDF) yardımcı programları

Modül, notebookutils.udf not defteri kodunu Kullanıcı Veri İşlevi (UDF) öğeleriyle tümleştirmeye yönelik yardımcı programlar sağlar. İşlevlere aynı çalışma alanı içindeki veya farklı çalışma alanlarındaki bir UDF öğesinden erişebilir ve sonra gerektiğinde bu işlevleri çağırabilirsiniz. UDF öğeleri kod yeniden kullanılabilirliğini, merkezi bakımı ve ekip işbirliğini destekler.

UDF yardımcı programlarını kullanarak:

  • İşlev alma – UDF öğelerindeki işlevlere ada göre erişin.
  • Çalışma alanları arası erişim – Diğer çalışma alanlarındaki UDF öğelerindeki işlevleri kullanın.
  • İşlev bulma – Kullanılabilir işlevleri ve bunların imzalarını inceleyin.
  • Esnek çağrı – Dile uygun parametrelerle çağrı işlevleri.

Uyarı

İşlevlerini almak için hedef çalışma alanında bir UDF öğesine okuma erişiminiz olmalıdır. UDF işlevlerindeki özel durumlar, çağıran not defterine yayılır.

Aşağıdaki tabloda kullanılabilir UDF yöntemleri listelenir:

Yöntem Signature Açıklama
getFunctions getFunctions(udf: String, workspaceId: String = ""): UDF Bir UDF öğesindeki tüm işlevleri yapıt kimliğine veya adına göre alır. Çağrılabilen işlev özniteliklerine sahip bir nesne döndürür.

Döndürülen nesne aşağıdaki özellikleri kullanıma sunar:

Mülkiyet Türü Açıklama
functionDetails List İşlev meta veri sözlüklerinin listesi. Her sözlük şunları içerir: Name (işlev adı), Description (işlev açıklaması), Parameters (parametre tanımlarının listesi), FunctionReturnType (dönüş türü) ve DataSourceConnections (kullanılan veri kaynağı bağlantıları).
itemDetails Sözlük Anahtarlar içeren UDF öğe meta verilerinin sözlüğü: Id (yapıt kimliği), Name (öğe adı), WorkspaceId (çalışma alanı kimliği) ve CapacityId (kapasite kimliği).
<functionName> Callable UDF öğesindeki her işlev, döndürülen nesnede çağrılabilen bir yönteme dönüşür. myFunctions.functionName(...) ögesini çağırmak için kullanın.

Tavsiye

UDF işlevlerini bir kez alın ve sarmalayıcı nesnesini önbelleğe alın. Döngüde tekrar tekrar çağırmaktan getFunctions() kaçının; ek yükü en aza indirmek için bunun yerine sonucu önbelleğe alın.

UDF'den fonksiyonları al

UDF öğesinden tüm işlevleri almak için kullanın notebookutils.udf.getFunctions() . İsteğe bağlı olarak, çalışma alanları arası erişim için bir çalışma alanı kimliği belirtebilirsiniz.

# 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')

İşlevi çağırma

İşlevleri bir UDF öğesinden aldıktan sonra, onları adlarına göre çağırın. Python konumsal ve adlandırılmış parametreleri destekler. Scala ve R örneklerinde konumsal parametreler kullanılır.

# Positional parameters
myFunctions.functionName('value1', 'value2')

# Named parameters (recommended for clarity)
myFunctions.functionName(parameter1='value1', parameter2='value2')

Varsayılan parametre değerleri

Fabric kullanıcı verileri işlevleri varsayılan bağımsız değişken değerlerini destekler. aracılığıyla notebookutils.udf.getFunctionsalınan işlevleri çağırdığınızda, tanımlı varsayılanı olan herhangi bir parametre atlanabilir; çalışma zamanı varsayılanı otomatik olarak kullanır. Ayrıca, belirli varsayılanları geçersiz kılmak için adlandırılmış bağımsız değişkenler sağlayabilir ve diğerlerini varsayılan değerlerinde bırakabilirsiniz.

# 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')

Desteklenen varsayılan giriş türleri

Aşağıdaki türler varsayılan parametre değerleri olarak desteklenir:

Varsayılan tür Notes
Dize Herhangi bir JSON serileştirilebilir dize.
Tarih zaman dizgisi İşlev imzasında dize olarak belirtin. Çalışma zamanı, çağrı anında datetime olarak ayrıştırır. ISO 8601 gibi tutarlı bir biçim kullanın (örneğin, 2025-12-31T23:59:59Z).
Boolean True veya False.
Integer Herhangi bir tamsayı değeri.
Float Herhangi bir kayan nokta değeri.
List JSON ile uyumlu olmalıdır; imzada None kullanmayı tercih edin ve değiştirilebilir varsayılan sıkıntılardan kaçınmak için işlevin içinde atayın.
Sözlük JSON serileştirilebilir olmalıdır; imzada None öğesini tercih edin ve fonksiyonun içinde atayın.
pandas DataFrame (veri çerçevesi) JSON nesnesi olarak sağlanır ve SDK tarafından pandas türüne dönüştürülür. fabric-user-data-functions Sürüm 1.0.0 veya üzerini gerektirir.
pandas Serisi SDK'nın pandas türüne dönüştürdüğü nesnelerin JSON dizisi olarak sağlanır. fabric-user-data-functions Sürüm 1.0.0 veya üzerini gerektirir.

Sınırlamalar ve rehberlik

Varsayılanlar JSON serileştirilebilir olmalıdır (kümeler ve tanımlama grupları desteklenmez). Liste veya sözlük varsayılanları için imzada kullanın None ve paylaşılan değiştirilebilir varsayılanları önlemek için işlevin içinde gerçek varsayılanı atayın. Tarih saat varsayılanları için ISO 8601 biçimini (örneğin, 2025-12-31T23:59:59Z) kullanın. Pandas DataFrame veya Series'in varsayılan olarak kullanılması için sürüm 1.0.0 veya üzeri gerekir fabric-user-data-functions .

Ayrıntıları görüntüle

UDF öğe meta verilerini ve işlev imzalarını program aracılığıyla inceleyebilirsiniz.

UDF öğesi ayrıntılarını görüntüleme

display(myFunctions.itemDetails)

İşlev ayrıntılarını görüntüleme

display(myFunctions.functionDetails)

Tavsiye

Yeni bir UDF öğesiyle çalışırken her zaman functionDetails inceleyin. Bu, çağrıdan önce kullanılabilir işlevleri ve beklenen parametre türlerini doğrulamanıza yardımcı olur.

Hata yönetimi

Eksik işlevleri veya beklenmeyen parametre türlerini düzgün bir şekilde yönetmek için UDF çağrılarını dile uygun hata işlemeye sarmalayın. Bir işlevi çağırmadan önce her zaman UDF öğesinde var olduğunu doğrulayın.

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}")

Veri işlem hattında UDF işlevlerini kullanma

Yeniden kullanılabilir ETL adımları oluşturmak için UDF işlevleri oluşturabilirsiniz:

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")

Önemli

UDF çağrılarının ek yükü vardır. Aynı işlevi aynı parametrelerle tekrar tekrar çağırırsanız sonucu önbelleğe almayı göz önünde bulundurun. Mümkün olduğunda UDF işlevlerini sıkı döngülerde çağırmaktan kaçının.

İlgili içerik

  • Last updated on