Conectar-se a itens do Fabric a partir do item de funções de dados do Fabric User

As funções de dados do utilizador Fabric fornecem conexões com fontes de dados e itens suportados pelo Fabric, usando o recurso Gerenciar conexões no portal do Fabric. Esse recurso permite que você se conecte às fontes de dados do Fabric sem precisar criar cadeias de conexão ou gerenciar credenciais de acesso. Para itens de malha que não são uma fonte de dados, você pode se conectar com segurança a esses itens dentro de uma função.

Neste artigo, você aprenderá a:

• Crie uma nova conexão para o item de funções de dados do usuário.
• Use sua nova conexão em seu código de função.
• Modifique ou exclua sua conexão de dados.

Itens suportados nas funções de dados do usuário do Fabric

Os seguintes itens são atualmente suportados para funções de dados do Fabric User:

• Bancos de dados SQL de malha para operações de leitura/gravação
• Armazéns de malha para operações de leitura/gravação
• Fabric lakehouses para operações de leitura/gravação para ficheiros Lakehouse e para operações de apenas leitura para o SQL Endpoint.
• Bases de dados espelhadas em rede para operações somente leitura
• Fabric Variable library para definir configurações usando variáveis. Mais informações.

Criar uma nova conexão de dados para o item de funções de dados do usuário

Todas as conexões de dados adicionadas estão associadas ao item de funções de dados do usuário e podem ser referenciadas no código de qualquer uma das suas funções. Para seguir este guia, você precisa de um item de funções de dados do Fabric existente e uma fonte de dados do Fabric existente.

1. Aceda à funcionalidade Gerir ligações a partir do portal Funções

No modo de desenvolvimento, localize e selecione Gerenciar conexões na faixa de opções do editor do portal Funções.

O painel aberto contém todas as conexões de dados que você criou. Selecione Adicionar conexão de dados para criar uma nova conexão.

2. Selecione sua conexão de dados do catálogo OneLake

Quando você seleciona Adicionar conexão de dados, o catálogo do OneLake é aberto com uma lista de todas as fontes de dados às quais sua conta de usuário tem acesso. A lista é filtrada para incluir apenas fontes de dados suportadas, algumas das quais podem estar em outros espaços de trabalho.

Escolha sua fonte de dados e, em seguida, selecione Conectar.

Observação

Se não conseguir encontrar a fonte de dados que está procurando, verifique se você tem as permissões certas para se conectar a ela. Como alternativa, verifique se você está usando uma fonte de dados compatível, conforme listado no início deste artigo.

Uma vez criada, a nova conexão com a fonte de dados selecionada é mostrada no painel lateral da guia Conexões . Quando você vir a conexão, anote o campo Alias que foi gerado para ela. Você precisa deste alias para referenciar a conexão a partir de qualquer função no item de funções de dados dos usuários.

3. Use seu alias de conexão em seu código de função

Depois de voltares ao editor do portal, precisas de adicionar ao teu código o alias da conexão que criaste no separador Manage Connections. Esse alias é criado automaticamente com base no nome do item de malha ao qual você está se conectando.

Nesse caso, usaremos um exemplo de código chamado "Ler dados de uma tabela no Banco de dados SQL". Você pode encontrar este exemplo clicando na guia Editar, depois clicando no botão "Inserir exemplo" e navegando até "Banco de dados SQL".

Este é o código de exemplo que foi inserido:

@udf.connection(argName="sqlDB",alias="<alias for sql database>")
@udf.function()
def read_from_sql_db(sqlDB: 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);"

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

    query.capitalize()

    # Execute the query
    cursor.execute(query)

    # Fetch all results
    results = []
    for row in cursor.fetchall():
        results.append(row)

    # Close the connection
    cursor.close()
    connection.close()
        
    return results

Observação

Embora este exemplo se conecte a um Banco de Dados SQL, ele não precisa de um esquema ou dados em seu banco de dados para ser executado.

Para usar a conexão de dados que você criou, modifique a seguinte linha neste exemplo: @udf.connection(argName="sqlDB",alias="<alias for sql database>") substituindo o valor do alias pelo que você obteve no Manage Connections menu. O código a seguir mostra este exemplo com o valor ContosoSalesDat:

@udf.connection(argName="sqlDB",alias="ContosoSalesDat")
@udf.function()
def read_from_sql_db(sqlDB: fn.FabricSqlConnection)-> list:
    [...]

Depois de modificar o código, você pode testar suas alterações usando o recurso de teste no modo de desenvolvimento. Quando estiver pronto, você pode publicar sua função usando o botão Publicar na barra de ferramentas. Esta operação pode demorar alguns minutos.

Quando a publicação estiver concluída, você pode executar sua função passando o mouse sobre seu nome na lista do Explorador de Funções e clicando no botão "Executar" no painel lateral. O painel inferior "Saída" mostra o resultado da execução da função.

E isso é tudo o que necessita para se conectar a uma fonte de dados a partir das suas funções de dados de utilizador do Fabric.

Obter variáveis das bibliotecas de variáveis do Fabric

Uma Fabric Variable Library no Microsoft Fabric é um repositório centralizado para gerir variáveis que podem ser usadas em diferentes itens num espaço de trabalho. Ele permite que os desenvolvedores personalizem e compartilhem configurações de itens de forma eficiente. Siga estas etapas para usar bibliotecas de variáveis em suas funções:

1. Adicione uma conexão a uma biblioteca de variáveis usando Gerenciar conexões e obtenha o alias para o item de biblioteca variável.
2. Adicione um decorador de conexão para o item de biblioteca variável. Por exemplo, @udf.connection(argName="varLib", alias="<My Variable Library Alias>") e substitua o alias para a conexão recém-adicionada para o item de biblioteca variável.
3. Na definição da função, inclua um argumento com o tipo fn.FabricVariablesClient. Este cliente fornece métodos que você precisa para trabalhar com o item de biblioteca de variáveis.
4. Use getVariables() o método para obter todas as variáveis da biblioteca de variáveis.
5. Para ler os valores das variáveis, use ou ["variable-name"] ou .get("variable-name").

Exemplo Neste exemplo, simulamos um cenário de configuração para um ambiente de produção e desenvolvimento. Esta função define um caminho de armazenamento dependendo do ambiente selecionado usando um valor recuperado da Biblioteca de Variáveis. A Biblioteca de Variáveis contém uma variável chamada ENV onde os usuários podem definir um valor de dev ou prod.

@udf.connection(argName="varLib", alias="<My Variable Library Alias>")
@udf.function()
def get_storage_path(dataset: str, varLib: fn.FabricVariablesClient) -> str:
    """
    Description: Determine storage path for a dataset based on environment configuration from Variable Library.
    
    Args:
        dataset_name (str): Name of the dataset to store.
        varLib (fn.FabricVariablesClient): Fabric Variable Library connection.
    
    Returns:
        str: Full storage path for the dataset.
    """
    # Retrieve variables from Variable Library
    variables = varLib.getVariables()
    
    # Get environment and base paths
    env = variables.get("ENV")    
    dev_path = variables.get("DEV_FILE_PATH")
    prod_path = variables.get("PROD_FILE_PATH")
    
    # Apply environment-specific logic
    if env.lower() == "dev":
        return f"{dev_path}{dataset}/"
    elif env.lower() == "prod":
        return f"{prod_path}{dataset}/"
    else:
        return f"incorrect settings define for ENV variable"

Conteúdo relacionado

• Criar um item de funções de dados do usuário do Fabric de dentro do Fabric ou usar a extensão do Visual Studio Code
• Saiba mais sobre o modelo de programação de funções de dados do usuário