Operadores definidos por el usuario en Lakeflow Designer

Lakeflow Designer permite crear operadores definidos por el usuario que aparecen directamente en el lienzo junto con operadores integrados. Úselos para ampliar Lakeflow Designer con su propia lógica de negocios, cálculos o integraciones.

Los operadores definidos por el usuario existen en dos alcances:

Crea un operador definido localmente por el usuario con Genie Code

Cuando Genie Code esté disponible en tu espacio de trabajo, puedes crear un operador definido localmente por el usuario a partir del lienzo de Lakeflow Designer:

  1. En el panel Operadores, selecciona Crear operador definido por el usuario.

  2. Introduce una descripción y, opcionalmente, un nombre. Selecciona Generar vista previa.

    Tip

    Por ejemplo, introduce la siguiente descripción:

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

  3. Revisa la configuración generada y la función de Python, luego selecciona Aprobar y crear.

El diseñador almacena la definición del operador local en el archivo actual y la añade al panel Operadores. Utiliza el menú de acciones del operador para editar o eliminar la definición. Debes eliminar todas las instancias del operador del lienzo antes de poder eliminar su definición.

Elige un tipo de operador compartido

Los operadores compartidos definidos por el usuario tienen tres tipos:

  • python-run-function: un archivo YAML independiente con código Python integrado almacenado en el área de trabajo. Mejor para las transformaciones de nivel de DataFrame y las integraciones externas. Los permisos se administran en el nivel de archivo del área de trabajo.
  • uc-udf: encapsula una función escalar de Unity Catalog. Ideal para transformaciones a nivel de columna. El acceso se rige por los permisos del catálogo de Unity.
  • uc-udtf: encapsula una función con valores de tabla de Unity Catalog. Lo mejor para las transformaciones de nivel de tabla, como la agrupación en clústeres de ML y la agregación. El acceso se rige por los permisos del catálogo de Unity.
Feature python-run-function uc-udf uc-udtf
Ejemplo de caso de uso Transformaciones de DataFrame, integraciones de API, notificaciones por correo electrónico Cálculos de nivel de columna (IMC, tasas de interés) Agrupación por clústeres de aprendizaje automático, agregación a través de las filas
Entrada Marcos de datos Valores únicos Tabla completa, fila por fila
Output Marcos de datos Valor único Tabla (varias filas)
Requiere la función catálogo de Unity No Sí Sí
Gobernanza del acceso Permisos de archivo del área de trabajo Permisos de Unity Catalog (EXECUTE, USE SCHEMA) Permisos de Unity Catalog (EXECUTE, USE SCHEMA)
Idiomas compatibles Únicamente Python SQL o Python en un contenedor de SQL SQL o Python en un contenedor de SQL

Funcionamiento de los operadores definidos por el usuario

Un operador compartido definido por el usuario consiste en:

  • Lógica del operador: código que se ejecuta cuando se ejecuta el operador. Esta es una función Python run() en línea para los operadores python-run-function, o una función de Unity Catalog para los operadores uc-udf y uc-udtf. Consulta Escribir lógica para operadores definidos por el usuario de Lakeflow Designer.
  • Configuración de YAML: indica al Diseñador de Lakeflow cómo presentar el operador en la interfaz de usuario, incluido el nombre del operador, la descripción, los parámetros de entrada, los widgets de interfaz de usuario y los puertos. Todos los tipos de operador usan el user-defined-operator-v0.1.0 esquema. Para un python-run-function operador, el YAML es un archivo de espacio de trabajo independiente que también contiene el código en línea. Para una función de Unity Catalog, el YAML está incrustado en el cuerpo de la función. Consulta la referencia YAML de operador definido por el usuario.
  • Archivo de registro: una entrada en .user_defined_operators.yaml que permite que Lakeflow Designer detecte el operador. Consulta Registra e implementa tu operador en Lakeflow Designer.

Crear un operador común

Para construir un operador compartido definido por el usuario de principio a fin:

  1. Elige un tipo de operador. Ver Elegir un tipo de operador compartido.
  2. Escribe y prueba la lógica del operador. Consulta Escribir lógica para operadores definidos por el usuario de Lakeflow Designer.
  3. Describe el operador en YAML: su nombre, propiedades de configuración, widgets de la interfaz y puertos. Consulta la referencia YAML de operador definido por el usuario.
  4. Registre al operador en .user_defined_operators.yaml. Consulta Registrar e implementar tu operador en Lakeflow Designer.
  5. Conceder permisos para que otros usuarios puedan descubrir y ejecutar el operador. Consulte Permisos.
  6. Usa el operador. Aparece en el panel de Operadores en Lakeflow Designer, junto con los operadores integrados.

Cada tutorial recorre estos pasos de principio a fin para un operador.

Tip

Para crear un operador compartido python-run-function sin escribirlo tú mismo, descríbelo a Genie Code en el panel lateral. Genie Code pregunta si debe registrar el operador para ti o para todo el espacio de trabajo, luego escribe el archivo YAML y lo registra. Aún necesitas conceder permisos a otros usuarios.

Registro e implementación del operador en Lakeflow Designer

Para que el operador aparezca en Lakeflow Designer, regístrelo en un .user_defined_operators.yaml archivo:

  • Nivel de área de trabajo: Coloque el archivo en la raíz del área de trabajo para que el operador sea visible para todos los usuarios.
  • Nivel de usuario: Coloque el archivo en la carpeta principal del usuario (/Workspace/Users/<user-name>/.user_defined_operators.yaml) para que los operadores sean visibles solo para usted.

La operators: sección admite rutas de acceso de archivo, referencias a funciones de Catálogo de Unity y patrones globales. Puede mezclar tipos de entrada:

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

Actualizar o quitar un operador

Al cambiar el código de un operador, actualice los operadores definidos por el usuario para cargar el cambio. En la pestaña Operadores del menú, haga clic en icono Actualizar.

  • Si el operador mantiene el mismo version, al actualizar se carga el código actualizado.
  • Si el operador tiene un nuevo version, el operador en el lienzo te pedirá que lo actualices (o que mantengas la versión actual) después de actualizar la página.

Para quitar un operador de Lakeflow Designer, elimine su entrada de .user_defined_operators.yaml. Para los operadores uc-udf y uc-udtf, también puedes eliminar la función subyacente de Unity Catalog con DROP FUNCTION si ya no la necesitas.

Permissions

Permiso propósito
Acceso de lectura a .user_defined_operators.yaml. Detectar el operador.
Acceso de lectura al archivo YAML (python-run-function solo). Cargue la definición del operador.
EXECUTE en la función Unity Catalog (operadores basados solo en funciones Unity Catalog). Ejecutar el operador.
USE SCHEMA sobre el esquema (operadores basados solo en funciones del Catálogo de Unity). Acceda al esquema donde se crea la función.
Otros permisos Según el operador, los usuarios pueden requerir otros permisos. Por ejemplo, USE CONNECTION en una conexión de Unity Catalog para llamadas a la API HTTP.

Troubleshooting

Issue Solución
El operador no aparece en el Diseñador de Lakeflow. Compruebe que .user_defined_operators.yaml existe e incluye su función o la ruta de acceso del archivo. Para los operadores python-run-function, verifique la ruta del archivo y que el archivo YAML sea accesible.
Se produce un error en la validación del esquema. Compruebe el CÓDIGO YAML con el esquema oficial en https://your-workspace.cloud.databricks.com/static/schemas/user-defined-operator-v0.1.0.json.
permiso denegado. Para operadores basados en funciones del Catálogo de Unity, verifica que los usuarios tengan EXECUTE sobre la función y USE SCHEMA sobre el esquema. Para los operadores python-run-function, compruebe que los usuarios tienen acceso de lectura al archivo YAML.
python-run-function el operador produce un error en tiempo de ejecución. Compruebe que la firma de la run() función coincide con def run(config, inputs, spark). Compruebe que los nombres de puerto del código coincidan con YAML y que las claves de diccionario de retorno coincidan con los valores del puerto name de salida.
UDTF devuelve tipos incorrectos. Los tipos de retorno de las UDTF deben ser explícitos; no se puede hacer referencia a los tipos de las columnas de entrada.

Recursos adicionales

Explore los siguientes tutoriales:

Example Tipo Description
Remitente de correo electrónico de Gmail python-run-function Envía datos de DataFrame como archivo adjunto CSV en un correo a través de Gmail.
Calculadora de interés compuesto uc-udf Calcule los valores de inversión futuros mediante la fórmula de interés compuesto.
Agrupación en clústeres K-Means uc-udtf Segmente los datos en clústeres mediante scikit-learn.
Enviar mensaje de Slack uc-udf Envía notificaciones a los canales de Slack a través de la API de Slack.
Todos los widgets de interfaz de usuario uc-udf Operador de referencia que muestra todos los widgets de interfaz de usuario disponibles.

Para escribir la lógica de operadores, véase Escribir lógica para operadores definidos por el usuario de Lakeflow Designer. Para obtener una referencia completa al esquema YAML, consulte Referencia de YAML del operador definido por el usuario.

  • Se actualizó por última vez el