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

Neste guia, criaremos um novo item Funções de Dados do Usuário e escreveremos novas funções nele. Cada item Funções de Dados do Usuário contém código que define uma ou várias funções que você pode executar individualmente.

Especificamente, você aprende a:

• Crie um item de funções de dados do usuário.
• Escreva uma nova função.
• Gerencie funções.
• Execute a sua função.

Pré-requisitos

• Uma capacidade do Microsoft Fabric em uma das regiões suportadas. Se você não tiver uma capacidade de malha, poderá criar uma capacidade de avaliação gratuitamente.
• Um espaço de trabalho de malha vinculado a essa capacidade

Criar um novo item de Funções de Dados de Utilizador do Fabric

1. Seleciona o teu espaço de trabalho, e depois clica em + Novo item.
2. Selecione o tipo de item como Todos os itens. Procure e selecione funções de dados do utilizador.

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

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

2. No painel que se abre, procure user data functions, e em seguida, selecione o mosaico.

   

3. Forneça um Nome para o item de funções de dados do utilizador.

4. Selecione Nova função para criar um modelo de função hello_fabric Python. O explorador de funções mostra todas as funções que estão publicadas e prontas para serem invocadas.

   

5. Depois que a hello_fabric função for publicada, você poderá executá-la a partir da lista de funções no explorador de funções.

   

Adicionar uma nova função a partir do exemplo

Este é um exemplo de como adicionar uma nova função a partir do menu Insert sample. Neste caso, iremos adicionar uma função chamada Manipular dados com a biblioteca pandas que tem a biblioteca pandas como requisito. Siga as etapas para adicionar esta função de exemplo:

1. Certifique-se de que está no modo de Desenvolvimento. Selecione Gestão de Bibliotecas para adicionar as bibliotecas que a sua função requer.

   

   Observação

   fabric_user_data_functions biblioteca é adicionada 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.

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

   

3. Selecione Inserir amostra e selecione Manipular dados com a biblioteca pandas. Esta ação irá inserir código de exemplo na parte inferior do seu código, após as outras funções.

   

4. Depois que o exemplo é inserido no editor, você o testa usando o recurso Test no modo Develop.

5. Quando estiver pronto, você pode selecionar Publicar para salvar suas alterações e atualizar suas funções. A publicação pode demorar alguns minutos.

   

6. Depois que a publicação for concluída, você verá a nova função na lista Explorador de funções. Essa função agora está pronta para ser executada a partir do portal, ou invocada a partir de outro aplicativo ou item do Fabric, como um pipeline.

   

Execute a sua função

1. Para executar sua função, primeiro você precisa alternar para o modo Executar somente clicando no seletor de modo.

   

2. Selecione o ícone Executar que aparece quando o utilizador passa o mouse sobre uma função na lista do Explorador de Funções.

   

3. Passe os parâmetros necessários apresentados como um formulário no explorador de funções. Neste caso, vamos executar a função manipulate_data que requer uma string JSON como parâmetro.

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

4. Selecione Executar para executar a função.

   

5. Você pode ver os logs ao vivo e a saída para a função para validar se ela foi executada com êxito. Como alternativa, você verá uma mensagem de erro e logs da sua chamada de função.

Escrever uma nova função

Toda função executável começa com um decorador de @udf.function() antes da definição da função. Leia mais sobre o nosso modelo de Programação em Python. Para escrever uma nova função, use o decorador @udf.function() no início para declará-la como uma função executável. Aqui está um exemplo de função:

# This sample allows you to pass a credit card number as an integer and mask it, leaving the last 4 digits. 

@udf.function()
def maskCreditCard(cardNumber: int)-> str:
    # Convert the card number to a string
    cardNumberStr = str(cardNumber)
    
    # Check if the card number is valid
    if not cardNumberStr.isdigit() or not (13 <= len(cardNumberStr) <= 19):
        raise ValueError("Invalid credit card number")
    
    # Mask all but the last four digits
    maskedNumber = '*' * (len(cardNumberStr) - 4) + cardNumberStr[-4:]
    
    return str(maskedNumber)

Quando a função estiver pronta, publique a função para executá-la.

Conceitos-chave do modelo de programação

Suas Funções de Dados do Utilizador usam o modelo de programação Python de Funções de Dados do Utilizador para criar, executar, depurar e modificar funções individuais. Esta é uma biblioteca de primeira parte que fornece a funcionalidade necessária para invocar suas funções no Fabric e aproveitar todas as integrações.

Depois de criar sua primeira função, as primeiras linhas do código conterão as instruções de importação com as bibliotecas necessárias para executar seu modelo.

import datetime
import fabric.functions as fn
import logging

udf = fn.UserDataFunctions()

Observação

A instrução import que contém a fabric.functions biblioteca e a linha que contém essa instrução udf = fn.UserDataFunctions() são necessárias para executar suas funções corretamente. As suas funções não funcionarão corretamente se estas linhas estiverem em falta.

• Para criar, executar e gerir funções, é necessário o SDK fabric.functions e algumas outras bibliotecas importantes, como logging, que permitem a gravação de logs personalizados.
• udf=fn.UserDataFunctions() é a construção para definir funções dentro de um item de funções de dados do usuário.

Gerenciar funções de dados

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. Depois que as alterações forem publicadas, você poderá exibir o novo nome da função no explorador de funções.

Eliminar uma função

Para excluir uma função, selecione o código da função no editor de código e remova toda a seção de 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.

Próximos passos

• Criar um item de funções de dados do utilizador do Fabric no Visual Studio Code
• Saiba mais sobre o modelo de programação de funções de dados do usuário