Conecte-se aos itens do Fabric a partir do item de funções de dados do usuário no Fabric.

As funções de dados do Fabric User fornecem conexões para fontes e itens de dados suportados na malha usando o recurso Gerenciar conexões no portal 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 a sua nova conexão no código da função.
• Modifique ou exclua a sua conexão de dados.

Itens com suporte nas funções de dados do Usuário do Fabric

Atualmente, há suporte para os seguintes itens para funções de dados do Usuário do Fabric:

• Bancos de dados SQL do Fabric 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 de arquivos Lakehouse e para operações de leitura somente do SQL Endpoint.
• Bancos de dados espelhados para operações somente leitura
• Biblioteca Fabric Variable para definir configurações como variáveis. Saiba mais.

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 de suas funções. Para seguir este guia, você precisa de um item das Funções de dados do usuário do Fabric existente e uma fonte de dados existente do Fabric.

1. Acessar o recurso Gerenciar conexões no portal do Functions

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

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

2. Selecionar a sua conexão de dados no catálogo do 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 com suporte, algumas das quais podem estar em outros workspaces.

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

Observação

Se você não conseguir encontrar a fonte de dados que está procurando, certifique-se de que você possua as permissões certas para se conectar a ela. Como alternativa, certifique-se de que você esteja usando uma fonte de dados com suporte, conforme listado no início deste artigo.

Depois de criada, a nova conexão com a fonte de dados selecionada é mostrada no painel lateral na guia Conexões. Quando você vir a conexão, anote o campo Alias que foi gerado para ela. Você precisa desse alias para fazer referência à conexão de qualquer função no item de funções de dados do usuário.

3. Usar o alias de conexão no código da função

Depois de voltar ao editor do portal, você precisará adicionar o alias da conexão criada na guia Manage Connections ao seu código. Esse alias é criado automaticamente com base no nome do item Fabric ao qual você está conectando.

Nesse caso, usaremos um exemplo de código chamado "Ler dados de uma tabela no Banco de Dados SQL". Você pode encontrar esse exemplo clicando na guia Editar, 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 que você obteve no menu Manage Connections. 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 a funcionalidade De teste no modo Desenvolver. Quando estiver pronto, você poderá publicar sua função usando o botão Publicar na barra de ferramentas. Essa operação poderá levar alguns minutos.

Depois que a publicação for concluída, você poderá executar a sua função focalizando o seu nome na lista do Gerenciador 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 você precisa para se conectar a uma fonte de dados das Funções de dados do usuário do Fabric.

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

Uma Biblioteca de Variáveis do Fabric no Microsoft Fabric é um repositório centralizado para gerenciar variáveis que podem ser usadas em diferentes itens em um workspace. Ele permite que os desenvolvedores personalizem e compartilhem configurações de itens com eficiência. 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 de variáveis.
2. Adicione um decorador de conexão ao item da biblioteca de variáveis. 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 de função, inclua um argumento com o tipo fn.FabricVariablesClient. Esse cliente fornece métodos necessários 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 ["variable-name"] ou .get("variable-name").

Exemplo Neste exemplo, simulamos um cenário de configuração para um ambiente de produção e de desenvolvimento. Essa 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 das Funções de dados do Usuário do Fabric dentro do Fabric ou usar a extensão do Visual Studio Code
• Saiba mais sobre o modelo de programação das funções de dados de usuário