Общие сведения о модели программирования функций пользовательских данных Fabric

Модель программирования функций пользовательских данных Fabric определяет шаблоны и понятия для разработки функций в Fabric.

Пакет fabric-user-data-functions SDK реализует эту модель программирования, предоставляя необходимые функциональные возможности для создания и публикации выполняемых функций. Пакет SDK также позволяет легко интегрироваться с другими элементами в экосистеме Fabric, такими как источники данных Fabric. Эта библиотека общедоступна в PyPI и установлена по умолчанию в элементах функций данных пользователя.

В этой статье объясняется, как использовать пакет SDK для создания функций, которые можно вызвать с портала Fabric, других элементов Fabric или внешних приложений с помощью REST API. Вы узнаете о модели программирования и ключевых понятиях с практическими примерами.

Подсказка

Полные сведения обо всех классах, методах и параметрах см. в справочной документации по пакету SDK.

Начало работы с набором SDK

В этом разделе представлены основные компоненты пакета SDK для функций пользовательских данных и объясняется, как структурировать функции. Вы узнаете о необходимых импортах, декораторах и типах входных и выходных данных, которые могут обрабатывать функции.

Пакет SDK для функций пользовательских данных

Пакет fabric-user-data-functions SDK предоставляет основные компоненты, необходимые для создания пользовательских функций данных в Python.

Обязательные импорты и инициализация

Каждый файл функций данных пользователя должен импортировать fabric.functions модуль и инициализировать контекст выполнения:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Декоратор @udf.function()

Функции, @udf.function() помеченные декоратором, можно вызывать с портала Fabric, другого элемента Fabric или внешнего приложения. Функции с этим декоратором должны указывать возвращаемый тип.

Пример:

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

Вспомогательные функции

Методы Python без @udf.function() декоратора не могут вызываться напрямую. Они могут вызываться только из декорированных функций и служить вспомогательными функциями.

Пример:

def uppercase_name(name: str) -> str:
    return name.upper()

Поддерживаемые типы входных данных

Вы можете определить входные параметры для функции, например примитивные типы данных, такие как str, int, float и т. д. Поддерживаемые типы входных данных:

Тип JSON	Тип данных Python
Струна	стр
Строка даты и времени	дата-время
Булев	булевая переменная (bool)
Числа	целое число (int), число с плавающей точкой (float)
массива	list[], пример list[int]
Объект	Дикт
Объект	фрейм данных pandas
Объект или массив объектов	Серия pandas

Замечание

Чтобы использовать типы DataFrame и Series в pandas, перейдите на портал Fabric, найдите рабочую область и откройте элемент «Пользовательские функции данных». Выберите управление библиотекой, найдите fabric-user-data-functions пакет и обновите его до версии 1.0.0 или более поздней.

Пример текста запроса для поддерживаемых типов входных данных:

{
  "name": "Alice",                          // String (str)
  "signup_date": "2025-11-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-11-01": {"product": "A", "units": 10},
    "2025-11-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}
  ]
}

Поддерживаемые типы вывода

Поддерживаемые типы выходных данных:

Тип данных Python
стр
дата-время
булевая переменная (bool)
целое число (int), число с плавающей точкой (float)
list[тип данных], например list[int]
Дикт
Отсутствует
Серия pandas
фрейм данных pandas

Написание функций

Требования к синтаксису и ограничения

При написании пользовательских функций данных необходимо следовать определенным правилам синтаксиса, чтобы обеспечить правильную работу функций.

Именование параметров

Использование camelCase: имена параметров должны использовать соглашение об именовании camelCase и не могут содержать нижние подчеркивания. Например, используйте функцию productName вместо product_name.
Зарезервированные ключевые слова: вы не можете использовать зарезервированные ключевые слова Python или следующие ключевые слова для структуры в качестве имен параметров или имен функций: req, contextи reqInvocationId.

Требования к параметру

Обязательные примечания типов: все параметры должны включать заметки типа (например, name: str).
Значения по умолчанию: поддерживаются значения параметров по умолчанию. Аргументы по умолчанию можно определить в функциях пользовательских данных Fabric, чтобы упростить вызов и обслуживание кода. Значения по умолчанию поддерживают распространенные типы JSON-serializable, включая строки, логические значения, числа (int, float), массивы (списки) и объекты (словари). Syntax
```
    @udf.function()
    def function_name(param1: type = value1, param2: type = value2, listparam: list | None = None, ...) -> output_type:
        # function body
```
Обратите внимание, что значение по умолчанию должно быть сериализуемым в формате JSON. Например, вложенные списки, такие как [1, 2, [3]], разрешены, в то время как вложенные множества или кортежи не поддерживаются. Для списков или словарей по умолчанию предпочитайте использовать None в сигнатуре и назначать реальное значение по умолчанию внутри функции.

Требования к функциям

Обязательный тип возвращаемого значения: функции с @udf.function() декоратором должны указывать аннотацию типа возвращаемого значения (например, -> str).
Обязательные элементы: оператор и инициализацияimport fabric.functions as fn необходимы для работы ваших функций.

Пример правильного синтаксиса

@udf.function()
def process_order(orderNumber: int, customerName: str, orderDate: str) -> dict:
    return {
        "order_id": orderNumber,
        "customer": customerName,
        "date": orderDate,
        "status": "processed"
    }

Как написать асинхронную функцию

Добавьте асинхронный декоратор с определением функции в коде. async С помощью функции вы можете повысить скорость реагирования и эффективность приложения, одновременно обрабатывая несколько задач. Они идеально подходят для управления большими объемами операций ввода-вывода. В этом примере функция считывает CSV-файл из lakehouse с помощью pandas. Функция принимает имя файла в качестве входного параметра.

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

Работа с данными

Подключения к источникам данных Fabric

Пакет SDK позволяет ссылаться на подключения к данным без необходимости писать строки подключения в коде. Библиотека fabric.functions предоставляет два способа обработки подключений к данным:

fabric.functions.FabricSqlConnection: Позволяет работать с базами данных SQL в Fabric, включая конечные точки аналитики SQL и хранилища Fabric.
fabric.functions.FabricLakehouseClient: Позволяет работать с Lakehouses с способом подключения как к таблицам Lakehouse, так и к файлам Lakehouse.

Чтобы ссылаться на подключение к источнику данных, необходимо использовать декоратор @udf.connection. Его можно применить в любом из следующих форматов:

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

Аргументы для @udf.connection следующие:

argName — имя переменной, которую соединение использует в вашей функции.
alias, псевдоним подключения, добавленного в меню "Управление подключениями ".
Если argName и alias имеет то же значение, можно использовать @udf.connection("<alias and argName for the data connection>").

Пример

# 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:
  # Connect to the SQL database
  connection = demosqldatabase.connect()
  cursor = connection.cursor()
  
  # Replace with the query you want to run
  query = "SELECT * FROM (VALUES ('John Smith', 31), ('Kayla Jones', 33)) AS Employee(EmpName, DepID);"
  
  # Execute the query
  cursor.execute(query)
  
  # Fetch all results
  results = cursor.fetchall()
  
  # Close the cursor and connection
  cursor.close()
  connection.close()
  
  return results

Универсальные подключения для объектов виртуальной сети Azure или ресурсов Fabric

Пакет SDK поддерживает универсальные подключения, которые позволяют создавать соединения с элементами Fabric или ресурсами Azure, используя удостоверение владельца элемента для "Функции пользовательских данных". Эта функция генерирует токен Microsoft Entra ID с идентификацией владельца элемента и заданным типом аудитории. Этот маркер используется для проверки подлинности с помощью элементов Fabric или Azure ресурсов, поддерживающих этот тип аудитории. Этот подход обеспечивает аналогичный интерфейс программирования для использования объектов управляемых подключений из функции "Управление подключениями ", но только для указанного типа аудитории в соединении.

Эта возможность использует декоратор @udf.generic_connection() с следующими параметрами:

Параметр	Описание	Ценность
`argName`	Имя переменной, передаваемой функции. Пользователь должен указать эту переменную в аргументах своей функции и использовать для нее тип `fn.FabricItem` .	Например, если объект `argName=CosmosDb`, то функция должна содержать этот аргумент. `cosmosDb: fn.FabricItem`
`audienceType`	Тип аудитории, для которую создается подключение. Этот параметр связан с типом элемента Fabric или службой Azure и определяет клиент, используемый для подключения.	Допустимые значения для этого параметра имеют `CosmosDb` или `KeyVault`.

Подключение к контейнеру Fabric Cosmos DB с помощью универсального подключения

Поддержка общих подключений для родных элементов Fabric Cosmos DB осуществляется через тип аудитории CosmosDB. Включенный пакет SDK для функций пользовательских данных предоставляет вспомогательный метод, который get_cosmos_client получает клиент Singleton Cosmos DB для каждого вызова.

Вы можете подключиться к элементу Fabric Cosmos DB с помощью универсального подключения, выполнив следующие действия.

Перейдите на портал Fabric, найдите рабочую область и откройте элемент функций пользовательских данных. Выберите Управление библиотекой, найдите azure-cosmos библиотеку и установите ее. Дополнительные сведения см. в разделе "Управление библиотеками".
Перейдите к параметрам элемента Fabric Cosmos DB .
Получите URL-адрес конечной точки Fabric Cosmos DB.

Перейдите к элементу пользовательских функций данных. Используйте следующий пример кода для подключения к контейнеру Fabric Cosmos DB и выполнения запроса на чтение с помощью примера набора данных Cosmos DB. Замените значения следующих переменных:

COSMOS_DB_URI с конечной точкой Fabric Cosmos DB.
DB_NAME с именем вашего объекта Fabric Cosmos DB.

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)

Проверьте или запустите эту функцию , указав имя категории, например Accessory в параметрах вызова.

Замечание

Эти действия также можно использовать для подключения к базе данных Cosmos DB Azure с помощью URL-адреса учетной записи и имен баз данных. Для того чтобы учетная запись владельца функций данных пользователя могла получить разрешения на доступ к этой учетной записи Azure Cosmos DB.

Подключение к Azure Key Vault с помощью универсального подключения

Универсальные подключения поддерживают подключение к Azure Key Vault с помощью типа аудитории KeyVault. Для этого типа подключения требуется, чтобы владелец функций пользовательских данных Fabric получил разрешения на подключение к Azure Key Vault. Это подключение можно использовать для получения ключей, секретов или сертификатов по имени.

Вы можете подключиться к Azure Key Vault для получения секрета клиента для вызова API с помощью универсального подключения, выполнив следующие действия:

Перейдите на портал Fabric, найдите рабочую область и откройте элемент функций пользовательских данных. Выберите управление библиотеками, а затем найдите и установите библиотеки requests и azure-keyvault-secrets. Дополнительные сведения см. в разделе "Управление библиотеками".
Перейдите к ресурсу Azure Key Vault в Azure portal и получите Vault URI и имя ключа, секрета или сертификата.

Вернитесь к элементу Fabric User Data Functions и используйте этот пример. В этом примере мы извлекаем секрет из Azure Key Vault для подключения к общедоступному API. Замените значение следующих переменных:

Используйте KEY_VAULT_URL с Vault URI, который вы извлекли на предыдущем шаге.
KEY_VAULT_SECRET_NAME с именем секрета.
API_URL переменная с URL-адресом API, к которому вы хотите подключиться. В этом примере предполагается, что вы подключаетесь к общедоступному API, который принимает запросы GET и принимает следующие параметры api-key и 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}"

Проверьте или запустите эту функцию, предоставив текст запроса в коде.

Расширенные функции

Модель программирования определяет расширенные шаблоны, которые обеспечивают более широкий контроль над функциями. Пакет SDK реализует эти шаблоны с помощью классов и методов, которые позволяют:

Получите доступ к метаданным вызова о том, кто вызвал вашу функцию и как
Обработка пользовательских сценариев ошибок с помощью структурированных ответов об ошибках
Интеграция с библиотеками переменных Fabric для централизованного управления конфигурацией

Замечание

Функции пользовательских данных имеют ограничения службы для размера запроса, времени ожидания выполнения и размера ответа. Дополнительные сведения об этих ограничениях и их применении см. в разделе "Сведения о службе" и ограничениях.

Получите свойства вызова с помощью `UserDataFunctionContext`

Пакет SDK включает UserDataFunctionContext объект. Этот объект содержит метаданные вызова функции и может использоваться для создания определенной логики приложения для различных механизмов вызова вызовов (таких как вызов портала и вызов REST API).

В следующей UserDataFunctionContext таблице показаны свойства объекта:

Название свойства	Тип данных	Описание
invocation_id	струна	Уникальный GUID, связанный с вызовом элемента пользовательских функций данных.
executing_user	объект	Метаданные информации пользователя, используемой для авторизации вызова.

Объект executing_user содержит следующие сведения:

Название свойства	Тип данных	Описание
Оид	строка (GUID)	Идентификатор объекта пользователя, который является неизменяемым идентификатором запрашивающего объекта. Это проверенное удостоверение пользователя или субъекта-службы, используемое для вызова этой функции в приложениях.
Идентификатор арендатора (TenantId)	строка (GUID)	Идентификатор арендатора, в который вошел пользователь.
предпочитаемое имя пользователя	струна	Предпочтительное имя пользователя, который инициировал вызов, как установлено самим пользователем. Это значение является изменяемым.

Чтобы получить доступ к параметру UserDataFunctionContext, необходимо использовать следующий декоратор в начале определения функции: @udf.context(argName="<parameter name>")

Пример

@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 = {myContext.executing_user['Oid']}, TenantId = {myContext.executing_user['TenantId']}, PreferredUsername = {myContext.executing_user['PreferredUsername']}, InvocationId = {myContext.invocation_id}"

Генерация обработанной ошибки с помощью `UserThrownError`

При разработке функции можно вызвать ожидаемый ответ на ошибку с помощью UserThrownError класса, доступного в пакете SDK. Одним из вариантов использования этого класса является управление случаями, когда предоставленные пользователем входные данные не проходят правила проверки бизнеса.

Пример

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

Конструктор UserThrownError класса принимает два параметра:

Message: эта строка возвращается в виде сообщения об ошибке приложению, вызывающего эту функцию.
Словарь свойств возвращается приложению, вызывающей эту функцию.

Получение переменных из библиотек переменных Fabric

Библиотека переменных Fabric в Microsoft Fabric — это централизованный репозиторий для управления переменными, которые можно использовать в разных элементах рабочей области. Это позволяет разработчикам эффективно настраивать конфигурации элементов и предоставлять общий доступ к ним. Если у вас еще нет библиотеки переменных, см. статью "Создание библиотек переменных и управление ими".

Чтобы использовать библиотеку переменных в функциях, необходимо добавить к ней подключение из элемента функций данных пользователя. Библиотеки переменных отображаются в каталоге OneLake вместе с источниками данных, такими как базы данных SQL и озера.

Выполните следующие действия, чтобы использовать библиотеки переменных в функциях:

В элементе функций данных пользователя добавьте подключение к библиотеке переменных. В каталоге OneLake найдите и выберите библиотеку переменных, а затем нажмите кнопку Connect. Обратите внимание на псевдоним, создаваемый Fabric для подключения.
Добавьте декоратор подключения для элемента библиотеки переменных. Например, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") и замените псевдоним новым добавленным подключением для элемента библиотеки переменной.
В определении функции добавьте аргумент с типом fn.FabricVariablesClient. Этот клиент предоставляет методы, необходимые для работы с элементом библиотеки переменных.
Используйте getVariables() метод для получения всех переменных из библиотеки переменных.
Чтобы считать значения переменных, используйте ["variable-name"] либо .get("variable-name").

Пример

В этом примере мы имитируем сценарий конфигурации для рабочей среды и среды разработки. Эта функция задает путь storage в зависимости от выбранной среды, используя значение, полученное из библиотеки переменных. Библиотека переменных содержит переменную, называемую ENV , где пользователи могут задать значение dev или prod.

@udf.connection(argName="varLib", alias="<My Variable Library Alias>")
@udf.function()
def get_storage_path(dataset: str, varLib: fn.FabricVariablesClient) -> str:
    """
    Description: Determine storage path for a dataset based on environment configuration from Variable Library.
    
    Args:
        dataset_name (str): Name of the dataset to store.
        varLib (fn.FabricVariablesClient): Fabric Variable Library connection.
    
    Returns:
        str: Full storage path for the dataset.
    """
    # Retrieve variables from Variable Library
    variables = varLib.getVariables()
    
    # Get environment and base paths
    env = variables.get("ENV")    
    dev_path = variables.get("DEV_FILE_PATH")
    prod_path = variables.get("PROD_FILE_PATH")
    
    # Apply environment-specific logic
    if env.lower() == "dev":
        return f"{dev_path}{dataset}/"
    elif env.lower() == "prod":
        return f"{prod_path}{dataset}/"
    else:
        return f"incorrect settings define for ENV variable"

Справочная документация по API
Создание элемента функций пользовательских данных Fabric
примеры функций данных User

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-01-22

Поделиться через

Общие сведения о модели программирования функций пользовательских данных Fabric

Начало работы с набором SDK

Пакет SDK для функций пользовательских данных

Обязательные импорты и инициализация

Декоратор @udf.function()

Вспомогательные функции

Поддерживаемые типы входных данных

Поддерживаемые типы вывода

Написание функций

Требования к синтаксису и ограничения

Именование параметров

Требования к параметру

Требования к функциям

Пример правильного синтаксиса

Как написать асинхронную функцию

Работа с данными

Подключения к источникам данных Fabric

Пример

Универсальные подключения для объектов виртуальной сети Azure или ресурсов Fabric

Подключение к контейнеру Fabric Cosmos DB с помощью универсального подключения

Подключение к Azure Key Vault с помощью универсального подключения

Расширенные функции

Получите свойства вызова с помощью UserDataFunctionContext

Генерация обработанной ошибки с помощью UserThrownError

Получение переменных из библиотек переменных Fabric

Пример

Связанный контент

Обратная связь

Дополнительные ресурсы

Получите свойства вызова с помощью `UserDataFunctionContext`

Генерация обработанной ошибки с помощью `UserThrownError`