Megosztás a következőn keresztül:

Fabric User data functions programozási modell áttekintése (előzetes verzió)

A Fabric User adatfüggvény-programozási modell egy SDK, amely biztosítja a futtatható függvények létrehozásához és közzétételéhez szükséges funkciókat a Fabricben. Az SDK-val zökkenőmentesen integrálható a Fabric-ökoszisztéma más elemeivel, például a Fabric-adatforrásokkal. Ez a kódtár nyilvánosan elérhető a PyPI, és előre telepítve van a felhasználói adatfüggvények elemeiben.

Felhasználói adatkezelő SDK

A felhasználói adatfüggvények egy vagy több függvényt tartalmaznak, amelyeket meghívhat a Háló portálról, egy másik Hálóelemből vagy egy külső alkalmazásból a megadott REST-végpont használatával. Minden függvény egy metódus a Python-szkriptben, amely lehetővé teszi a paraméterek átadását és a kimenet visszaadását a meghívónak. A Felhasználói adatfüggvények programozási modellje a következő összetevőket tartalmazza:

  • A fabric.functions kódtár tartalmazza a felhasználói adatfüggvények Pythonban való létrehozásához szükséges kódot. Új felhasználói adatfüggvény-elem létrehozásakor láthatja, hogy ez a kódtár az első függvénysablonban lesz importálva.

  • A fn.UserDataFunctions() metódus biztosítja a végrehajtási környezetet. A kódfájl elején, minden új felhasználói adatfüggvény-elemben hozzáadjuk, a függvénydefiníciók előtt.

    példa:

    import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

  • Minden függvényt egy @udf.function() decoratorral azonosítanak. Ez a dekorátor meghatározza, hogy a függvényt külön-külön lehet-e meghívni a portálról vagy egy külső meghívó által.

    Hívható függvény példa

    # This is a hello fabric function sample that can be invoked from the Fabric portal, another Fabric item, or an external application.

@udf.function()
def hello_fabric(name: str) -> str:
    logging.info('Python UDF trigger function processed a request.')
    logging.info('Executing hello fabric function.')

    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

  • A @udf.function() dekoratőr nélküli Python-metódusok közvetlenül nem hívhatók meg. Ezek csak a dekoratőrt tartalmazó függvényekből hívhatók meg, és segédfüggvényekként is használhatók.

    Segítő függvény példa

    # This is a helper function that can be invoked from other functions, but can't be invoked or run directly because it doesn't have the @udf.function() decorator

def uppercase_name(name: str) -> str:
    return name.upper()

Támogatott bemeneti típusok

Megadhat bemeneti paramétereket a függvényhez, például primitív adattípusokat, például str, int, float stb. A támogatott bemeneti adattípusok a következők:

JSON-típus Python-adattípus
Karakterlánc str
Időpont-szöveg dátum/idő
Boolean bool
Számok int, float
Tömb list[], példalista[int]
objektum szótár

Támogatott kimeneti típusok

A támogatott kimeneti adattípusok a következők:

Python-adattípus
str
dátum/idő
bool
int, float
list[adat-típus], például list[egész szám]
szótár
Egyik sem

Adatkapcsolatok Fabric-adatforrásokkal

Ez a modul lehetővé teszi, hogy a adatkapcsolatokra hivatkozzon anélkül, hogy kapcsolati sztringeket kellene írnia a kódban. A fabric.functions kódtár két módon kezeli az adatkapcsolatokat:

  • fabric.functions.FabricSqlConnection: Lehetővé teszi az SQL-adatbázisok használatát a Fabricben, beleértve az SQL Analytics-végpontokat és a Fabric-raktárakat.
  • fabric.functions.FabricLakehouseClient: Lehetővé teszi a Lakehouse-okkal való munkát, és lehetővé teszi a Lakehouse-táblákhoz és a Lakehouse-fájlokhoz való csatlakozást.

Az adatforráshoz való kapcsolódáshoz a @udf.connection dekorátort kell használnia. A következő formátumok bármelyikében alkalmazhatja:

  • @udf.connection(alias="<alias for data connection>", argName="sqlDB")
  • @udf.connection("<alias for data connection>", "<argName>")
  • @udf.connection("<alias for data connection>")

A @udf.connection argumentumai a következők:

  • argName, annak a változónak a neve, amelyet a kapcsolat használni fog a függvényben.
  • aliasa Kapcsolatok kezelése menüben hozzáadott kapcsolat aliasa.
  • Ha argName és alias ugyanaz az érték, használhatja a @udf.connection("<alias and argName for the data connection>").

Példa

# Where demosqldatabase is the argument name and the alias for my data connection used for this function
@udf.connection("demosqldatabase")
@udf.function()
def read_from_sql_db(demosqldatabase: fn.FabricSqlConnection)-> list:
  # Replace with the query you want to run
  query = "SELECT * FROM (VALUES ('John Smith', 31), ('Kayla Jones', 33)) AS Employee(EmpName, DepID);"

  # [...] Here is where the rest of your SqlConnection code would be.

  return results

A meghívási tulajdonságok lekérése UserDataFunctionContext

A programozási modell tartalmazza a UserDataFunctionContext objektumot is. Ez az objektum tartalmazza a függvényhívás metaadatait, és adott alkalmazáslogika létrehozásához használható bizonyos meghívási mechanizmusokhoz.

Az alábbi táblázat a UserDataFunctionContext objektum tulajdonságait mutatja be:

Tulajdonság neve Adattípus Leírás
Meghívás azonosítója szál A felhasználói adatfüggvényelem meghívásához kapcsolódó egyedi GUID.
VégrehajtóFelhasználó tárgy A meghívás engedélyezéséhez használt felhasználói adatok metaadatai.

A ExecutingUser objektum a következő információkat tartalmazza:

Tulajdonság neve Adattípus Leírás
Oid karakterlánc (GUID) A felhasználó objektumazonosítója, amely a kérelmező nem módosítható azonosítója. Ez annak a felhasználónak vagy szolgáltatásnévnek az igazolt identitása, amelyet a függvény alkalmazások közötti meghívásához használnak.
BérlőAzonosító karakterlánc (GUID) Annak a bérlőnek az azonosítója, amelybe a felhasználó bejelentkezett.
PreferáltFelhasználónév szál Az invokáló felhasználó előnyben részesített felhasználóneve, a felhasználó által megadott módon. Ez az érték nem módosítható.

A UserDataFunctionContext paraméter eléréséhez a függvénydefiníció tetején található alábbi dekorátort kell használnia: @udf.context(argName="<parameter name>")

példa

@udf.context(argName="myContext")
@udf.function()
def getContext(myContext: fabric.functions.UserDataFunctionContext)-> str:
    logging.info('Python UDF trigger function processed a request.')
    return f"Hello oid = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

Dobjon egy kezelt hibát a UserThrownError használatával

A függvény fejlesztésekor a Python programozási modellben elérhető UserThrownError metódussal várható hibaválaszt adhat meg. Ennek a módszernek az egyik módja az olyan esetek kezelése, amikor a felhasználó által megadott bemenetek nem adták át az üzleti érvényesítési szabályokat.

példa

import datetime

@udf.function()
def raise_userthrownerror(age: int)-> str:
    if age < 18:
        raise fn.UserThrownError("You must be 18 years or older to use this service.", {"age": age})

    return f"Welcome to Fabric Functions at {datetime.datetime.now()}!"

Ez a UserThrownError metódus két paramétert használ:

  • Message: Ez a sztring hibaüzenetként jelenik meg a függvényt használó alkalmazásnak.
  • A függvényt megszólító alkalmazásnak visszaadott tulajdonságok szótára.

Következő lépések