Parte 1 do TripPin – Conector de dados para um serviço OData

Este tutorial de várias partes aborda a criação de uma nova extensão de fonte de dados para o Power Query. O tutorial deve ser seguido sequencialmente; cada lição se baseia no conector criado nas lições anteriores, adicionando incrementalmente novos recursos a ele.

Nesta lição, você vai:

• Criar um projeto de Conector de Dados usando o SDK do Power Query
• Criar uma função básica para extrair dados de uma fonte
• Testar o conector no SDK do Power Query
• Registrar o conector no Power BI Desktop

Criar um conector OData básico

Nesta seção, você criará um projeto de Conector de Dados, fornecerá algumas informações básicas e testará no SDK do Power Query.

Abra o Visual Studio Code. Recomendamos que você crie um novo espaço de trabalho e, em seguida, crie um novo projeto de extensão. Para criar o novo projeto de extensão, abra o explorador e, na seção SDK do Power Query, selecione o botão Criar um projeto de extensão.

Depois de selecionar esse botão, será solicitado que você insira o nome do novo projeto. Dê o nome de TripPin ao novo projeto.

Abra o arquivo TripPin.pq e cole na definição do conector a seguir.

section TripPin;

[DataSource.Kind="TripPin", Publish="TripPin.Publish"]
shared TripPin.Feed = Value.ReplaceType(TripPinImpl, type function (url as Uri.Type) as any);

TripPinImpl = (url as text) =>
    let
        source = OData.Feed(url)
    in
        source;

// Data Source Kind description
TripPin = [
    Authentication = [
        Anonymous = []
    ],
    Label = "TripPin Part 1 - OData"
];

// Data Source UI publishing description
TripPin.Publish = [
    Beta = true,
    Category = "Other",
    ButtonText = { "TripPin OData", "TripPin OData" }
];

Essa definição de conector contém:

• Um registro de definição da Fonte de Dados para o conector do TripPin
• Uma declaração de que Implícita (Anônima) é o único tipo de autenticação para essa fonte
• Uma função (TripPinImpl) com uma implementação que chama OData.Feed
• Uma função compartilhada (TripPin.Feed) que define o tipo de parâmetro como Uri.Type
• Um registro de publicação da Fonte de Dados que permite que o conector apareça na caixa de diálogo Obter Dados do Power Query

Abra o arquivo TripPin.query.pq. Substitua o conteúdo atual por uma chamada para a função exportada.

TripPin.Feed("https://services.odata.org/v4/TripPinService/")

Antes de testar seu conector, você precisa criá-lo. Para fazer isso, vá para o Terminal e selecione a opção Executar tarefa de compilação... (atalho de teclado Ctrl + Shift + B). Recomendamos escolher a opção MakePQX , mas qualquer uma das opções disponíveis para compilação deve funcionar.

O resultado desta operação cria uma nova pasta Bin onde seu conector construído é armazenado como TripPin.mez.

O arquivo <project>.query.pq é usado para testar a extensão sem precisar implantá-la na pasta bin do Power BI Desktop. Usando as ferramentas disponíveis no SDK do Power Query:

1. Selecione a opção Definir credencial.
2. Selecione TripPin como a fonte de dados.
3. Selecione o arquivo TripPin.query.pq como o arquivo de consulta/teste.
4. Selecione anônimo como o tipo de autenticação.

Na caixa de diálogo de saída, é exibida uma mensagem que confirma que você definiu uma credencial para a fonte de dados e os detalhes para cada credencial criada.

Observação

Você sempre pode limpar as credenciais usando o comando Clear ALL credentials ou verificar as credenciais disponíveis usando o comando List credentials nas ferramentas do SDK do Power Query.

Com a credencial agora em vigor, você seleciona o arquivo TripPin.query.pq e seleciona com o botão direito do mouse no documento para Avaliar o arquivo atual do Power Query ou usa a opção para Avaliar o arquivo atual das ferramentas do SDK do Power Query.

A caixa de diálogo de saída exibe uma mensagem dos resultados da sua avaliação, bem como uma nova janela com o nome PQTest result.

A janela PQTest result consiste em três guias:

• Saída: exibe uma visualização dos dados em uma grade.
• Resumo: detalhes gerais da avaliação, como StartTime, EndTime, Duration, o arquivo que foi usado para a avaliação, o status e outros.
• DataSource: fornece informações sobre a fonte de dados que foi usada a partir do tipo, o nome da função e o caminho.

Você pode experimentar algumas URLs do OData diferentes no arquivo de teste para ver como outros resultados são retornados. Por exemplo:

• https://services.odata.org/v4/TripPinService/Me
• https://services.odata.org/v4/TripPinService/GetPersonWithMostFriends()
• https://services.odata.org/v4/TripPinService/People

O arquivo TripPin.query.pq pode conter instruções individuais, instruções let ou documentos de seção completa.

let
    Source = TripPin.Feed("https://services.odata.org/v4/TripPinService/"),
    People = Source{[Name="People"]}[Data],
    SelectColumns = Table.SelectColumns(People, {"UserName", "FirstName", "LastName"})
in
    SelectColumns

Importante

Certifique-se de sempre salvar seus arquivos enquanto trabalha. Se você fizer alterações no arquivo TripPin.pq, deverá sempre disparar uma tarefa de compilação subsequente para certificar-se de que está testando a versão mais recente do conector.

Abra o Fiddler para capturar o tráfego HTTP e execute a consulta. Você verá algumas solicitações diferentes ao services.odata.org, geradas pelo processo de contêiner de mashup. Veja que o acesso à URL raiz do serviço resulta em um status 302 e um redirecionamento para a versão mais longa da URL. Os redirecionamentos a seguir são outros comportamentos que você obtém "gratuitamente" das funções da biblioteca básica.

Uma coisa a observar se você olhar para as URLs é que você poderá ver a dobragem de consultas que aconteceu com a instrução SelectColumns. https://services.odata.org/v4/TripPinService/People?$select=UserName%2CFirstName%2CLastName

Se você adicionar transformações à sua consulta, verá como elas afetam a URL gerada.

Esse comportamento é importante de se observar. Embora você não tenha implementado a lógica de dobragem explícita, seu conector herda esses recursos da função OData.Feed. As instruções da M podem ser compostas; os contextos de filtro fluirão de uma função para outra, sempre que possível. Isso tem conceito semelhante à maneira como as funções da fonte de dados usadas no conector herdam o contexto e as credenciais de autenticação. Em lições posteriores, você substituirá o uso do OData.Feed, que tem funcionalidades de dobragem nativas, pelo Web.Contents, que não as tem. Para obter o mesmo nível de funcionalidades, você precisará usar a interface Table.View e implementar sua própria lógica de dobragem explícita.

Carregar sua extensão no Power BI Desktop

Para usar sua extensão no Power BI Desktop, você precisará copiar o arquivo de saída do projeto do conector (TripPin.mez) para o diretório Conectores Personalizados.

1. Crie um diretório [Meus Documentos]\Power BI Desktop\Conectores Personalizados .
2. Copie o arquivo de extensão (TripPin.mez) neste diretório.
3. Verifique a opção (Não Recomendado) Permitir que qualquer extensão seja carregada sem validação ou aviso no Power BI Desktop (em Arquivo>Opções e configurações>Opções>Segurança>Extensões de Dados).
4. Reinicie o Power BI Desktop.
5. Selecione Obter Dados > Mais para abrir a caixa de diálogo Obter Dados.

Para localizar a extensão, digite o nome dela na caixa de pesquisa.

Selecione o nome da função e selecione Conectar. Uma mensagem de terceiros é exibida; selecione Continuar para seguir. A caixa de diálogo de invocação de função agora é exibida. Insira a URL raiz do serviço (https://services.odata.org/v4/TripPinService/) e selecione OK.

Como esta é a primeira vez que você está acessando essa fonte de dados, você receberá um prompt de credenciais. Verifique se a URL mais curta está selecionada e escolha Conectar.

Observe que, em vez de obter uma tabela simples de dados, o navegador é exibido. Isso ocorre porque a função OData.Feed retorna uma tabela com metadados especiais que a experiência do Power Query sabe exibir como uma tabela de navegação. Este passo a passo abordará como você faz para criar e personalizar sua própria tabela de navegação em uma lição futura.

Selecione a tabela Me e selecione Transformar Dados. Observe que as colunas já têm tipos atribuídos (bem, a maioria delas). Esse é outro recurso da função OData.Feed subjacente. Se você observar as solicitações no Fiddler, verá que obteve o documento $metadata do serviço. A implementação do OData do mecanismo faz isso automaticamente para determinar o esquema, os tipos de dados e as relações do serviço.

Conclusão

Esta lição mostrou a criação de um conector simples com base na função de biblioteca OData.Feed. Como você viu, é necessária pouca lógica para habilitar um conector totalmente funcional sobre a função base OData. Outras funções habilitadas para extensibilidade, como ODBC.DataSource, fornecem recursos semelhantes.

Na próxima lição, você substituirá o uso de OData.Feed por uma função com menos funcionalidades: Web.Contents. Cada lição implementa mais recursos de conector, incluindo paginação, detecção de metadados/esquema e dobragem de consultas na sintaxe da consulta do OData, até que seu conector personalizado dê suporte à mesma variedade de recursos que o OData.Feed.

Próximas etapas

Parte 2 do TripPin – Conector de Dados para um serviço REST