Compartilhar via

Tutorial: Criar um fluxo de tarefas translytical (prévia)

Neste tutorial de ponta a ponta, você criará um exemplo de fluxo de tarefas transanalítico que escreve de volta para um Banco de Dados SQL no Fabric. Para ajudar a ilustrar a experiência de aprimoramento de ponta a ponta, nos concentramos em um fluxo de tarefas integradas para um cenário de anotação de dados.

Neste tutorial, você aprenderá como:

  • Crie um banco de dados SQL no Fabric.
  • Configure uma função de dados do usuário que grava de volta em um banco de dados SQL.
  • Integre uma função de dados do usuário a um relatório do Power BI.

Se você não tiver uma capacidade existente do Fabric, inicie uma avaliação do Fabric.

Observação

O recurso de fluxo de tarefas translytical está atualmente em versão prévia pública.

Pré-requisitos

Visão geral

A criação de um fluxo de tarefas translítico requer três tarefas para habilitar seus cenários automatizados:

  • Armazenar dados

    Comece com uma fonte de dados existente do Fabric. Neste tutorial, usamos um banco de dados SQL com dados de exemplo.

  • Desenvolver dados

    Escreva uma função de dados de usuário do Fabric que é chamada de um relatório do Power BI. Essa função pode realizar qualquer número de ações, desde editar a fonte de dados do relatório até enviar uma notificação até criar um item de trabalho em um pipeline de aprovações. Neste tutorial, criamos uma função de dados do usuário que usa uma nova descrição do produto e a grava no banco de dados SQL.

  • Visualizar dados

    Crie um relatório do Power BI que exibe os dados de origem e elementos interativos que chamam a função de dados. Neste tutorial, usamos uma segmentação de texto para coletar a descrição do produto do usuário e enviá-la para a função de dados do usuário. Em seguida, o relatório é atualizado para mostrar a tabela atualizada.

Criar um Banco de Dados SQL

Esse cenário usa o conjunto de dados AdventureWorksLT de exemplo no banco de dados SQL.

  1. Siga as etapas em Criar um banco de dados SQL no portal do Fabric.

    Anote o nome que você dá ao banco de dados SQL. Você usará esse valor mais adiante no tutorial.

  2. Depois de criar o banco de dados, escolha a opção De exemplo de dados para carregar os dados de exemplo AdventureWorksLT em seu banco de dados vazio.

Criar uma função de dados do usuário

Crie uma função de dados do usuário em um workspace.

  1. Navegue até o workspace de sua escolha no Power BI ou Fabric.

  2. Selecione Novo item.

  3. Selecione Funções de dados do usuário (versão prévia) no grupo Desenvolver dados .

    Uma captura de tela que mostra o bloco de funções de dados do usuário no menu novo item.

  4. Forneça um nome para a nova função de dados do usuário, por exemplo , sqlwriteback e selecione Criar.

    Anote o nome usado e o nome do workspace. Você usará esses dois valores mais adiante no tutorial.

  5. Selecione Nova função.

Conectar-se ao banco de dados SQL

Conecte a função de dados do usuário ao banco de dados SQL criado anteriormente. Verifique se você tem permissões de acesso para o banco de dados SQL antes de continuar.

  1. Selecione Gerenciar conexões na página da nova função de dados do usuário.

    Captura de tela que mostra a seleção de

  2. Selecione Adicionar conexão de dados.

  3. Selecione o banco de dados SQL AdventureWorksLT criado anteriormente e selecione Conectar.

  4. Quando a conexão é criada, um alias é criado automaticamente para a conexão. Anote o valor do Alias a ser usado posteriormente no tutorial.

    Captura de tela que mostra onde encontrar o alias gerado automaticamente para a conexão de dados.

  5. Feche a página Conexões para retornar à função de dados do usuário.

Adicionar código de função

Adicione código à função de dados do usuário para que ele grave dados na tabela [SalesLT].[ProductDescription] no exemplo AdventureWorksLT do banco de dados SQL.

As funções de dados do usuário usam pyodbc por padrão para conexões SQL e recomendamos essa biblioteca para esse cenário.

Para conectar uma função de dados do usuário a um botão do Power BI, a função deve retornar uma cadeia de caracteres.

  1. Substitua o código padrão na função de dados do usuário pelo seguinte exemplo:

    import fabric.functions as fn
import uuid

udf = fn.UserDataFunctions()

@udf.connection(argName="sqlDB",alias="<REPLACE_WITH_CONNECTION_ALIAS>") 
@udf.function() 

# Take a product description and product model ID as input parameters and write them back to the SQL database
# Users will provide these parameters in the PowerBI report
def write_one_to_sql_db(sqlDB: fn.FabricSqlConnection, productDescription: str, productModelId:int) -> str: 

    # Error handling to ensure product description doesn't go above 200 characters
    if(len(productDescription) > 200):
        raise fn.UserThrownError("Descriptions have a 200 character limit. Please shorten your description.", {"Description:": productDescription})

    # Establish a connection to the SQL database  
    connection = sqlDB.connect() 
    cursor = connection.cursor() 

    # Insert data into the ProductDescription table  
    insert_description_query = "INSERT INTO [SalesLT].[ProductDescription] (Description) OUTPUT INSERTED.ProductDescriptionID VALUES (?)" 
    cursor.execute(insert_description_query, productDescription) 

    # Get the result from the previous query 
    results = cursor.fetchall() 

    # In real-world cases, call an API to retrieve the cultureId
    # For this example, generate a random Id instead
    cultureId = str(uuid.uuid4()) 

    # Insert data into the ProductModelProductDescription table 
    insert_model_description_query = "INSERT INTO [SalesLT].[ProductModelProductDescription] (ProductModelID, ProductDescriptionID, Culture) VALUES (?, ?, ?);" 
    cursor.execute(insert_model_description_query, (productModelId, results[0][0], cultureId[:6])) 

    # Commit the transaction 
    connection.commit() 
    cursor.close() 
    connection.close()  

    return "Product description was added"

  2. Localize a seguinte linha de código no exemplo:

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

  3. Substitua o marcador de alias pelo valor do alias da seção anterior.

    Você pode abrir a página Gerenciar conexões novamente para exibir o alias de conexão.

Testar o código de exemplo

Use as etapas nesta seção se desejar testar o código de exemplo até agora.

  1. Selecione Publicar.

  2. Depois que a função for publicada, passe o mouse sobre a função write_one_to_sql_db no menu do Gerenciador de Funções e selecione o ícone Executar .

  3. Na página Executar , forneça dados de exemplo para os dois parâmetros necessários:

    • productDescription: cadeia de caracteres
    • productModelId: inteiro entre 1 e 127

  4. Selecione Executar.

  5. Examine a saída da função e os logs gerados.

  6. Feche a página Executar quando terminar de testar.

Se você receber erros ao executar o código de exemplo, verifique se sua conta tem permissões de acesso ao banco de dados.

Conceder permissões de usuário (opcional)

Se outros usuários interagirem com o relatório do Power BI que chama essa função, conceda a eles permissões executar funções .

  1. Na página de funções, selecione Compartilhar.

  2. Selecione a primeira caixa da janela Criar e enviar link pop-up.

  3. Selecione Executar Funções e Exibir Logs de Funções na lista de permissões adicionais e selecione Aplicar.

    Captura de tela que mostra a adição das permissões

  4. Na caixa Inserir um nome ou endereço de email , forneça aos usuários ou grupos que você deseja ter permissões para essa função.

  5. Selecione Enviar.

Criar um relatório do Power BI

Nesta seção, você criará um relatório do Power BI que extrai dados do banco de dados SQL criado na seção anterior.

Conectar-se ao banco de dados SQL

Conecte-se ao banco de dados SQL como a fonte de dados do relatório.

  1. No Power BI Desktop, crie um novo relatório.

  2. Selecione Catálogo do OneLake>banco de dados SQL.

    Captura de tela que mostra a seleção do banco de dados SQL no catálogo do OneLake.

  3. Na janela do catálogo do OneLake , selecione o banco de dados que você criou na seção anterior. Por exemplo, AdventureWorksLT. Em seguida, selecione Conectar.

  4. Siga todas as instruções para autenticar no banco de dados.

  5. Depois que você se conectar com êxito ao banco de dados, a janela Navegador será aberta. Selecione as tabelas a seguir e, em seguida, selecione Carregar:

    • SalesLT.ProductDescription
    • SalesLT.ProductModel
    • SalesLT.ProductModelProductDescription

    Captura de tela que mostra o carregamento de três tabelas do conjunto de dados de exemplo no relatório do Power BI.

  6. Quando solicitado, escolha DirectQuery como o modo de conexão e selecione Ok.

    O modo DirectQuery é uma conexão dinâmica que permite que o relatório atualize os dados e reflita as modificações de dados. Para obter mais informações, consulte DirectQuery no Power BI.

Criar o relatório do Power BI

Nesta seção, crie visuais com os dados que você carregou no relatório do Power BI.

  1. No menu Dados , selecione as seguintes colunas:

    • SalesLT.ProductModel > Name
    • SalesLT.ProductModelProductDescription > ProductModelID

    Captura de tela que mostra a seleção das colunas 'Name' e 'ProductModelID' a serem adicionadas ao relatório.

    Uma tabela de duas colunas aparece na janela do relatório.

    Captura de tela que mostra o relatório do Power BI com uma tabela adicionada a ela.

  2. No menu Visualizações , selecione o ícone de segmentação de texto .

    Captura de tela que mostra a seleção da visualização

    Dica

    Se você não vir o ícone de segmentação de texto, verifique se o recurso de visualização da segmentação de texto está habilitado no Power BI Desktop. Para obter mais informações, consulte os recursos de visualização necessários.

    Uma visualização de segmentação de texto aparece na janela do relatório.

    Captura de tela que mostra o relatório do Power BI com uma segmentação de texto adicionada a ele.

  3. Selecione a segmentação de texto e use as opções Formato visual>Geral>Título para dar à segmentação de texto o seguinte título: Write a new product description.

  4. Na barra de tarefas, selecione o menu Inserir e adicione um botão Em branco ao relatório. Arraste o botão sob o fatiador de texto.

    Captura de tela que mostra o relatório do Power BI com um botão adicionado a ele.

  5. Selecione o botão e expanda as opções de ação no painel de botão Formatar . Defina o botão de opção Ação para Ativado.

  6. Forneça os seguintes valores para o botão:

    Parâmetro Valor
    Tipo Selecionar função de Dados
    Área de trabalho Selecione o espaço de trabalho que contém a função de dados de usuário que você criou na seção anterior.
    Conjunto de funções Selecione o conjunto de funções que contém sua função de dados. Por exemplo, sqlwriteback.
    Função de dados Selecione sua função de dados. Por exemplo, write_one_to_sql_db.

    Dica

    Se você não vir a opção função de dados, verifique se o recurso de visualização de fluxos de tarefa Translytical está habilitado no Power BI Desktop.

    Se você vir a opção função Dados , mas não vir a função de dados do usuário, verifique se a função de dados retorna uma cadeia de caracteres.

  7. Depois de selecionar sua função de dados, mais parâmetros aparecerão para representar os parâmetros que a função usa. Forneça os seguintes valores:

    Parâmetro Valor
    productDescription Selecione o fatiador de texto do relatório, Escreva uma nova descrição do produto.
    productModelId Selecione o botão formatação condicional (fx). Uma nova janela é aberta.

    Para o parâmetro estilo de formato, mantenha o valor de campo padrão.

    Para o campo Em que devemos basear isso? parâmetro, selecione Todos os dados>SalesLT.ProductModel>ProductModelID.
    Resumo Selecione Máximo.

  8. Selecione OK para concluir a configuração de ação. Os detalhes da ação devem ser semelhantes ao seguinte exemplo:

    Captura de tela que mostra os detalhes da configuração da ação final.

  9. Selecione o botão e expanda as opções Estilo no painel de botão Formatar . Ative o botão de opção Textoe rotule o botão Enter.

  10. Nas opções de Estilo, altere a opção Aplicar configurações em para Carregar.

    O estado de carregamento é um estado exclusivo disponível para botões de função de dados que você pode usar para definir opções de estilo que aparecem enquanto a função de dados está em execução.

    Captura de tela que mostra a seleção do estado de

  11. Expanda o menu Texto e substitua o valor do texto do botão por Submitting.

  12. Expanda o menu Ícone .

    Por padrão, um botão de função de dados tem um tipo de ícone Spinner para o estado de carregamento.

  13. Ajuste o estilo do ícone com as seguintes alterações:

    Parâmetro Valor
    Margem Altere o preenchimento esquerdo para 20 px.
    Tamanho do ícone Substitua o valor automático padrão por 20.

  14. No painel Visualizações , selecione o ícone Tabela para inserir uma nova tabela.

  15. No painel Dados , selecione as seguintes colunas a serem adicionadas à tabela:

    • SalesLT.ProductModel > Name
    • SalesLT.ProductDescription > Description
    • SalesLT.ProductDescription > ModifiedDate

    Captura de tela que mostra o relatório do Power BI com uma segunda tabela adicionada a ele.

Modificações de relatório opcionais

Assim como acontece com qualquer relatório do Power BI, há várias maneiras de personalizar a aparência e melhorar a funcionalidade deste relatório. Considere algumas destas opções:

  • Adicione títulos às duas tabelas. Por exemplo, selecione um produto e umadescrição do produto.
  • Defina o cortador de texto para limpar automaticamente após enviar uma nova descrição do produto. Para fazer isso, selecione o botão que dispara a função de dados do usuário. No menu Ação do botão de Formatar>, defina o alternador Limpar Automático como Ligado.
  • Recusar a autorefresh para o relatório depois de disparar a função de dados do usuário. Nesse cenário, é útil atualizar os dados e ver a nova descrição do produto aparecer na tabela. Em outros cenários, talvez você não precise ou queira atualizar o relatório. Para desativar essa configuração, selecione o botão que dispara a função de dados do usuário. No menuAção do botão> Formatar, defina a opção Atualizar o relatório após uma alternância de resultado bem-sucedida para Desativada.

Execute o fluxo de tarefas translytical

Você pode testar a funcionalidade do fluxo de tarefas translíticas no Power BI Desktop. Mas se você quiser ver a experiência mais precisa do usuário final, publique o relatório no serviço do Power BI e teste-o na Web.

Publicar seu relatório

Você criou seu relatório no Power BI Desktop. Nesta seção, você publicará o relatório para que os usuários possam interagir com ele no portal da Web.

  1. No menu Barra de ferramentas Página Inicial , selecione Publicar.

  2. Selecione o workspace do Power BI no qual deseja publicar este relatório e selecione Selecionar.

  3. Depois que o relatório terminar de publicar, selecione o link para Abrir <REPORT_NAME.pbix> no Power BI.

    Dica

    Ao abrir o relatório no portal da Web do Power BI, você poderá ver um erro que diz que a fonte de dados não tem credenciais e não pode ser acessada. Para resolver esse erro, use as seguintes etapas:

    1. Abra o modelo semântico do relatório e navegue atéAs Configuraçõesde Arquivo>.
    2. Expanda a configuração Credenciais da fonte de dados se ainda não estiver.
    3. Selecione Editar credenciais.
    4. Escolha seu método de Autenticação no menu suspenso. Por exemplo, o Basic usa um nome de usuário e uma senha, e o OAuth2 habilita o logon único com sua conta atual.
    5. Forneça as informações necessárias, se houver, selecione Entrar.

Agora, você tem um fluxo de tarefas translítico em um relatório do Power BI que está disponível no serviço do Power BI.

Execute o fluxo de tarefas translytical.

Nesta seção, você interage com seu relatório no portal da Web do Power BI para testar o fluxo de tarefas translyticais que você criou.

Somente usuários autorizados a disparar funções de dados podem usar esse recurso. Todos os usuários não autorizados recebem uma resposta errada .

  1. Abra seu relatório no Power BI.
  2. Selecione um produto na tabela do produto que lista o nome e a ID. Essa seleção passa o contexto para a segmentação de texto para qual produto você deseja atualizar. Você também vê que a tabela de descrição do produto filtra para mostrar todas as descrições atuais do produto selecionado.
  3. Escreva uma nova descrição do produto na caixa de texto de entrada.
  4. Selecione o ícone de seta ou use a tecla Tab para enviar a entrada. Depois que um produto é selecionado e uma descrição é fornecida, você vê que o botão alterna para um estado habilitado.
  5. Selecione o botão para executar a função de dados do usuário.

Se o fluxo de tarefas translítico funcionar corretamente, você receberá uma mensagem informando que a ação em seu relatório foi enviada com êxito. A tabela de descrição do produto é atualizada para mostrar a nova descrição.

Se algo der errado com o fluxo de tarefas translítico, você receberá uma mensagem informando que algo deu errado. Selecione Exibir detalhes para obter mais informações sobre o motivo da falha. Alguns motivos comuns para uma execução de função malsucedida incluem:

  • Validação de dados: os valores de entrada não atendem às regras de validação de dados definidas na função de dados do usuário.
  • Erro de tempo limite: uma função ou processo leva mais tempo do que o tempo permitido para ser concluído.
  • Configuração inadequada: erros ao configurar os elementos do relatório, geralmente o botão, podem causar falha no fluxo de tarefas ou resultados inesperados do produto.
  • Usuário não autorizado: o usuário não tem permissões para disparar a função de dados.

Próximas etapas