Kangas Käyttäjätietojen toiminnot ohjelmointimallin yleiskatsaus

Fabric User -tietofunktioiden ohjelmointimalli on SDK, joka tarjoaa tarvittavat toiminnot suoritettavien funktioiden luomiseen ja julkaisemiseen Fabricissa. SDK:n avulla voit integroida saumattomasti myös muihin Fabric-ekosysteemin kohteisiin, kuten Fabric-tietolähteisiin. Tämä kirjasto on julkisesti käytettävissä PyPI ja se on esiasentettu käyttäjän tietofunktiokohteihin.

Käyttäjätietofunktiot SDK

Käyttäjän tietofunktiokohde sisältää yhden tai useita funktioita, jotka voit käynnistää Fabric-portaalista, toisesta Fabric-kohteesta tai ulkoisesta sovelluksesta käyttämällä annettua REST-päätepistettä. Kukin funktio on Python-komentosarjassasi oleva menetelmä, joka sallii parametrien välittämisen ja tuloksen palauttamisen käynnistäjälle. User-tietofunktioiden ohjelmointimalli sisältää seuraavat osat:

fabric.functions kirjasto sisältää koodin, jota tarvitset käyttäjätietofunktioiden luomiseen Pythonissa. Näet, että tämä kirjasto tuodaan ensimmäiseen funktiomalliin, kun luot uuden käyttäjätietofunktiokohteen.
-menetelmä fn.UserDataFunctions() tarjoaa suorituskontekstin, joka löytyi kooditiedoston alusta kaikista uusista käyttäjätietofunktiokohteista ennen mitään funktiomääritelmiä.

Esimerkki:
```
import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()
```
Kaikki funktiot tunnistetaan @udf.function() decoratorilla. Tämä decorator määrittää, voidaanko funktio käynnistää erikseen portaalista vai ulkoisesta käynnistimen kautta. Tämän dekoraattorin käyttäminen edellyttää myös, että funktiolla on palautusarvo. Tämän dekoraattorin toiminnot voivat käyttää dekoraattorin @udf.connection merkitsemiä yhteysobjekteja.

kutsuttavan funktion esimerkki
```
# 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()}!"
```
Mitään Python-menetelmiä, joilla ei ole @udf.function() decorator -elementtistä, ei voi käynnistää suoraan. Ne voidaan käynnistää vain funktioista, jotka sisältävät decoratorin, ja niitä voidaan käyttää apufunktioina.

Helper -funktion esimerkki
```
# 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()
```

Tuetut syötetyypit

Voit määrittää funktiolle syöteparametrit, kuten primitiivitietotyypit, kuten str, int, liukuluku jne. Tuetut syötetietotyypit ovat seuraavat:

JSON -tyypin	Python-tietotyyppi
Merkkijono	Str
Datetime-merkkijonon	päivämäärä/aika
Totuusarvo	Bool
Numbers -	int, kelluva
Valikoima	list[], esimerkkiluettelo[int]
Objekti	Dict
Objekti	pandas DataFrame
Objektien tai matriisi	pandas-sarja

Huomautus

Jos haluat käyttää pandas DataFrame- ja Series-tyyppejä, valitse User Data Function -portaalissa Kirjaston hallinta ja päivitä fabric-user-data-function versioksi 1.0.0.

Esimerkki tuettujen syötetyyppien pyynnön leipätekstistä:

{
  "name": "Alice",                          // String (str)
  "signup_date": "2025-07-08T13:44:40Z",    // Datetime string (datetime)
  "is_active": true,                        // Boolean (bool)
  "age": 30,                                // Number (int)
  "height": 5.6,                            // Number (float)
  "favorite_numbers": [3, 7, 42],           // Array (list[int])
  "profile": {                              // Object (dict)
    "email": "alice@example.com",
    "location": "Sammamish"
  },
  "sales_data": {                           // Object (pandas DataFrame)
    "2025-07-01": {"product": "A", "units": 10},
    "2025-07-02": {"product": "B", "units": 15}
  },
  "weekly_scores": [                        // Object or Array of Objects (pandas Series)
    {"week": 1, "score": 88},
    {"week": 2, "score": 92},
    {"week": 3, "score": 85}
  ]
}

Tuetut tulostetyypit

Tuetut tulostetietotyypit ovat seuraavat:

Python-tietotyyppi
Str
päivämäärä/aika
Bool
int, kelluva
list[data-type], esimerkiksi list[int]
Dict
Ei mitään
pandas-sarja
pandas DataFrame

Asynkronisen funktion kirjoittaminen

Lisää asynkroninen decorator funktiomäärityksen avulla koodissasi. Funktiolla async voit parantaa sovelluksesi reagointia ja tehokkuutta käsittelemällä useita tehtäviä kerralla. Ne ovat ihanteellisia suurten I/O-sidottujen toimintojen hallintaan. Tämä esimerkkifunktio lukee CSV-tiedoston lakehousesta pandas-funktion avulla. Funktio ottaa tiedoston nimen syöteparametriksi.

import pandas as pd 

# Replace the alias "<My Lakehouse alias>" with your connection alias.
@udf.connection(argName="myLakehouse", alias="<My Lakehouse alias>")
@udf.function()
async def read_csv_from_lakehouse(myLakehouse: fn.FabricLakehouseClient, csvFileName: str) -> str:

    # Connect to the Lakehouse
    connection = myLakehouse.connectToFilesAsync()   

    # Download the CSV file from the Lakehouse
    csvFile = connection.get_file_client(csvFileName)

    downloadFile = await csvFile.download_file()
    csvData = await downloadFile.readall()
    
    # Read the CSV data into a pandas DataFrame
    from io import StringIO
    df = pd.read_csv(StringIO(csvData.decode('utf-8')))

    # Display the DataFrame    
    result="" 
    for index, row in df.iterrows():
        result=result + "["+ (",".join([str(item) for item in row]))+"]"
    
    # Close the connection
    csvFile.close()
    connection.close()

    return f"CSV file read successfully.{result}"

Tietoyhteydet Fabric-tietolähteisiin

Tämän moduulin avulla voit viitata tietoyhteyksiin kirjoittamatta koodiin yhteysmerkkijonoja. fabric.functions kirjastossa on kaksi tapaa käsitellä tietoyhteyksiä:

fabric.functions.FabricSqlConnection: Mahdollistaa SQL-tietokantojen käytön Fabricissa, mukaan lukien SQL Analytics -päätepisteet ja Fabric-varastot.
fabric.functions.FabricLakehouseClient: Mahdollistaa Lakehousesin kanssa työskentelyn yhdessä sen kanssa, miten voit yhdistää sekä Lakehouse-taulukoihin että Lakehouse-tiedostoihin.

Jos haluat viitata yhteyteen tietolähteeseen, sinun on käytettävä @udf.connection decoratoria. Voit käyttää sitä missä tahansa seuraavista muodoista:

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

@udf.connection argumentit ovat seuraavat:

argName, sen muuttujan nimi, jota yhteys käyttää funktiossasi.
alias, yhteyden alias, jonka lisäsit Yhteyksien hallinta -valikossa.
Jos argName ja alias ovat samat, voit käyttää @udf.connection("<alias and argName for the data connection>").

Esimerkki:

# 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

Yleiset yhteydet Fabric-kohteille tai Azure-resursseille

Yleisten yhteyksien avulla voit luoda yhteyksiä Fabric-kohteisiin tai Azure-resursseihin käyttämällä User Data Functions -kohteen omistajan käyttäjätietoja. Tämä ominaisuus luo Microsoft Entra ID -tunnuksen, jossa on kohteen omistajan käyttäjätiedot ja annettu kohderyhmätyyppi. Tätä tunnusta käytetään todentamiseen Fabric-kohteiden tai Azure-resurssien kanssa, jotka tukevat kyseistä kohderyhmätyyppiä. Tämä prosessi antaa sinulle samanlaisen ohjelmointikokemuksen kuin hallittujen yhteyksien objektien käyttäminen Yhteyksien hallinta -ominaisuudesta , mutta vain yhteyden käyttäjäryhmätyypille.

Tämä ominaisuus käyttää sisustajaa @udf.generic_connection() seuraavilla parametreilla:

Parametri	Kuvaus	Arvo
`argName`	Funktiolle välitettävän muuttujan nimi. Käyttäjän on määritettävä tämä muuttuja funktionsa argumenteissa ja käytettävä sille tyyppiä `fn.FabricItem`	Jos esimerkiksi `argName=CosmosDb`, funktion pitäisi sisältää tämä argumentti `cosmosDb: fn.FabricItem`
`audienceType`	Kohderyhmän tyyppi, jolle yhteys luodaan. Tämä parametri liittyy Fabric-kohteen tai Azure-palvelun tyyppiin ja määrittää yhteydessä käytettävän asiakkaan.	Tämän parametrin sallitut arvot ovat `CosmosDb` tai `KeyVault`.

Yhteyden muodostaminen Fabric Cosmos DB -säilöön yleisen yhteyden avulla

Yleiset yhteydet tukevat alkuperäisiä Fabric Cosmos DB -kohteita käyttäjäryhmätyypin avulla CosmosDB . Mukana tuleva User Data Functions SDK tarjoaa apumenetelmän nimeltä get_cosmos_client , joka noutaa yksittäisen Cosmos DB -asiakasohjelman jokaista kutsua varten.

Voit muodostaa yhteyden Fabric Cosmos DB -kohteeseen käyttämällä yleistä yhteyttä seuraavasti:

Asenna azure-cosmos kirjasto Fabric User Data Functions -kohteessa kirjaston hallintakokemuksen avulla.
Siirry Fabric Cosmos DB -kohteen asetuksiin.
Hae Fabric Cosmos DB -päätepisteen URL-osoite.

Siirry Käyttäjätietofunktiot -kohtaan. Seuraavan mallikoodin avulla voit muodostaa yhteyden Fabric Cosmos DB -säilöön ja suorittaa lukukyselyn Cosmos DB -mallitietojoukon avulla. Korvaa seuraavien muuttujien arvot:

COSMOS_DB_URI Fabric Cosmos DB -päätepisteen kanssa.
DB_NAME Fabric Cosmos DB -kohteen nimellä.

from fabric.functions.cosmosdb import get_cosmos_client
import json

@udf.generic_connection(argName="cosmosDb", audienceType="CosmosDB")
@udf.function()
def get_product_by_category(cosmosDb: fn.FabricItem, category: str) -> list:

    COSMOS_DB_URI = "YOUR_COSMOS_DB_URL"
    DB_NAME = "YOUR_COSMOS_DB_NAME" # Note: This is the Fabric item name
    CONTAINER_NAME = "SampleData" # Note: This is your container name. In this example, we are using the SampleData container.

    cosmosClient = get_cosmos_client(cosmosDb, COSMOS_DB_URI)

    # Get the database and container
    database = cosmosClient.get_database_client(DB_NAME)
    container = database.get_container_client(CONTAINER_NAME)

    query = 'select * from c WHERE c.category=@category' #"select * from c where c.category=@category"
    parameters = [
        {
            "name": "@category", "value": category
        }
    ]
    results = container.query_items(query=query, parameters=parameters)
    items = [item for item in results]

    logging.info(f"Found {len(items)} products in {category}")

    return json.dumps(items)

Testaa tai suorita tämä funktio antamalla luokan nimi, kuten Accessory kutsuparametreissa.

Huomautus

Näiden vaiheiden avulla voit myös muodostaa yhteyden Azure Cosmos DB -tietokantaan tilin URL-osoitteen ja tietokannan nimien avulla. User Data Functions -omistajatilin on saatava kyseisen Azure Cosmos DB -tilin käyttöoikeudet.

Yhteyden muodostaminen Azure Key Vaultiin yleisen yhteyden avulla

Yleiset yhteydet tukevat yhteyden muodostamista Azure Key Vaultiin käyttäjäryhmätyypin avulla KeyVault . Tämäntyyppinen yhteys edellyttää, että Fabric User Data Functions -omistajalla on oikeudet muodostaa yhteys Azure Key Vaultiin. Tämän yhteyden avulla voit noutaa avaimia, salaisuuksia tai varmenteita nimen mukaan.

Voit muodostaa yhteyden Azure Key Vaultiin ja noutaa asiakasohjelman salasanan ohjelmointirajapinnan kutsumista varten yleisen yhteyden avulla seuraavasti:

Asenna Fabric User Data Functions -kohteessarequests ja kirjastot azure-keyvault-secretskirjaston hallintakokemuksen avulla.
Siirry Azure Key Vault -resurssiin ja nouda Vault URI avaimen, salasanan tai varmenteen nimi.

Palaa Fabric User Data Functions -kohtaan ja käytä tätä mallia. Tässä mallissa noudamme salaisuuden Azure Key Vaultista muodostaaksemme yhteyden julkiseen ohjelmointirajapintaan. Korvaa seuraavien muuttujien arvo:

KEY_VAULT_URL edellisessä vaiheessa noudetulla painikkeella Vault URI .
KEY_VAULT_SECRET_NAME salaisuutesi nimellä.
API_URL -muuttuja, jossa on sen API:n URL-osoite, johon haluat muodostaa yhteyden. Tässä mallissa oletetaan, että muodostat yhteyden julkiseen ohjelmointirajapintaan, joka hyväksyy GET-pyynnöt ja ottaa seuraavat parametrit api-key ja .request-body

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential
import requests

@udf.generic_connection(argName="keyVaultClient", audienceType="KeyVault")
@udf.function()
def retrieveNews(keyVaultClient: fn.FabricItem, requestBody:str) -> str:
    KEY_VAULT_URL = 'YOUR_KEY_VAULT_URL'
    KEY_VAULT_SECRET_NAME= 'YOUR_SECRET'
    API_URL = 'YOUR_API_URL'

    credential = keyVaultClient.get_access_token()

    client = SecretClient(vault_url=KEY_VAULT_URL, credential=credential)

    api_key = client.get_secret(KEY_VAULT_SECRET_NAME).value

    api_url = API_URL
    params = {
        "api-key": api_key,
        "request-body": requestBody
    }

    response = requests.get(api_url, params=params)

    data = "" 

    if response.status_code == 200:
        data = response.json()
    else:
        print(f"Error {response.status_code}: {response.text}")

    return f"Response: {data}"

Testaa tai suorita tämä funktio antamalla pyynnön runko koodissasi.

Hae kutsuominaisuudet `UserDataFunctionContext` avulla

Ohjelmointimalli sisältää myös UserDataFunctionContext-objektin. Tämä objekti sisältää funktiokutsun metatiedot, ja sen avulla voidaan luoda tietty sovelluslogiikka tietyille kutsumekanismeille.

Seuraavassa taulukossa näkyvät UserDataFunctionContext-objektin ominaisuudet:

Ominaisuuden nimi	Tietotyyppi	Kuvaus
Kutsutunnus	merkkijono	Käyttäjätietofunktiokohteen kutsuun yhdistetty yksilöllinen GUID-tunnus.
ExecutingUser	objekti	Metatiedot käyttäjän tiedoista, joita käytetään kutsun antamiseen.

ExecutingUser-objekti sisältää seuraavat tiedot:

Ominaisuuden nimi	Tietotyyppi	Kuvaus
Oid	merkkijono (GUID)	Käyttäjän objektitunnus, joka on pyytäjän muuttumaton tunnus. Tämä on sen käyttäjän tai palvelun päänimen todennettu käyttäjätieto, jota käytetään tämän funktion kutsumiseen kaikissa sovelluksissa.
Vuokraajan tunnus	merkkijono (GUID)	Sen vuokraajan tunnus, johon käyttäjä on kirjautunut sisään.
PreferredUsername	merkkijono	Käyttäjän määrittämä ensisijainen käyttäjänimi. Tämä arvo on muunnettavissa.

Jos haluat käyttää UserDataFunctionContext-parametria, sinun on käytettävä seuraavaa decorator-elementtistä funktion määrityksen yläosassa: @udf.context(argName="<parameter name>")

Esimerkki

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

Anna käsitelty virhe `UserThrownError`

Kehittäessäsi funktiota voit antaa odotetun virhevastauksen käyttämällä Python-ohjelmointimallissa käytettävissä olevaa UserThrownError-menetelmää. Tämän menetelmän avulla hallitaan tapauksia, joissa käyttäjän antamat syötteet eivät läpäise liiketoiminnan vahvistussääntöjä.

Esimerkki

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ässä UserThrownError menetelmässä on kaksi parametria:

Message: Tämä merkkijono palautetaan virhesanomana sovellukselle, joka käynnistää tämän funktion.
Ominaisuuksien sanasto palautetaan sovellukseen, joka kutsuu tätä funktiota.

Muuttujien hakeminen Fabric-muuttujakirjastoista

Microsoft Fabricin Fabric-muuttujakirjasto on keskitetty säilö muuttujien hallintaan, joita voidaan käyttää työtilan eri kohteissa. Sen avulla kehittäjät voivat mukauttaa ja jakaa esinemäärityksiä tehokkaasti.

Lisää yhteys muuttujakirjastoon Yhteyksien hallinta -toiminnolla ja hanki muuttujakirjastokohteen alias .
Lisää yhteyden koristelija, joka @udf.connection(argName="varLib", alias="<My Variable Library Alias>") viittaa muuttujan kirjastokohteen aliakseen.
Sisällytä funktion määritykseen argumentti, jonka tyyppi fn.FabricVariablesClienton . Tämä asiakasohjelma tarjoaa menetelmiä, joita tarvitset muuttujien kirjastokohteen käsittelyyn. Esimerkiksi def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Käytä getVariables() metodia saadaksesi kaikki muuttujat muuttujakirjastosta.

    # Get all variables from the variable library item
    variables = varLib.getVariables()

1 Voit lukea muuttujien arvot käyttämällä joko ["variable-name"] tai .get("variable-name").

  # Get desired format from environment or use default
  date_format = variables["DATE_FORMAT"]
  # Another way to get the variable
  # date_format= variables.get("DATE_FORMAT")

Palaute

Oliko tästä sivusta apua?

Last updated on 2025-11-10