Criar um item de funções de dados de utilizador do Fabric

As Funções de Dados de Utilizador permitem-lhe criar funções Python reutilizáveis que podem ser invocadas em todo o Microsoft Fabric e a partir de aplicações externas. Ao centralizar a sua lógica de negócio em funções, pode manter a consistência, reduzir a duplicação de código e otimizar os fluxos de trabalho de transformação de dados em toda a sua organização.

Com as Funções de Dados do Utilizador, pode:

• Centralizar a lógica de negócio - Escrever funções uma vez e invocá-las a partir de Pipelines, Notebooks, as regras dos Ativadores e Power BI
• Integrar de forma fluida - Chamar funções via endpoints REST a partir de qualquer aplicação ou serviço
• Acelerar o desenvolvimento - Use funções de exemplo pré-construídas ou crie funções personalizadas com o modelo de programação Python
• Manter a consistência - Garantir que as transformações de dados e as regras de negócio são aplicadas de forma uniforme em todas as cargas de trabalho

Este quickstart mostra-te como criar o teu primeiro item de Funções de Dados de Utilizador, adicionar funções da biblioteca de exemplo, escrever funções personalizadas e executá-las no portal do Fabric. No final, tens uma função funcional que demonstra a padronização por categorias para dados de produtos.

O que você realiza

Neste início rápido, você conclui as seguintes tarefas:

1. Crie um item de Funções de Dados de Utilizador no seu espaço de trabalho
2. Adicionar e configurar as bibliotecas Python necessárias (como o pandas)
3. Inserir uma função da biblioteca de exemplos
4. Escreva uma função personalizada com sintaxe e decoradores adequados
5. Testa e publica as tuas funções
6. Execute funções no portal e veja os resultados

Pré-requisitos

• Uma capacidade Microsoft Fabric numa das regiões suportadas. Se não tiver uma capacidade Fabric, comece um teste gratuito do Fabric.
• Um espaço de trabalho Fabric atribuído a essa capacidade

Criar um novo item de funções de dados do usuário

1. No espaço de trabalho, selecione + Novo item.

2. Procure e selecione o quadro de funções de dados do utilizador.

   

3. Introduza um Nome para o item de funções de dados do utilizador e selecione Criar.

4. Selecione o ficheiro de função Nova para criar uma nova função de amostra. A hello_fabric função Python é publicada e carregada no editor de código.

5. O explorador de funções mostra todas as funções que estão publicadas e prontas para serem invocadas. Como a hello_fabric função está publicada, pode executá-la a partir da lista de funções no explorador de funções.

   

Adicionar uma nova função a partir do exemplo

Este exemplo mostra como adicionar uma nova função a partir do menu Inserir exemplos . Neste caso, adicionamos uma função chamada Manipular dados com a biblioteca pandas que usa a pandas biblioteca como requisito.

Adicionar bibliotecas obrigatórias

1. Certifica-te de que estás em modo Desenvolvimento.

   

2. Selecione Gestão de Bibliotecas para adicionar as bibliotecas que a sua função requer.

   

3. Selecione +Adicionar do PyPI para adicionar uma nova biblioteca do repositório público do PyPI.

4. Procura e seleciona a biblioteca pandas e seleciona a versão. Depois que a biblioteca é adicionada, ela é salva automaticamente no item Funções de dados do usuário.

   

5. Opcionalmente, pode atualizar a versão da fabric_user_data_functions biblioteca para a versão mais recente disponível. Seleciona o ícone do lápis ao lado da biblioteca para o atualizar.

   Observação

   A fabric_user_data_functions biblioteca está incluída por defeito e não pode ser removida. Esta biblioteca é necessária para a funcionalidade das funções de dados do usuário. Você precisa atualizar a versão desta biblioteca para quaisquer versões futuras deste SDK.

6. Feche o painel de gestão da Biblioteca para voltar à página inicial das Funções de Dados do Utilizador.

Inserir a função de amostra

1. Selecione o separador Editar para abrir mais opções de edição na faixa de opções.

2. Selecione Inserir exemplo>Manipulação de Dados>Manipule dados com a biblioteca pandas. Esta ação adiciona uma nova função que utiliza a pandas biblioteca para manipular dados.

   

3. Depois de o exemplo ser inserido no editor, verá a nova função aparecer no explorador de Funções com um ícone circular ao lado. Este ícone indica que a função mudou desde a última publicação, o que significa que há atualizações que precisam de ser publicadas.

   

Escrever uma função personalizada

Agora que adicionou uma função da biblioteca de exemplo, pode escrever a sua própria função personalizada diretamente no editor de código. Esta secção mostra-lhe a sintaxe e a estrutura necessárias para criar funções do zero.

Toda função executável requer o @udf.function() decorador antes da definição da função. Este decorador marca a sua função Python como executável dentro do framework User Data Functions. A sintaxe básica é:

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

Aqui está um exemplo completo que padroniza categorias de produtos a partir de dados brutos de vendas:

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

Pode adicionar esta função ao seu editor de código juntamente com as funções existentes. A função aparece no explorador de Funções com um ícone circular, indicando que precisa de ser publicada.

Utilização de valores de parâmetros padrão

As funções podem definir valores predefinidos para qualquer parâmetro, tornando esses parâmetros opcionais no momento da invocação. O exemplo seguinte mostra uma função com vários tipos de valores padrão:

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

Tipos de entrada padrão suportados a um nível geral:

• Strings serializáveis em JSON, booleanos, inteiros e floats — usados diretamente como predefinidos.
• Strings de data/hora — especificam como uma string na assinatura da função; o runtime analisa-a no datetime momento da invocação. Use o formato ISO 8601 (por exemplo, 2025-12-31T23:59:59Z) para análise fiável.
• Listas e dicionários — devem ser serializáveis em JSON. Prefira None na assinatura e atribua o valor padrão real dentro da função para evitar valores padrão mutáveis partilhados.
• Objetos ou arrays de objetos — podem ser mapeados para um pandas DataFrame ou Series. Requer fabric-user-data-functions versão 1.0.0 ou posterior.

Conceitos-chave do modelo de programação

As suas Funções de Dados de Utilizador utilizam o modelo de Programação Python de Funções de Dados de Utilizador para criar, executar, depurar e modificar funções individuais. O modelo de programação é fornecido pelo fabric-user-data-functions pacote, que está disponível publicamente no PyPI e pré-instalado nos itens das funções de dados do utilizador.

Quando crias a tua primeira função, o ficheiro de código inclui as instruções de importação obrigatórias:

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Pontos-chave sobre o modelo de programação:

• O pacote fabric-user-data-functions fornece o módulo fabric.functions, que deve importar como fn no seu código.
• A fn.UserDataFunctions() chamada cria o contexto de execução necessário para definir e executar funções dentro de um item de Funções de Dados de Utilizador.
• Outras bibliotecas, como logging, permitem-lhe escrever logs personalizados para depuração e monitorização.
• O modelo de programação em Python suporta valores de argumento padrão para parâmetros de função. Para a lista autoritativa de tipos e restrições suportados, veja Requisitos e limitações sintáticas.

Testa e publica as tuas funções

Agora que criaste várias funções (a função de exemplo manipulate_data e a tua função personalizada standardize_category ), podes testá-las e publicá-las em conjunto.

1. Enquanto estiver no modo Desenvolvimento , pode testar cada função usando a capacidade de Teste antes de publicar. Os testes permitem-te validar as alterações ao código sem as disponibilizar para invocação externa.

2. Quando estiver pronto para disponibilizar as suas funções, selecione Publicar para guardar as alterações e atualizar todas as suas funções. Publicar pode demorar alguns minutos.

3. Após a conclusão da publicação, todas as funções são atualizadas na lista do explorador de funções e os ícones do círculo são removidos. As suas funções estão agora prontas para serem:

   • Executar a partir do portal em modo apenas execução
   • Invocado de outro item do Fabric, como um pipeline, caderno ou regra do Activator
   • Chamado a partir de uma aplicação externa através do endpoint REST

Executa as tuas funções

Com todas as tuas funções criadas, testadas e publicadas, podes agora mudar para o modo apenas Run para as executar e ver os resultados.

1. Selecione o modo Executar apenas no seletor de modos no canto superior direito do portal.

   

2. Selecione o ícone Executar que aparece quando passa o cursor sobre uma função na lista do explorador de funções.

   

Executar a função de amostragem

1. No explorador de Funções, passe o rato sobre a manipulate_data função.

2. Selecione o botão Correr que aparece quando passa o rato sobre a função.

3. Um painel de execução abre no lado direito do ecrã.

4. No painel de execução, vê o nome do parâmetro data com o tipo list. Introduza o seguinte valor JSON na caixa de texto:

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

5. Seleciona o botão Executar no painel de execução (localizado ao lado de onde introduziste os dados JSON) para executar a função.

   

6. Veja os resultados e registos em Saída (lista) no painel de execução. A saída mostra os dados manipulados como um DataFrame pandas em formato JSON.

Executar a função personalizada

Agora tenta executar a tua função personalizada standardize_category .

1. No explorador de Funções, passe o rato sobre a standardize_category função.

2. Selecione o botão Correr que aparece quando passa o rato sobre a função.

3. Um painel de execução abre no lado direito do ecrã.

4. Forneça parâmetros de teste:

   • produtoNome: Laptop Computer
   • rawCategoria: tech

5. Selecione Executar e observe a saída, que deverá mostrar a categoria padronizada como "eletrónica" e incluir os metadados sobre a categorização.

Gerir funções

Depois de criar e executar as suas funções, pode renomeá-las ou eliminá-las conforme necessário. Todas as operações de gestão exigem que estejas em modo Desenvolvimento .

Renomear uma função

1. No modo de desenvolvimento, selecione no editor de código e atualize o nome da função. Por exemplo, renomeie hello_fabric para 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. Depois de alterar o nome, selecione Publicar para salvar essas alterações.

3. Assim que as alterações são publicadas, vê o novo nome da função no explorador de funções.

Eliminar uma função

Para eliminar uma função, selecione o código da função no editor de código e remova toda a secção do código. Publique as alterações para excluí-lo totalmente do item de funções de dados do usuário.

Por exemplo, para eliminar a função hello_fabric, remova o seguinte bloco de código:

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

Depois de remover o código, pode selecionar Publicar para salvar as alterações. Quando a publicação for concluída, você verá uma lista atualizada de funções disponíveis no explorador de funções.

Solução de problemas

Se encontrar problemas ao trabalhar com Funções de Dados de Utilizador:

• A função não publica - Verifica se há erros de sintaxe no teu código. Certifique-se de que todas as importações necessárias (fabric.functions) e a linha udf = fn.UserDataFunctions() estão presentes.
• Erros na nomeação dos parâmetros - Lembre-se que os nomes dos parâmetros devem usar camelCase (sem sublinhados). Revê os requisitos e limitações da sintaxe.
• Erros de importação de bibliotecas - Verifique se todas as bibliotecas necessárias foram adicionadas via Gestão de Bibliotecas e se a versão é compatível com Python 3.11.
• Função que não aparece no explorador de funções - Certifique-se de que publicou as suas alterações depois de adicionar ou modificar funções.
• Problemas de valores padrão - Se uma função falha em publicar ou as entradas não forem analisadas corretamente:
  • Use o formato ISO 8601 (por exemplo, 2025-12-31T23:59:59Z) para valores padrão data/hora para garantir uma análise fiável.
  • Não utilize padrões mutáveis para listas e dicionários. Use None na assinatura da função e atribua o padrão real dentro do corpo da função (por exemplo, items = items or []).
  • Garanta que todos os valores predefinidos são serializáveis em JSON. Conjuntos e tuplas não são suportados como valores padrão.
  • Verifica se os nomes dos parâmetros e os valores padrão correspondem ao esperado. Se a sua função usar os defaults do pandas DataFrame ou Series, certifique-se de que o pacote fabric-user-data-functions está na versão 1.0.0 ou posterior.

Para mais ajuda, consulte os limites e considerações do serviço Funções de Dados do Utilizador.

Conteúdo relacionado

Agora que criou o seu primeiro item de Funções de Dados de Utilizador, explore estes recursos para expandir as suas competências:

• Crie um item de funções de dados de utilizador Fabric no Visual Studio Code - Aprenda a desenvolver funções localmente com suporte completo ao IDE
• Saiba mais sobre o modelo de programação de funções de dados do utilizador - Aprofunde o SDK em Python e funcionalidades avançadas
• Invocar Funções de Dados de Utilizador a partir de uma aplicação Python - Chamar as suas funções a partir de aplicações externas através de APIs REST
• Gerir bibliotecas para Funções de Dados de Utilizador - Aprender técnicas avançadas de gestão de bibliotecas