Del via

Oversigt over programmeringsmodel til fabric-brugerdatafunktioner (prøveversion)

Programmeringsmodellen for Fabric User-datafunktioner er et SDK, der giver den nødvendige funktionalitet til at oprette og publicere runnable funktioner i Fabric. SDK'et giver dig også mulighed for problemfrit at integrere med andre elementer i Fabric-økosystemet, f.eks. Fabric-datakilder. Dette bibliotek er offentligt tilgængeligt i PyPI- og er forudinstalleret i elementer i dine brugerdatafunktioner.

SDK til brugerdatafunktioner

Et element med brugerdatafunktioner indeholder en eller flere funktioner, som du kan aktivere fra Fabric-portalen, fra et andet Fabric-element eller fra et eksternt program ved hjælp af det angivne REST-slutpunkt. Hver funktion er en metode i Python-scriptet, der gør det muligt at overføre parametre og returnere et output til aktiveringsfunktionen. Programmeringsmodellen Brugerdatafunktioner indeholder følgende komponenter:

  • Biblioteket fabric.functions indeholder den kode, du skal bruge for at oprette brugerdatafunktioner i Python. Du kan se, at dette bibliotek importeres i din første funktionsskabelon, når du opretter et nyt element til brugerdatafunktioner.

  • Metoden fn.UserDataFunctions() leverer udførelseskonteksten. Den tilføjes i starten af kodefilen i alle nye elementer med brugerdatafunktioner før nogen funktionsdefinitioner.

    Eksempel:

    import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

  • Hver funktion identificeres med en @udf.function() dekoratør. Denne dekoratør definerer, om din funktion kan aktiveres individuelt fra portalen eller en ekstern invoker.

    eksempel på funktionen Invokable

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

  • Python-metoder uden @udf.function() dekoratøren kan ikke aktiveres direkte. De kan kun aktiveres fra funktioner, der indeholder dekoratøren, og kan bruges som hjælpefunktioner.

    eksempel på hjælpefunktion

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

Understøttede inputtyper

Du kan definere inputparametre for funktionen, f.eks. primitive datatyper som str, int, float osv. De understøttede inputdatatyper er:

JSON-type Python-datatype
Streng Str
datetime-streng dato/klokkeslæt
Boolesk Bool
tal int, float
Array list[], eksempelliste[int]
objekt Dict

Understøttede outputtyper

De understøttede outputdatatyper er:

Python-datatype
Str
dato/klokkeslæt
Bool
int, float
list[data-type], f.eks. list[int]
Dict
Ingen

Dataforbindelser til Fabric-datakilder

I dette modul kan du referere til dataforbindelser uden at skulle skrive forbindelsesstrenge i din kode. Biblioteket fabric.functions indeholder to måder at håndtere dataforbindelser på:

  • fabric.functions.FabricSqlConnection: Giver dig mulighed for at arbejde med SQL-databaser i Fabric, herunder SQL Analytics-slutpunkter og Fabric warehouses.
  • fabric.functions.FabricLakehouseClient: Giver dig mulighed for at arbejde med Lakehouses, så du kan oprette forbindelse til både Lakehouse-tabeller og Lakehouse-filer.

Hvis du vil referere til en forbindelse til en datakilde, skal du bruge @udf.connection dekoratør. Du kan anvende den i et af følgende formater:

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

Argumenterne for @udf.connection er:

  • argName, bruges navnet på den variabel, som forbindelsen bruger i din funktion.
  • alias, aliasset for den forbindelse, du har tilføjet med menuen Administrer forbindelser.
  • Hvis argName og alias har samme værdi, kan du bruge @udf.connection("<alias and argName for the data connection>").

Eksempel

# 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

Hent aktiveringsegenskaber ved hjælp af UserDataFunctionContext

Programmeringsmodellen indeholder også objektet UserDataFunctionContext. Dette objekt indeholder metadata for funktionsaktivering og kan bruges til at oprette specifik applogik for visse aktiveringsmekanismer.

I følgende tabel vises egenskaberne for det UserDataFunctionContext objekt:

Egenskabsnavn Datatype Beskrivelse
Aktiverings-id streng Det entydige GUID, der er knyttet til aktiveringen af elementet med brugerdatafunktioner.
Udfører bruger objekt Metadata for brugerens oplysninger, der bruges til at godkende aktiveringen.

Objektet ExecutingUser indeholder følgende oplysninger:

Egenskabsnavn Datatype Beskrivelse
Oid streng (GUID) Brugerens objekt-id, som er et uforanderligt id for anmoderen. Dette er den bekræftede identitet for den bruger eller tjenesteprincipal, der bruges til at aktivere denne funktion på tværs af programmer.
TenantId streng (GUID) Id'et for den lejer, som brugeren er logget på.
PreferredUsername streng Det foretrukne brugernavn for den bruger, der aktiverer, som angivet af brugeren. Denne værdi kan slås fra.

Hvis du vil have adgang til parameteren UserDataFunctionContext, skal du bruge følgende dekoratør øverst i funktionsdefinitionen: @udf.context(argName="<parameter name>")

Eksempel

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

Kast en håndteret fejl med UserThrownError

Når du udvikler din funktion, kan du udløse et forventet fejlsvar ved hjælp af den UserThrownError metode, der er tilgængelig i Python-programmeringsmodellen. En måde at bruge denne metode på er at administrere tilfælde, hvor brugerindgivne input ikke kan bestå forretningsvalideringsregler.

Eksempel

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

Denne UserThrownError metode tager to parametre:

  • Message: Denne streng returneres som fejlmeddelelsen til det program, der aktiverer denne funktion.
  • En ordbog med egenskaber, der returneres til det program, der aktiverer denne funktion.

Næste trin