Compartilhar via

Manipulando a navegação

Tabelas de navegação (ou nav tables) são uma parte central para proporcionar uma experiência amigável ao usuário do seu conector. A experiência do Power Query os exibe ao usuário depois que ele inseriu todos os parâmetros necessários para sua função de fonte de dados e se autenticou com a fonte de dados.

A tabela de navegação TripPin.

Nos bastidores, uma tabela de navegação é apenas um valor de Tabela M regular com campos de metadados específicos definidos em seu Tipo. Quando a função de fonte de dados retornar uma tabela com esses campos definidos, o Power Query exibirá a caixa de diálogo do navegador. Na verdade, você pode ver os dados subjacentes como um valor de Tabela clicando com o botão direito do mouse no nó raiz e selecionando Editar.

Table.ToNavigationTable

Você pode usar a Table.ToNavigationTable função para adicionar os metadados de tipo de tabela necessários para criar uma tabela de navegação.

Observação

No momento, você precisa copiar e colar essa função em sua extensão M. No futuro, ele provavelmente será movido para a biblioteca padrão M.

A tabela a seguir descreve os parâmetros para esta função:

Parâmetro Detalhes
tabela Sua tabela de navegação.
keyColumns Lista de nomes de coluna que atuam como a chave primária para sua tabela de navegação.
nameColumn O nome da coluna que deve ser usada como o nome de exibição no navegador.
dataColumn O nome da coluna que contém a Tabela ou a Função a ser exibida.
itemKindColumn O nome da coluna a ser usada para determinar o tipo de ícone a ser exibido. Veja abaixo a lista de valores válidos para a coluna.
itemNameColumn O nome da coluna a ser usada para determinar o comportamento de visualização. Normalmente, isso é definido como o mesmo valor que itemKind.
isLeafColumn O nome da coluna usada para determinar se esse é um nó folha ou se o nó pode ser expandido para conter outra tabela de navegação.

A função adiciona os seguintes metadados ao tipo de tabela:

Campo Parâmetro
TabelaDeNavegação.NomeColuna nameColumn
NavigationTable.DataColumn dataColumn
NavigationTable.ItemKindColumn itemKindColumn
NavigationTable.IsLeafColumn isLeafColumn
Preview.DelayColumn itemNameColumn

Valores para ItemKind

Cada um dos seguintes valores de tipo de item fornece um ícone diferente na tabela de navegação.

  • Alimentar
  • Base de dados
  • Servidor de Banco de Dados
  • Dimensão
  • Table
  • Pasta
  • Função
  • View
  • Planilha
  • NomeDefinido
  • Registro

Exemplos

Tabela de navegação simples

O exemplo de código a seguir exibe uma tabela de navegação simples com três tabelas e uma função.

shared NavigationTable.Simple = () =>
    let
        objects = #table(
            {"Name",       "Key",        "Data",                           "ItemKind", "ItemName", "IsLeaf"},{
            {"Item1",      "item1",      #table({"Column1"}, {{"Item1"}}), "Table",    "Table",    true},
            {"Item2",      "item2",      #table({"Column1"}, {{"Item2"}}), "Table",    "Table",    true},
            {"Item3",      "item3",      FunctionCallThatReturnsATable(),  "Table",    "Table",    true},            
            {"MyFunction", "myfunction", AnotherFunction.Contents,       "Function", "Function", true}
            }),
        NavTable = Table.ToNavigationTable(objects, {"Key"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        NavTable;

shared FunctionCallThatReturnsATable = () =>
    #table({"DynamicColumn"}, {{"Dynamic Value"}});

Esse código resultará na seguinte exibição do Navegador no Power BI Desktop:

Um exemplo de uma tabela de navegação simples.

Tabela de navegação de vários níveis

É possível usar tabelas de navegação aninhadas para criar uma exibição hierárquica sobre seu conjunto de dados. Você faz isso definindo o valor de IsLeaf dessa linha como false (o que a marca-o como um nó que pode ser expandido) e formatando a coluna Data para também se tornar outra tabela de navegação.

shared NavigationTable.Nested = () as table =>
    let
        objects = #table(
            {"Name",       "Key",  "Data",                "ItemKind", "ItemName", "IsLeaf"},{
            {"Nested A",   "n1",   CreateNavTable("AAA"), "Table",    "Table",    false},
            {"Nested B",   "n2",   CreateNavTable("BBB"), "Table",    "Table",    false},
            {"Nested C",   "n3",   CreateNavTable("CCC"), "Table",    "Table",    false}
        }),
        NavTable = Table.ToNavigationTable(objects, {"Key"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        NavTable;

CreateNavTable = (message as text) as table => 
    let
        objects = #table(
            {"Name",  "Key",   "Data",                           "ItemKind", "ItemName", "IsLeaf"},{
            {"Item1", "item1", #table({"Column1"}, {{message}}), "Table",    "Table",    true},
            {"Item2", "item2", #table({"Column1"}, {{message}}), "Table",    "Table",    true}
        }),
        NavTable = Table.ToNavigationTable(objects, {"Key"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        NavTable;

Esse código resultaria na seguinte exibição do Navegador no Power BI Desktop:

Um exemplo de uma tabela de navegação hierárquica.

Tabelas de navegação dinâmica

Funcionalidades mais complexas podem ser criadas a partir dessas noções básicas. Embora todos os exemplos acima mostrem entidades codificadas na tabela de navegação, é fácil ver como uma tabela de navegação pode ser gerada dinamicamente com base em entidades que estão disponíveis para um determinado usuário. Algumas considerações importantes para tabelas de navegação dinâmica incluem:

  • Tratamento de erros para garantir uma boa experiência para usuários que não têm acesso a certos endpoints.
  • A avaliação do nó é preguiçosa por padrão; os nós folha não são avaliados até que o nó pai seja expandido. Determinadas implementações de tabelas de navegação dinâmica de vários níveis podem resultar em uma avaliação ansiosa de toda a árvore. Certifique-se de monitorar o número de chamadas que o Power Query está fazendo, pois ele inicialmente renderiza a tabela de navegação. Por exemplo, Table.InsertRows é 'lazier' que Table.FromRecords, pois não precisa avaliar seus argumentos.
  • Last updated on