Tratamento de caminho de fonte de dados

O mecanismo da 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 do Tipo de Fonte de Dados.

O valor Path é derivado dos parâmetros necessários da função da fonte de dados. Parâmetros opcionais não são levados em conta no identificador do caminho da fonte de dados. Assim, todas as funções da fonte de dados associadas a um tipo de fonte de dados devem ter os mesmos parâmetros. Há tratamento especial para funções que têm um único parâmetro do tipo Uri.Type. Acesse 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. Nessa caixa de diálogo, o Tipo é representado por um ícone e o valor Caminho é exibido como texto.

Observação

Se você alterar os parâmetros necessários da sua função da fonte de dados durante o desenvolvimento, as credenciais armazenadas anteriormente deixarão de funcionar (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, você poderá receber um erro em runtime.

Formato do caminho da fonte de dados

O valor Path de uma fonte de dados é derivado dos parâmetros necessários da função da 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, acesse Excluindo parâmetros necessários do caminho da sua 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 do Tipo de Fonte de Dados tiver incluído um valor Label, então você verá o valor do rótulo.

Por exemplo, a função da 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 é usado para calcular o caminho da fonte de dados. O parâmetro opcional (count) é ignorado. O caminho seria exibido da seguinte maneira:

Solicitação de credenciais

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

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

Observação

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 inseridas. Esperamos melhorar isso no futuro (ou seja, permitir que os conectores de dados exibam seus próprios caminhos de fonte de dados personalizados).

Exclusão de parâmetros necessários do caminho da fonte de dados

Se você quiser que um parâmetro de função seja obrigatório, mas que não seja incluído como parte do caminho da fonte de dados, poderá adicionar DataSource.Path = false aos metadados da função documentation. Essa propriedade pode ser adicionada a um ou mais parâmetros em 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 função TestConnection), portanto, ele deve ser usado apenas para parâmetros que não são necessários para identificar sua fonte de dados ou distinguir entre as credenciais do usuário.

Por exemplo, o conector no exemplo HelloWorldWithDocs exigiria credenciais diferentes para valores diferentes de message. Adicionar DataSource.Path = false ao parâmetro message o removeria 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 fornece credenciais apenas 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 de 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).

Assim 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 o 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);