Del via

Oversikt over programmeringsmodell for Fabric User-datafunksjoner (forhåndsversjon)

Programmeringsmodellen for Fabric User-datafunksjoner er en SDK som gir den nødvendige funksjonaliteten til å redigere og publisere kjørbare funksjoner i Fabric. SDK lar deg også sømløst integrere med andre elementer i Fabric-økosystemet, for eksempel Fabric-datakilder. Dette biblioteket er offentlig tilgjengelig i PyPI- og er forhåndsinstallert i elementene for brukerdatafunksjoner.

SDK for brukerdatafunksjoner

Et element for brukerdatafunksjoner inneholder én eller mange funksjoner du kan aktivere fra Stoff-portalen, fra et annet stoffelement eller fra et eksternt program ved hjelp av det angitte REST-endepunktet. Hver funksjon er en metode i Python-skriptet som gjør det mulig å sende parametere og returnere utdata til aktiveringsprogrammet. Programmeringsmodellen for brukerdatafunksjoner inneholder følgende komponenter:

  • Biblioteket fabric.functions inneholder koden du trenger for å opprette brukerdatafunksjoner i Python. Du kan se at dette biblioteket importeres i den første funksjonsmalen når du oppretter et nytt element for brukerdatafunksjoner.

  • Metoden fn.UserDataFunctions() gir utførelseskonteksten. Den legges til i begynnelsen av kodefilen i alle nye elementer for brukerdatafunksjoner, før noen funksjonsdefinisjoner.

    Eksempel:

    import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

  • Hver funksjon identifiseres med en @udf.function() dekoratør. Denne dekoratøren definerer om funksjonen kan aktiveres individuelt fra portalen eller en ekstern aktivering.

    eksempel på aktiverbar funksjon

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

  • Alle Python-metoder uten @udf.function()-dekoratøren kan ikke aktiveres direkte. De kan bare aktiveres fra funksjoner som inneholder dekoratøren, og kan brukes som hjelpefunksjoner.

    eksempel på hjelpefunksjon

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

Støttede inndatatyper

Du kan definere inndataparametere for funksjonen, for eksempel primitive datatyper som str, int, float osv. Datatypene for inndata som støttes, er:

JSON-type Python-datatype
Streng Str
Datetime-streng datetime
Boolsk Bool
tall int, flyt
Matrise list[], eksempelliste[int]
objekt Diktering

Utdatatyper som støttes

Datatypene for utdata som støttes, er:

Python-datatype
Str
datetime
Bool
int, flyt
list[datatype], for eksempel liste[int]
Diktering
Ingen

Datatilkoblinger til Fabric-datakilder

Med denne modulen kan du referere til datatilkoblinger uten behov for å skrive tilkoblingsstrenger i koden. Biblioteket fabric.functions inneholder to måter å håndtere datatilkoblinger på:

  • fabric.functions.FabricSqlConnection: Lar deg arbeide med SQL-databaser i Fabric, inkludert SQL Analytics-endepunkter og Fabric-lagre.
  • fabric.functions.FabricLakehouseClient: Lar deg jobbe med Lakehouses, med en måte å koble til både Lakehouse-bord og Lakehouse-filer.

Hvis du vil referere til en tilkobling til en datakilde, må du bruke @udf.connection-dekoratøren. Du kan bruke den i et av 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>")

Argumentene for @udf.connection er:

  • argNamevil navnet på variabelen som tilkoblingen skal bruke i funksjonen.
  • alias, aliaset for tilkoblingen du la til med Behandle tilkoblinger-menyen.
  • Hvis argName og alias har samme verdi, kan du bruke @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 aktiveringsegenskaper ved hjelp av UserDataFunctionContext

Programmeringsmodellen inkluderer også objektet UserDataFunctionContext. Dette objektet inneholder funksjonsmetadata og kan brukes til å opprette spesifikk applogikk for bestemte aktiveringsmekanismer.

Tabellen nedenfor viser egenskapene for objektet UserDataFunctionContext:

Egenskapsnavn Datatype Beskrivelse
Aktiverings-ID streng Den unike GUID-en som er knyttet til aktiveringen av elementet for brukerdatafunksjoner.
ExecutingUser objekt Metadata for brukerens informasjon som brukes til å godkjenne aktiveringen.

Objektet ExecutingUser inneholder følgende informasjon:

Egenskapsnavn Datatype Beskrivelse
Oid streng (GUID) Brukerens objekt-ID, som er en uforanderlig identifikator for anmoderen. Dette er den bekreftede identiteten til brukeren eller tjenestekontohaveren som brukes til å aktivere denne funksjonen på tvers av programmer.
TenantId streng (GUID) ID-en til leieren som brukeren er logget på.
PreferredUsername streng Foretrukket brukernavn for den påkallende brukeren, som angitt av brukeren. Denne verdien kan dempes.

Hvis du vil ha tilgang til UserDataFunctionContext-parameteren, må du bruke følgende dekoratør øverst i funksjonsdefinisjonen: @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åndtert feil med UserThrownError

Når du utvikler funksjonen, kan du sende et forventet feilsvar ved hjelp av UserThrownError metoden som er tilgjengelig i Python-programmeringsmodellen. Én bruk av denne metoden er å administrere tilfeller der inndataene fra brukeren ikke klarer å sende 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 metoden tar to parametere:

  • Message: Denne strengen returneres som feilmeldingen til programmet som aktiverer denne funksjonen.
  • En ordliste med egenskaper som returneres til programmet som aktiverer denne funksjonen.

Neste trinn