Manipulando o caminho da fonte de dados

O mecanismo M identifica uma fonte de dados usando uma combinação de seu Tipo e Caminho. Quando uma fonte de dados é encontrada durante uma avaliação de consulta, o mecanismo M tenta encontrar credenciais correspondentes. Se nenhuma credencial for encontrada, o mecanismo retornará um erro especial que resultará em um prompt de credenciais no Power Query.

O valor Kind vem da definição Data Source Kind .

O valor Path é derivado dos parâmetros necessários da sua função de fonte de dados. Os parâmetros opcionais não são considerados no identificador do caminho da fonte de dados. Como resultado, todas as funções de fonte de dados associadas a um tipo de fonte de dados devem ter os mesmos parâmetros. Há um tratamento especial para funções que têm um único parâmetro do tipo Uri.Type. Vá para Funções com um parâmetro Uri para obter detalhes.

Você pode ver um exemplo de como as credenciais são armazenadas na caixa de diálogo Configurações da fonte de dados no Power BI Desktop. Nesta caixa de diálogo, o Kind é representado por um ícone e o valor Path é exibido como texto.

Nota

Se você alterar os parâmetros necessários da função de fonte de dados durante o desenvolvimento, as credenciais armazenadas anteriormente não funcionarão mais (porque os valores de caminho não correspondem mais). Você deve excluir todas as credenciais armazenadas sempre que alterar os parâmetros da função da fonte de dados. Se forem encontradas credenciais incompatíveis, poderá receber um erro em tempo de execução.

Formato do caminho da fonte de dados

O valor Path para uma fonte de dados é derivado dos parâmetros necessários da função de fonte de dados. Os parâmetros necessários podem ser excluídos do caminho adicionando DataSource.Path = false aos metadados da função. Para obter mais informações, vá para Excluindo parâmetros necessários do caminho da fonte de dados.

Por padrão, você pode ver o valor real da cadeia de caracteres na caixa de diálogo Configurações da fonte de dados no Power BI Desktop e no prompt de credenciais. Se a definição de Tipo de Fonte de Dados tiver incluído um Label valor, você verá o valor do rótulo.

Por exemplo, a função de fonte de dados no exemplo HelloWorldWithDocs tem a seguinte assinatura:

HelloWorldWithDocs.Contents = (message as text, optional count as number) as table => ...

A função tem um único parâmetro necessário (message) do tipo text, e é usada para calcular o caminho da fonte de dados. O parâmetro opcional (count) é ignorado. O caminho seria exibido da seguinte forma:

Pedido de credenciais

Interface do usuário de configurações da fonte de dados

Quando um valor Label é definido, o valor do caminho da fonte de dados não é mostrado:

Nota

Atualmente, recomendamos que você não inclua um Rótulo para sua fonte de dados se sua função tiver parâmetros necessários, pois os usuários não poderão distinguir entre as diferentes credenciais que inseriram. Esperamos melhorar isso no futuro (ou seja, permitir que os conectores de dados exibam seus próprios caminhos de fonte de dados personalizados).

Excluindo os parâmetros necessários do caminho da fonte de dados

Se desejar que um parâmetro de função seja necessário, mas não seja incluído como parte do caminho da fonte de dados, você poderá adicionar DataSource.Path = false metadados à documentação da função. Esta propriedade pode ser adicionada a um ou mais parâmetros para sua função. Esse campo remove o valor do caminho da fonte de dados (o que significa que ele não é mais passado para sua TestConnection função), portanto, ele só deve ser usado para parâmetros que não são necessários para identificar sua fonte de dados ou distinguir entre credenciais de usuário.

Por exemplo, o conector no exemplo HelloWorldWithDocs exigiria credenciais diferentes para valores diferentes message . Adicionar DataSource.Path = false ao message parâmetro o remove do cálculo do caminho da fonte de dados, tornando efetivamente o conector um "singleton". Todas as chamadas para HelloWorldWithDocs.Contents são tratadas como a mesma fonte de dados e o usuário só fornece credenciais uma vez.

HelloWorldType = type function (
    message as (type text meta [
        DataSource.Path = false,
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

Funções com um parâmetro Uri

Como as fontes de dados com um identificador baseado em Uri são tão comuns, há um tratamento especial na interface do usuário do Power Query ao lidar com caminhos de fonte de dados baseados em Uri. Quando uma fonte de dados baseada em Uri é encontrada, a caixa de diálogo de credenciais fornece uma lista suspensa, que permite ao usuário selecionar o caminho base em vez do caminho completo (e todos os caminhos intermediários).

Como Uri.Type é um tipo atribuído em vez de um tipo primitivo na linguagem M, você precisará usar a função Value.ReplaceType para indicar que seu parâmetro de texto deve ser tratado como um Uri.

shared GithubSample.Contents = Value.ReplaceType(Github.Contents, type function (url as Uri.type) as any);