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

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

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

Элемент функций пользовательских данных содержит одну или несколько функций, которые можно вызвать с портала Fabric, из другого элемента Fabric или из внешнего приложения с помощью предоставленной конечной точки REST. Каждая функция — это метод в скрипте Python, который позволяет передавать параметры и возвращать выходные данные вызывающей функции. Модель программирования функций пользовательских данных содержит следующие компоненты:

Библиотека fabric.functions предоставляет код, необходимый для создания пользовательских функций данных в Python. Эта библиотека импортируется в первом шаблоне функции при создании нового элемента функций данных пользователя.
fn.UserDataFunctions() Метод предоставляет контекст выполнения, найденный в начале файла кода во всех новых функциях пользовательских данных, до любых определений функций.

Пример:
```
import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()
```
Каждая функция идентифицируется с помощью декоратора @udf.function(). Этот декоратор определяет, может ли функция вызываться отдельно с портала или внешнего вызывающего объекта. Для использования этого декоратора также требуется, чтобы функция возвращала значение. Функции с этим декоратором могут получить доступ к объектам подключения, обозначенным декоратором @udf.connection.

Пример вызываемой функции
```
# 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()}!"
```
Любые методы Python без @udf.function() декоратора не могут вызываться напрямую. Их можно вызывать только из функций, содержащих декоратор, и их можно использовать в качестве вспомогательных функций.

Пример вспомогательной функции
```
# 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()
```

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

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

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

Замечание

Чтобы использовать типы DataFrame и Series pandas, выберите управление библиотеками на портале Fabric для функции данных пользователя и обновите fabric-user-data-function до версии 1.0.0.

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

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

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

Добавьте асинхронный декоратор с определением функции в коде. 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

Этот модуль позволяет ссылаться на подключения к данным без необходимости писать строки подключения в коде. Библиотека 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:
  # 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

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

Универсальные подключения позволяют создавать подключения к элементам 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 в параметрах вызова.

Замечание

Эти действия также можно использовать для подключения к базе данных Azure Cosmos DB с помощью 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 и получите Vault URI имя ключа, секрета или сертификата.
Вернитесь к элементу функций пользовательских данных Fabric и используйте этот пример. В этом примере мы извлекаем секрет из 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}"
```
Проверьте или запустите эту функцию, предоставив текст запроса в коде.

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

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

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

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

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

Название свойства	Тип данных	Описание
Оид	строка (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 = {context.executing_user['Oid']}, TenantId = {context.executing_user['TenantId']}, PreferredUsername = {context.executing_user['PreferredUsername']}, InvocationId = {context.invocation_id}"

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

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

Пример

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 — это централизованный репозиторий для управления переменными, которые можно использовать в разных элементах рабочей области. Это позволяет разработчикам эффективно настраивать конфигурации элементов и предоставлять общий доступ к ним.

Добавьте подключение к библиотеке переменных с помощью управления подключениями и получите псевдоним для элемента библиотеки переменной.
Добавьте декоратор подключения, @udf.connection(argName="varLib", alias="<My Variable Library Alias>"), чтобы ссылаться на алиас переменной из библиотеки.
В определении функции добавьте аргумент с типом fn.FabricVariablesClient. Этот клиент предоставляет методы, необходимые для работы с элементом библиотеки переменных. Например: def standardize_date(rawDate: str, varLib: fn.FabricVariablesClient) -> str:
Используйте getVariables() метод для получения всех переменных из библиотеки переменных.

    # Get all variables from the variable library item
    variables = varLib.getVariables()

1 Чтобы прочитать значения переменных, используйте либо ["variable-name"], либо .get("variable-name").

  # Get desired format from environment or use default
  date_format = variables["DATE_FORMAT"]
  # Another way to get the variable
  # date_format= variables.get("DATE_FORMAT")

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

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

Last updated on 2025-11-10