Compartir a través de

Información general sobre el modelo de programación de funciones de datos de usuario de Fabric (versión preliminar)

El modelo de programación de funciones de datos de usuario de Fabric es un SDK que proporciona la funcionalidad necesaria para crear y publicar funciones ejecutables en Fabric. El SDK también le permitirá integrarse sin problemas con otros elementos del ecosistema de Fabric, como orígenes de datos de Fabric. Esta biblioteca está disponible públicamente en PyPI y se encuentra preinstalada en los elementos de funciones de datos de usuario.

SDK de funciones de datos de usuario

Un elemento de funciones de datos de usuario contiene una o varias funciones que se invocan desde el portal de Fabric, desde otro elemento de Fabric o desde una aplicación externa mediante el punto de conexión de REST proporcionado. Cada función es un método en el script de Python que permite pasar parámetros y devolver una salida al invocador. El modelo de programación de funciones de datos de usuario contiene los siguientes componentes:

  • La biblioteca fabric.functions proporciona el código necesario para crear funciones de datos de usuario en Python. Verá que esta biblioteca se importa en la primera plantilla de funciones al crear un nuevo elemento de funciones de datos de usuario.

  • El método fn.UserDataFunctions() proporciona el contexto de ejecución. Se agrega al principio del archivo de código en todos los elementos de funciones de datos de usuario nuevos, antes de cualquier definición de función.

    Ejemplo:

    import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

  • Cada función se identifica con un decorador @udf.function(). Este decorador definirá si la función se puede invocar individualmente desde el portal o un invocador externo.

    Ejemplo de función invocable

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

  • Los métodos de Python sin el decorador @udf.function() no se pueden invocar directamente. Solo se pueden invocar desde funciones que contengan el decorador y se pueden usar como funciones auxiliares.

    Ejemplo de función asistente

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

Tipos de entrada admitidos

Es posible definir parámetros de entrada para la función, como tipos de datos primitivos como str, int, float, etc. Los tipos de datos de entrada admitidos son:

Tipo JSON Tipo de datos de Python
Cuerda Str
Cadena Fecha y hora fecha y hora
Booleano booleano
Números entero, flotante
Matriz list[], ejemplo list[int]
objeto diccionario

Tipos de salida compatibles

Los tipos de datos de salida admitidos son:

Tipo de datos de Python
Str
fecha y hora
booleano
int, float
list[data-type], por ejemplo list[int]
diccionario
Ninguno

Conexiones de datos a orígenes de datos de Fabric

Este módulo permite hacer referencia a las conexiones de datos sin necesidad de escribir cadenas de conexión en el código. La biblioteca fabric.functions proporciona dos maneras de controlar las conexiones de datos:

  • fabric.functions.FabricSqlConnection: permite trabajar con bases de datos SQL en Fabric, incluyendo los puntos de conexión de SQL Analytics y los almacenes de Fabric.
  • fabric.functions.FabricLakehouseClient: permite trabajar con almacenes de lago, con una manera de conectarse tanto a tablas de almacén de lago como a archivos de almacén de lago.

Para hacer referencia a una conexión a un origen de datos, es necesario usar el decorador @udf.connection. Aplíquelo en cualquiera de los siguientes formatos:

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

Los argumentos de @udf.connection son:

  • argName, el nombre de la variable que usará la conexión en la función.
  • alias, el alias de la conexión que agregó con el menú Administrar conexiones.
  • Si argName y alias tuvieran el mismo valor, use @udf.connection("<alias and argName for the data connection>").

Ejemplo

# 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

Obtención de propiedades de invocación mediante UserDataFunctionContext

El modelo de programación también incluye el objeto UserDataFunctionContext. Este objeto contiene los metadatos de invocación de funciones y se puede usar para crear una lógica de aplicación específica para determinados mecanismos de invocación.

En la tabla siguiente se muestran las propiedades del objeto UserDataFunctionContext:

Nombre de propiedad Tipo de datos Descripción
Id. de invocación cuerda / cadena GUID único asociado a la invocación del elemento de funciones de datos de usuario.
UsuarioEjecutor objeto Metadatos de la información del usuario utilizada para autorizar la invocación.

El objeto ExecutingUser contiene la siguiente información:

Nombre de propiedad Tipo de datos Descripción
OID cadena (GUID) Id. de objeto del usuario, que es un identificador inmutable para el solicitante. Esta es la identidad comprobada del usuario o la entidad de servicio que se usa para invocar esta función en todas las aplicaciones.
Id. de inquilino cadena (GUID) Id. del inquilino en el que el usuario inició sesión.
NombreDeUsuarioPreferido cuerda / cadena El nombre de usuario preferido del usuario que invoca, tal y como lo establece el usuario. Este valor es mutable.

Para acceder al parámetro UserDataFunctionContext, use el siguiente decorador en la parte superior de la definición de función: @udf.context(argName="<parameter name>")

Ejemplo

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

Iniciar un error controlado con UserThrownError

Al desarrollar la función, es posible producir una respuesta de error esperada con el método UserThrownError, disponible en el modelo de programación de Python. Un uso de este método consiste en administrar casos en los que las entradas proporcionadas por el usuario no superen las reglas de validación empresarial.

Ejemplo

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

Este método UserThrownError toma dos parámetros:

  • Message: esta cadena se devolverá como mensaje de error a la aplicación que invoque esta función.
  • Diccionario de propiedades que se devolverán a la aplicación que invoque esta función.

Pasos siguientes