Zdieľať cez

Prehľad modelu programovania dátových funkcií používateľa služby Fabric (Preview)

Model programovania dátových funkcií používateľa služby Fabric je súprava SDK, ktorá poskytuje potrebné funkcie na vytváranie a publikovanie runnable funkcií v službe Fabric. Súprava SDK vám tiež umožňuje bezproblémovú integráciu s inými položkami v ekosystéme služby Fabric, ako sú napríklad zdroje údajov služby Fabric. Táto knižnica je verejne dostupná v PyPI a je predinštalovaná v položkách údajových funkcií používateľa.

Súprava SDK funkcií údajov používateľov

Položka údajových funkcií používateľa obsahuje jednu alebo viacero funkcií, ktoré môžete vyvolať z portálu služby Fabric, z inej položky služby Fabric alebo z externej aplikácie pomocou uvedeného koncového bodu REST. Každá funkcia je metóda v skripte jazyka Python, ktorá umožňuje odovzdávanie parametrov a vrátenie výstupu do vyvolávača. Programovací model dátových funkcií používateľa obsahuje nasledujúce súčasti:

  • Knižnica fabric.functions poskytuje kód, ktorý potrebujete na vytvorenie používateľských údajových funkcií v jazyku Python. Keď vytvoríte novú položku údajových funkcií používateľa, táto knižnica sa importuje do vašej prvej šablóny funkcie.

  • Metóda fn.UserDataFunctions() poskytne kontext spustenia. Pridá sa na začiatok súboru s kódom vo všetkých nových položkách údajových funkcií používateľa pred definíciami funkcií.

    Príklad:

    import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

  • Každá funkcia je identifikovaná pomocou dekorátora @udf.function(). Tento dekorátor definuje, či je možné funkciu vyvolať individuálne z portálu alebo externého vyvolávača.

    príklad invokable funkcie

    # 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()}!"

  • Akékoľvek metódy jazyka Python bez dekorátora @udf.function() nie je možné priamo vyvolať. Môžu sa vyvolať iba z funkcií, ktoré obsahujú dekorátor, a môžu sa použiť ako pomocné funkcie.

    príklad funkcie helper 

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

Podporované typy vstupov

Môžete definovať vstupné parametre pre funkciu, ako sú napríklad primitívne typy údajov, ako napríklad str, int, float atď. Podporované typy vstupných údajov sú:

typu JSON typ údajov jazyka Python
Povrázok Str
reťazca datetime datetime (dátumu a času)
Boolean Bool
Numbers int, float
Pole list[], example list[int]
objektu Dict

Podporované typy výstupu

Podporované typy údajov výstupu sú:

typ údajov jazyka Python
Str
datetime (dátumu a času)
Bool
int, float
list[data-type], napríklad list[int]
Dict
žiadne

Údajové pripojenia k zdrojom údajov služby Fabric

Tento modul vám umožňuje odkazovať na údajové pripojenia bez nutnosti zapisovania reťazcov pripojenia do kódu. Knižnica fabric.functions poskytuje dva spôsoby na spracovanie údajových pripojení:

  • fabric.functions.FabricSqlConnection: Umožňuje pracovať s databázami SQL v službe Fabric vrátane koncových bodov služby SQL Analytics a skladov služby Fabric.
  • fabric.functions.FabricLakehouseClient: Umožňuje vám pracovať s lakehouses, so spôsobom, ako sa pripojiť k obom lakehouse tabuliek a Lakehouse súbory.

Ak chcete odkazovať na pripojenie k zdroju údajov, musíte použiť dekorátor @udf.connection. Môžete ju použiť v ktoromkoľvek z nasledujúcich formátov:

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

Argumenty pre @udf.connection sú:

  • argName, názov premennej, ktorý pripojenie použije vo vašej funkcii.
  • alias, alias pripojenia, ktoré ste pridali, pomocou ponuky Spravovať pripojenia.
  • Ak argName a alias majú rovnakú hodnotu, môžete použiť @udf.connection("<alias and argName for the data connection>").

Príklad

# 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

Získanie vlastností vyvolania pomocou UserDataFunctionContext

Programovací model obsahuje aj objekt UserDataFunctionContext. Tento objekt obsahuje metaúdaje vyvolania funkcie a možno ho použiť na vytvorenie špecifickej logiky aplikácie pre určité mechanizmy vyvolania.

Nasledujúca tabuľka zobrazuje vlastnosti pre UserDataFunctionContext objekt:

Názov vlastnosti Typ údajov Popis
ID vyvolania povrázok Jedinečný identifikátor GUID zviazaný s vyvolanie položky údajových funkcií používateľa.
ExecutingUser (VykonávajúciPouýšer) namietať Metaúdaje informácií o používateľovi použité na overenie vyvolania.

Objekt ExecutingUser obsahuje nasledujúce informácie:

Názov vlastnosti Typ údajov Popis
Oid Reťazec (GUID) ID objektu používateľa, ktoré je nemenným identifikátorom žiadateľa. Ide o overenú identitu používateľa alebo objektu služby, ktorá sa použila na vyvolanie tejto funkcie v rámci aplikácií.
ID nájomníka Reťazec (GUID) ID nájomníka, do ktorému je používateľ prihlásený.
PreferredUsername povrázok Preferované meno používateľa na vyvolanie, ako je nastavené používateľom. Táto hodnota je mutable.

Ak chcete získať prístup k parametru UserDataFunctionContext, musíte použiť nasledujúci dekorátor v hornej časti definície funkcie: @udf.context(argName="<parameter name>")

Príklad

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

Hodiť spracovanú chybu s UserThrownError

Pri vývoji funkcie môžete hodiť očakávanú chybovú odpoveď pomocou metódy UserThrownError, ktorá je k dispozícii v programovacom modeli jazyka Python. Jednou z použitia tejto metódy je spravovanie prípadov, keď vstupy poskytnuté používateľom neprejdú pravidlami podnikovej overenia.

Príklad

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

Táto UserThrownError metóda má dva parametre:

  • Message: Tento reťazec sa vráti ako chybové hlásenie pre aplikáciu, ktorá vyvoláva túto funkciu.
  • Slovník vlastností, ktoré sa vrátia do aplikácie, ktorá vyvoláva túto funkciu.

Ďalšie kroky