Generování kódu vyvolání pro funkce uživatelských dat

Po publikování funkcí uživatelských dat je můžete volat z prvků Fabric nebo z externích aplikací. Místo psaní kódu vyvolání úplně od začátku použijte funkci Generovat vyvolání kódu k automatickému vytváření šablon kódu připravených k použití.

Zvolte možnost generování kódu na základě vašeho scénáře integrace:

• Fabric Notebooks kód (Python) – pro vyvolání funkcí z Fabric Notebooks, což je jeden ze způsobů integrace s položkami Fabric. Další položky infrastruktury, jako jsou Kanály a Aktivátor, najdete v dokumentaci k integraci.
• Kód klientské aplikace (Python, C#, Node.js) – pro volání funkcí z externích aplikací prostřednictvím jedinečného koncového bodu REST, který každá funkce zveřejňuje. To umožňuje integraci s webovými aplikacemi, službami nebo jakýmkoli systémem mimo Fabric.
• Specifikace OpenAPI (JSON, YAML) – pro platformy api management, agenty AI nebo generování klientských sad SDK. Použijte to k integraci funkcí se službou Azure API Management, konfiguraci systémů AI nebo generování knihoven pro externí aplikace.

Požadavky

Než vygenerujete invokační kód, musíte:

• Publikovaná položka Funkce uživatelských dat s alespoň jednou funkcí
• Přístup k položce Funkce uživatelských dat na portálu Fabric
• Alespoň spustit oprávnění pro položku Funkce uživatelských dat k vygenerování a použití vyvolání kódu

Generování kódu pro Fabric poznámkové bloky

Při integraci s Fabric položkami můžete využít tuto možnost k volání funkcí z Fabric Notebooks. Vygenerovaný kód používá integrovaný mssparkutils.userDataFunction nástroj, který poskytuje jednoduchý způsob volání funkcí bez správy ověřování nebo koncových bodů. To je ideální pro pracovní postupy zpracování dat, průzkumnou analýzu a kanály strojového učení v rámci prostředí Fabric.

1. Otevřete položku Funkce uživatelských dat na portálu Fabric.

2. Na kartě Domů vyberte Generovat kód vyvolání>kód klienta.

3. V části Vyvolat z v rozevíracím seznamu vyberte Notebook.

4. Vyberte název funkce, kterou chcete vyvolat.

5. Kód se automaticky vygeneruje v Pythonu. (Python je jediný jazyk dostupný pro kód vyvolání poznámkového bloku.)

   

6. Zkopírujte vygenerovaný fragment kódu.

7. Vložte to do nové buňky ve Fabric notebooku.

8. Aktualizujte parametry funkce skutečnými hodnotami. Vygenerovaný kód obsahuje komentář ukazující, kde se má aktualizovat:

   # UPDATE BELOW: Update the request body based on the inputs to your function
   myFunctions.hello_fabric(name = "string")
   

9. Spusťte buňku pro vyvolání vaší funkce.

Další informace naleznete v uživatelských funkcích pro data v poznámkovém bloku Fabric.

Generování kódu pro klientské aplikace

Při integraci s externími aplikacemi tuto možnost použijte k volání funkcí prostřednictvím jedinečného koncového bodu REST, který každá funkce zveřejňuje. Vygenerovaný kód zahrnuje nastavení ověřování pomocí ID Microsoft Entra a zpracovává tok požadavků a odpovědí HTTP. To vám umožní vyvolat funkce Fabric z webových aplikací, mobilních aplikací, mikroslužeb nebo jakéhokoli systému mimo prostředí Fabric.

1. Otevřete položku Funkce uživatelských dat na portálu Fabric.

2. Na kartě Domů vyberte Vygenerovat kód vyvolání>klientský kód.

3. Vyberte z rozevíracího seznamu v části Vyvolat z možnost Klientská aplikace.

4. Vyberte název funkce, kterou chcete vyvolat.

5. Zvolte programovací jazyk:

   • Python
   • C#
   • Node.js

   

6. Zkopírujte vygenerovaný kód a přidejte ho do aplikace.

7. Zkontrolujte strukturu kódu:

   • Ověřování – používá InteractiveBrowserCredential se k získání tokenu (pouze pro vývoj/testování).
   • Adresa URL koncového bodu – jedinečný koncový bod REST pro vaši konkrétní funkci
   • Text požadavku – obsahuje vstupní parametry, které vaše funkce očekává.

8. Aktualizujte oddíl request_body skutečnými hodnotami parametrů. Vygenerovaný kód obsahuje komentář ukazující, kde se má aktualizovat:

   # UPDATE HERE: Update the request body based on the inputs to your function 
   request_body = {
       "name": "string"
   }
   

9. V produkčních aplikacích nahraďte ověřovací kód správnou registrací aplikace Microsoft Entra ID. Vygenerovaný kód obsahuje upozornění a odkaz na pokyny pro produkční ověřování.

Úplný návod, včetně nastavení provozního ověřování, najdete v tématu Vyvolání funkcí uživatelských dat z aplikace v Pythonu.

Generování specifikace OpenAPI

Pokud potřebujete integrovat funkce s platformami API Management, agenty AI nebo vygenerovat klientské sady SDK pro externí aplikace, použijte tuto možnost k vytvoření specifikace OpenAPI. Specifikace OpenAPI poskytuje strojově čitelný popis koncových bodů REST vaší funkce, což usnadňuje nástrojům a systémům zjišťování a integraci s vašimi funkcemi prostřednictvím kódu programu.

1. Otevřete položku Funkce uživatelských dat na portálu Fabric.

2. Na kartě Domů vyberte Vygenerovat kód pro vyvolání>specifikace OpenAPI.

3. V dialogovém okně Generovat specifikaci OpenAPI vyberte výstupní formát:

   • JSON
   • YAML

   

4. Zkopírujte vygenerovanou specifikaci. Specifikace zahrnuje:

   • Všechny publikované funkce v položce Funkce uživatelských dat
   • Schémata požadavků a odpovědí pro každou funkci
   • Požadavky na ověřování (nosný token)
   • Standardní chybové odpovědi HTTP (400, 401, 403, 408, 413, 500)
   • Souhrny a popisy funkcí (z docstrings)

Vylepšení výstupu OpenAPI pomocí docstrings

Kvalita specifikace OpenAPI závisí na dokumentaci v kódu funkce. Když systémy, jako je Azure API Management, agenti AI nebo nástroje dokumentace k rozhraní API, využívají specifikace OpenAPI, spoléhají na jasné popisy, abyste porozuměli tomu, co vaše funkce dělají.

Generátor OpenAPI automaticky extrahuje informace z dokumentace funkcí. Přidejte do svých funkcí tyto vlastnosti a vytvořte komplexní dokumentaci k rozhraní API:

• Shrnutí – jednořádové vysvětlení, které se zobrazuje v katalogech rozhraní API a zobrazeních vysoké úrovně
• Popis – podrobné vysvětlení toho, co funkce dělá, jaké vstupy očekává a co vrací

Ukázková funkce se správnou dokumentací:

@udf.function()
def hello_fabric(name: str) -> str:
    """
    Summary: A Python function that prints your name and the time.
    Description: This function takes a string input and concatenates it with the current time 
    to give you a warm welcome to User Data Functions. Returns a string and provides a log entry.
    """
    logging.info('Python UDF trigger function processed a request.')
    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

Když vygenerujete specifikaci OpenAPI, tyto hodnoty docstringu naplní summary a description pole ve schématu OpenAPI, což vývojářům a systémům usnadňuje pochopení toho, jak používat funkce.

Běžné použití vygenerovaného kódu

Jakmile vygenerujete kód vyvolání, můžete ho použít k integraci funkcí do různých scénářů:

Integrace položek struktury:

• Volání funkcí z poznámkových bloků pro zpracování dat, strojové učení a průzkumnou analýzu
• Orchestrace funkcí v Pipe-line pro transformační pracovní postupy s daty
• Aktivace funkcí z pravidel aktivátoru v reakci na události v reálném čase

Integrace externích aplikací:

• Volání funkcí z webových aplikací, mobilních aplikací nebo mikroslužeb pomocí kódu klientské aplikace
• Import specifikací OpenAPI do služby Azure API Management nebo jiných bran rozhraní API pro centralizovanou správu
• Generování klientských sad SDK pomocí generátoru OpenAPI pro konzistentní integraci napříč několika systémy
• Konfigurace agentů AI ke zjišťování a volání funkcí pomocí specifikace OpenAPI
• Testování a ověřování funkcí pomocí nástrojů, jako je Postman nebo Swagger UI

Související obsah

• Vyvolání funkcí uživatelských dat z aplikace v Pythonu – Úplný návod pro volání funkcí z externích aplikací Pythonu
• Fabric Notebook utilities – Referenční informace pro volání funkcí z poznámkových bloků
• Integrace s potrubími Fabric – Používejte funkce v datových potrubích
• Programovací model Pythonu – Naučte se psát funkce se správnými docstringy