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

Функции пользовательских данных позволяют создавать повторно используемые функции Python, которые можно вызывать в Microsoft Fabric и из внешних приложений. Централизованная бизнес-логика в функциях позволяет поддерживать согласованность, уменьшать дублирование кода и оптимизировать рабочие процессы преобразования данных в организации.

С помощью функций пользовательских данных можно:

• Централизация бизнес-логики — запись функций один раз и их вызов из конвейеров, записных книжек, правил активации и Power BI
• Интеграция без проблем — вызов функций через конечные точки REST из любого приложения или службы
• Ускорение разработки . Использование предварительно созданных примеров функций или создание пользовательских функций с помощью модели программирования Python
• Обеспечение согласованности. Обеспечение единообразия преобразований данных и бизнес-правил для всех рабочих нагрузок

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

То, что вы делаете

В этом кратком руководстве вы выполните следующие задачи:

1. Создание элемента функций данных пользователя в рабочей области
2. Добавление и настройка необходимых библиотек Python (например, pandas)
3. Вставка функции из примера библиотеки
4. Напишите пользовательскую функцию с корректным синтаксисом и декораторами.
5. Тестирование и публикация функций
6. Выполнение функций на портале и просмотр результатов

Предпосылки

• Емкость Microsoft Fabric в одном из поддерживаемых регионов. Если у вас нет емкости Fabric, запустите бесплатную пробную версию Fabric.
• Рабочая область Fabric, назначенная этой емкости

Создание нового элемента функций данных пользователя

1. В рабочем пространстве выберите + Новый элемент.

2. Найдите и выберите плитку "Функции данных пользователя ".

   

3. Введите имя элемента функций данных пользователя и нажмите кнопку "Создать".

4. Выберите файл новой функции , чтобы создать новую образец функции. Функция hello_fabric Python публикуется и загружается в редакторе кода.

5. В обозревателе функций отображаются все опубликованные и готовые к вызову функции. hello_fabric Так как функция опубликована, ее можно запустить из списка функций в обозревателе функций.

   

Добавление новой функции из примера

В этом примере показано, как добавить новую функцию из меню "Вставка примера ". В этом случае мы добавим функцию с именем "Управление данными с помощью библиотеки pandas ", которая использует библиотеку pandas в качестве требования.

Добавление обязательных библиотек

1. Убедитесь, что вы находитесь в режиме разработки .

   

2. Выберите управление библиотеками, чтобы добавить необходимые библиотеки.

   

3. Нажмите кнопку +Добавить из PyPI , чтобы добавить новую библиотеку из общедоступного репозитория PyPI.

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

   

5. При необходимости можно обновить версию библиотеки до последней fabric_user_data_functions доступной версии. Щелкните значок карандаша рядом с библиотекой, чтобы обновить его.

   Примечание.

   Библиотека fabric_user_data_functions включена по умолчанию и не может быть удалена. Эта библиотека необходима для функциональных возможностей функций пользовательских данных. Необходимо обновить версию этой библиотеки для всех будущих выпусков этого пакета SDK.

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

Вставка примера функции

1. Выберите вкладку "Изменить ", чтобы открыть дополнительные параметры редактирования в меню ленты.

2. Выберите Вставить пример>Манипулирование данными>Манипулируйте данными с помощью библиотеки pandas. Это действие добавляет новую функцию, которая использует библиотеку pandas для управления данными.

   

3. После вставки примера в редактор вы увидите, что новая функция появится в обозревателе функций со значком круга рядом с ним. Этот значок указывает, что функция изменилась с момента последней публикации, то есть есть обновления, которые должны быть опубликованы.

   

Написать пользовательскую функцию

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

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

@udf.function()
def your_function_name(parameter: type) -> return_type:
    # Your function logic here
    return result

Ниже приведен полный пример стандартизации категорий продуктов из необработанных данных о продажах:

# This function standardizes inconsistent product category names from different data sources

@udf.function()
def standardize_category(productName: str, rawCategory: str) -> dict:
    # Define category mappings for common variations
    category_mapping = {
        "electronics": ["electronic", "electronics", "tech", "devices"],
        "clothing": ["clothes", "clothing", "apparel", "fashion"],
        "home_goods": ["home", "household", "home goods", "furniture"],
        "food": ["food", "grocery", "groceries", "snacks"],
        "books": ["book", "books", "reading", "literature"]
    }
    
    # Normalize the input
    raw_lower = rawCategory.lower().strip()
    
    # Find the standardized category
    standardized = "other"
    for standard_name, variations in category_mapping.items():
        if raw_lower in variations:
            standardized = standard_name
            break
    
    return {
        "product_name": productName,
        "original_category": rawCategory,
        "standardized_category": standardized,
        "needs_review": standardized == "other"
    }

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

Использование значений параметров по умолчанию

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

@udf.function()
def score_customer(
    customerId: str,                          # required — no default
    isActive: bool = True,                    # optional bool default
    maxRecords: int = 100,                    # optional int default
    startDate: datetime.datetime = "2025-01-01T00:00:00Z",  # specify as a string; the runtime parses it to datetime at invocation time
    tags: list | None = None,                 # optional list — use None to avoid mutable default
) -> dict:
    tags = tags or []
    return {
        "customerId": customerId,
        "isActive": isActive,
        "maxRecords": maxRecords,
        "startDate": str(startDate),
        "tags": tags,
    }

Поддерживаемые типы входных данных по умолчанию на высоком уровне:

• Сериализуемые в формате JSON строки , логические значения, целые числа и с плавающей запятой — используются непосредственно в качестве значений по умолчанию.
• Строки даты и времени — укажите их в качестве строки в сигнатуре функции; среда выполнения анализирует их как datetime во время вызова. Используйте формат ISO 8601 (например, 2025-12-31T23:59:59Zдля надежного анализа).
• Списки и словари — должны быть сериализуемыми в формате JSON. Предпочитайте использовать None в сигнатуре и присваивать реальное значение по умолчанию внутри функции, чтобы избежать общих изменяемых значений по умолчанию.
• Объекты или массивы объектов — могут быть сопоставлены с pandas DataFrame или Series. Требуется fabric-user-data-functions версия 1.0.0 или более поздняя.

Основные понятия модели программирования

Функции пользовательских данных используют модель программирования Python для пользовательских функций данных для создания, запуска, отладки и изменения отдельных функций. Модель программирования предоставляется пакетом fabric-user-data-functions , который доступен в PyPI и предварительно установлен в элементах функций пользовательских данных.

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

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Ключевые моменты в модели программирования:

• Пакет fabric-user-data-functions содержит модуль fabric.functions, который импортируется как fn в вашем коде.
• Вызов fn.UserDataFunctions() создает контекст выполнения, необходимый для определения и выполнения функций в элементе пользовательских функций данных.
• Другие библиотеки, например logging позволяют создавать пользовательские журналы для отладки и мониторинга.
• Модель программирования Python поддерживает значения аргументов по умолчанию для параметров функции. Список допустимых типов и ограничений см. в разделе "Требования к синтаксису" и "Ограничения".

Тестирование и публикация функций

Теперь, когда вы создали несколько функций (пример manipulate_data функции и настраиваемую standardize_category функцию), можно протестировать и опубликовать их вместе.

1. Хотя в режиме разработки можно протестировать каждую функцию с помощью возможности тестирования перед публикацией . Тестирование позволяет проверять изменения кода, не делая их доступными для внешнего вызова.

2. Когда вы будете готовы сделать свои функции доступными, выберите "Опубликовать ", чтобы сохранить изменения и обновить все функции. Публикация может занять несколько минут.

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

   • Запуск с портала в режиме "Только запуск "
   • Вызывается из другого элемента Fabric, например конвейера, записной книжки или правила активации
   • Вызывается из внешнего приложения через конечную точку REST

Запуск функций

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

1. Выберите "Запустить только режим " из селектора режима в правом верхнем углу портала.

   

2. Выберите значок запуска , который отображается при наведении указателя мыши на функцию в списке обозревателя функций.

   

Запуск примера функции

1. В обозревателе функций наведите указатель мыши на функцию manipulate_data .

2. Нажмите кнопку "Выполнить ", которая отображается при наведении указателя мыши на функцию.

3. Справа на экране откроется панель запуска.

4. В области выполнения вы видите имя параметра data с типом list. Введите следующее значение JSON в текстовом поле:

   [
    {
     "Name": "John",
     "Age": 22,
     "Gender": "male"
    }
   ]
   

5. Нажмите кнопку "Выполнить " в области выполнения (расположенную рядом с введенными данными JSON), чтобы выполнить функцию.

   

6. Просмотрите результаты и логи в разделе «Выходные данные» (список) в панели запуска. В выходных данных показаны обработанные данные в формате JSON в виде DataFrame pandas.

Запуск пользовательской функции

Теперь попробуйте запустить пользовательскую standardize_category функцию.

1. В обозревателе функций наведите указатель мыши на функцию standardize_category .

2. Нажмите кнопку "Выполнить ", которая отображается при наведении указателя мыши на функцию.

3. Справа на экране откроется панель запуска.

4. Укажите параметры теста:

   • productName: Laptop Computer
   • rawCategory: tech

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

Управление функциями

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

Переименование функции

1. В режиме разработки выберите редактор кода и обновите имя функции. Например, переименуйте hello_fabric в hello_fabric1:

   @udf.function()
   def hello_fabric1(name: str) -> str:
      logging.info('Python UDF trigger function processed a request.')
   
      return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"
   

2. После изменения имени выберите Опубликовать, чтобы сохранить эти изменения.

3. После публикации изменений вы увидите новое имя функции в обозревателе функций.

Удаление функции

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

Например, чтобы удалить функцию hello_fabric, удалите следующий блок кода:

@udf.function()
def hello_fabric(name: str) -> str:
    logging.info('Python UDF trigger function processed a request.')

    return f"Welcome to Fabric Functions, {name}, at {datetime.datetime.now()}!"

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

Устранение неполадок

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

• Функция не будет публиковаться . Проверьте наличие синтаксической ошибки в коде. Убедитесь, что присутствуют все необходимые импорты (fabric.functions) и строка udf = fn.UserDataFunctions().
• Ошибки именования параметров - Помните, что имена параметров должны быть в формате camelCase (без нижних подчеркиваний). Просмотрите требования к синтаксису и ограничения.
• Ошибки импорта библиотеки . Убедитесь, что все необходимые библиотеки добавляются с помощью управления библиотеками и что версия совместима с Python 3.11.
• Функция не отображается в обозревателе функций . Убедитесь, что вы опубликовали изменения после добавления или изменения функций.
• Проблемы со значением по умолчанию - Если функция не выполняется или анализ входных данных выполняется неправильно:
  • Используйте формат ISO 8601 (например, 2025-12-31T23:59:59Z) для значений по умолчанию даты и времени, чтобы обеспечить надежный анализ.
  • Избегайте изменения значений по умолчанию для списков и словарей. Используйте None сигнатуру функции и назначьте реальное значение по умолчанию внутри тела функции (например, items = items or []).
  • Убедитесь, что все значения по умолчанию сериализуются в формате JSON. Наборы и кортежи не поддерживаются по умолчанию.
  • Убедитесь, что имена параметров и значения по умолчанию соответствуют ожидаемым значениям. Если ваша функция использует pandas DataFrame или Series по умолчанию, убедитесь fabric-user-data-functions, что пакет версии 1.0.0 или новее.

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

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

Теперь, когда вы создали свой первый элемент функции пользовательских данных, изучите эти ресурсы, чтобы расширить свои навыки:

• Создание элемента функций пользовательских данных Fabric в Visual Studio Code . Узнайте, как разрабатывать функции локально с полной поддержкой интегрированной среды разработки
• Узнайте о модели программирования функций данных пользователей. Подробнее о пакете SDK для Python и расширенных функциях
• Вызов функций пользовательских данных из приложения Python . Вызов функций из внешних приложений через REST API
• Управление библиотеками для функций пользовательских данных — дополнительные методы управления библиотеками