Operatori definiti dall'utente in Lakeflow Designer

Lakeflow Designer consente di creare operatori definiti dall'utente visualizzati direttamente nell'area di disegno insieme agli operatori predefiniti. Usarli per estendere Lakeflow Designer con la propria logica di business, calcoli o integrazioni.

Gli operatori definiti dall'utente si dividono in due ambiti:

Local: L'operatore appartiene a un file di preparazione dati visivi. Descrivi la trasformazione e Genie Code genera l'operatore. Vedi Creare un operatore definito dall'utente locale con Genie Code.
Condiviso: L'operatore è registrato nello spazio di lavoro, così tu e altri utenti potete aggiungerlo a qualsiasi file di preparazione dati visivi. La sua logica è una funzione Python o una funzione Unity Catalog, descritta in YAML. Scrivilo da solo, oppure chiedi a Genie Code di crearlo. Vedi come funzionano gli operatori definiti dall'utente.

Crea un operatore locale definito dall'utente con Genie Code

Quando Genie Code è disponibile nel tuo spazio di lavoro, puoi creare un operatore definito localmente dall'utente dal canvas di Lakeflow Designer:

Nel pannello Operatori , seleziona Crea operatore definito dall'utente.

Inserisci una descrizione e, opzionalmente, un nome. Seleziona Genera anteprima.

Tip

Ad esempio, inserisci la seguente descrizione:

Count the business days between two date columns, excluding weekends. Let me choose the start and end date columns and name the output column.

Rivedi la configurazione generata e la funzione Python, poi seleziona Approva e crea.

Il designer memorizza la definizione dell'operatore locale nel file corrente e la aggiunge al pannello Operatori . Usa il menu azioni dell'operatore per modificare o eliminare la definizione. Devi rimuovere ogni istanza dell'operatore dalla tela prima di poterne eliminare la definizione.

Scegli un tipo di operatore condiviso

Gli operatori condivisi definiti dall'utente sono di tre tipi:

python-run-function: file YAML autonomo con Python inline archiviato nell'area di lavoro. Ideale per trasformazioni a livello di dataframe e integrazioni esterne. Le autorizzazioni vengono gestite a livello di file dell'area di lavoro.
uc-udf: Incapsula una funzione scalare di Unity Catalog. Ideale per le trasformazioni a livello di colonna. L'accesso è regolato dalle autorizzazioni del catalogo Unity.
uc-udtf: esegue il wrapping di una funzione con valori di tabella di Unity Catalog. Ideale per le trasformazioni a livello di tabella, ad esempio il clustering e l'aggregazione di ML. L'accesso è regolato dalle autorizzazioni del catalogo Unity.

Feature	`python-run-function`	`uc-udf`	`uc-udtf`
Esempio di caso d'uso	Trasformazioni di dataframe, integrazioni api, notifiche tramite posta elettronica	Calcoli a livello di colonna (BMI, tassi di interesse)	Clustering ML, aggregazione tra le righe
Inserimento	DataFrame	Valori singoli	Intera tabella, riga per riga
Risultato	DataFrame	Valore singolo	Tabella (più righe)
Richiede la funzione Catalog di Unity	No	Yes	Yes
Governance degli accessi	Autorizzazioni per i file dell'area di lavoro	Autorizzazioni del catalogo Unity (`EXECUTE`, `USE SCHEMA`)	Autorizzazioni del catalogo Unity (`EXECUTE`, `USE SCHEMA`)
Lingue disponibili	Solo Python	SQL o Python in un wrapper per SQL	SQL o Python in un wrapper per SQL

Funzionamento degli operatori definiti dall'utente

Un operatore condiviso definito dall'utente è composto da:

Logica dell'operatore: codice eseguito quando viene eseguito l'operatore. Questa è una funzione Python run() inline per python-run-function operatori, oppure una funzione Unity Catalog per gli operatori uc-udf e uc-udtf. Vedi Scrivere la logica per gli operatori definiti dall'utente di Lakeflow Designer.
Configurazione YAML: indica a Lakeflow Designer come presentare l'operatore nell'interfaccia utente, inclusi il nome, la descrizione, i parametri di input, i widget dell'interfaccia utente e le porte dell'operatore. Tutti i tipi di operatore usano lo user-defined-operator-v0.1.0 schema. Per un python-run-function operatore, lo YAML è un file di spazio di lavoro autonomo che contiene anche il codice inline. Per una funzione del Catalogo Unity, lo YAML è incorporato nel corpo della funzione. Vedi riferimento YAML per operatore definito dall'utente.
File di registrazione: voce in .user_defined_operators.yaml che consente a Lakeflow Designer di individuare l'operatore. Vedi Registra e distribuisci il tuo operatore in Lakeflow Designer.

Crea un operatore condiviso

Per costruire un operatore condiviso definito dall'utente dall'inizio alla fine:

Scegli un tipo di operatore. Vedi Scegli un tipo di operatore condiviso.
Scrivi e testa la logica dell'operatore. Vedi Scrivere la logica per gli operatori definiti dall'utente di Lakeflow Designer.
Descrivi l'operatore in YAML: il suo nome, le proprietà di configurazione, i widget dell'interfaccia utente e le porte. Vedi riferimento YAML per operatore definito dall'utente.
Registra l'operatore in .user_defined_operators.yaml. Vedi Registra e distribuisci il tuo operatore in Lakeflow Designer.
Concedere permessi affinché altri utenti possano scoprire ed eseguire l'operatore. Vedere Autorizzazioni.
Usa l'operatore. Appare nel pannello Operatori in Lakeflow Designer, insieme agli operatori integrati.

Ogni tutorial segue questi passaggi per un operatore dall'inizio alla fine.

Tip

Per creare un operatore condiviso python-run-function senza doverlo scrivere tu stesso, descrivilo a Genie Code nel pannello laterale. Genie Code chiede se registrare l'operatore per te o per l'intero spazio di lavoro, poi scrive il file YAML e lo registra. Devi comunque concedere permessi ad altri utenti.

Registra e distribuisci il tuo operatore in Lakeflow Designer

Affinché l'operatore venga visualizzato in Lakeflow Designer, registrarlo in un .user_defined_operators.yaml file:

Livello dell'area di lavoro: Posizionare il file nella radice dell'area di lavoro per rendere l'operatore visibile a tutti gli utenti.
Livello utente: Posizionare il file nella home folder dell'utente (/Workspace/Users/<user-name>/.user_defined_operators.yaml) per rendere visibili solo gli operatori.

La operators: sezione supporta i percorsi di file, i riferimenti alle funzioni di Unity Catalog e i modelli GLOB. È possibile combinare tipi di immissione:

operators:
  # File path (python-run-function operators)
  - /Workspace/Users/me/udos/my_operator.yaml
  # Glob pattern (registers all matching files)
  - /Workspace/Users/me/udos/transforms/*.yaml
  # UC function reference (uc-udf and uc-udtf operators)
  - catalog: my_catalog
    schema: my_schema
    functionName: my_function

Aggiornare o rimuovere un operatore

Quando si modifica il codice di un operatore, aggiornare gli operatori definiti dall'utente per applicare la modifica. Nella scheda Operatori del menu fare clic sull'icona Aggiorna.

Se l'operatore mantiene lo stesso version, l'aggiornamento carica il codice aggiornato.
Se l'operatore ha un nuovo version, l'operatore nell'area di disegno richiede di eseguire l'aggiornamento (o mantenere la versione corrente) dopo l'aggiornamento.

Per rimuovere un operatore da Lakeflow Designer, rimuovere la relativa voce da .user_defined_operators.yaml. Per gli operatori uc-udf e uc-udtf, è anche possibile rimuovere la funzione di Unity Catalog sottostante con DROP FUNCTION se non è più necessaria.

Permissions

Autorizzazione	Purpose
Accesso in lettura a `.user_defined_operators.yaml`.	Individuare l'operatore .
Accesso in lettura al file YAML (`python-run-function` soltanto).	Caricare la definizione dell'operatore.
EXECUTE sulla funzione di Unity Catalog (operatori basati solo su funzioni di Unity Catalog).	Esegui l'operatore.
USE SCHEMA sullo schema (operatori basati solo sulle funzioni del Catalogo Unity).	Accedere allo schema in cui viene creata la funzione.
Altre autorizzazioni	A seconda dell'operatore, gli utenti potrebbero richiedere altre autorizzazioni. Ad esempio, `USE CONNECTION` in una connessione del catalogo Unity per le chiamate API HTTP.

Risoluzione dei problemi

Issue	Soluzione
L'operatore non viene visualizzato in Lakeflow Designer.	Verificare che `.user_defined_operators.yaml` esista ed elencare la funzione o il percorso del file. Per `python-run-function` operatori, verificare il percorso del file e assicurarsi che il file YAML sia accessibile.
La convalida dello schema non riesce.	Verificare il codice YAML rispetto allo schema ufficiale all'indirizzo `https://your-workspace.cloud.databricks.com/static/schemas/user-defined-operator-v0.1.0.json`.
Autorizzazione negata.	Per gli operatori basati sulle funzioni del Catalogo Unity, verifica che gli utenti abbiano `EXECUTE` sulla funzione e `USE SCHEMA` sullo schema. Per gli operatori `python-run-function`, verificare che gli utenti abbiano accesso in lettura al file YAML.
`python-run-function` l'operatore ha esito negativo in fase di esecuzione.	Verificare che la firma della `run()` funzione corrisponda a `def run(config, inputs, spark)`. Verificare che i nomi delle porte nel codice corrispondano a YAML e che le chiavi del dizionario restituite corrispondano ai valori della porta `name` di output.
UDTF restituisce tipi errati.	I tipi restituiti UDTF devono essere espliciti; non è possibile fare riferimento ai tipi di colonna di input.

Risorse aggiuntive

Esplora i seguenti tutorial:

Example	Tipo	Description
Mittente di posta elettronica Gmail	`python-run-function`	Invia dati DataFrame come allegato email CSV tramite Gmail.
Calcolatore di interessi composti	`uc-udf`	Calcolare i valori di investimento futuri utilizzando la formula di interesse composta.
Clustering K-means	`uc-udtf`	Segmentare i dati in gruppi usando scikit-learn.
Invia messaggio Slack	`uc-udf`	Invia notifiche ai canali Slack tramite l'API Slack.
Tutti i widget dell'interfaccia utente	`uc-udf`	Operatore di riferimento che mostra tutti i widget dell'interfaccia utente disponibili.

Per scrivere la logica degli operatori, vedi Scrivere la logica per gli operatori definiti dall'utente di Lakeflow Designer. Per il riferimento completo dello schema YAML, vedere Riferimento YAML dell'operatore definito dall'utente.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-10-22