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 Visual Studio
• Criar uma função básica para extrair dados de uma fonte
• Testar seu conector no Visual Studio
• 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 Visual Studio.

Abra o Visual Studio e crie um projeto. Na pasta do Power Query, selecione o projeto Conector de Dados. Para este exemplo, defina o nome do projeto como TripPin.

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 permitirá que o conector apareça na caixa de diálogo Obter Dados do Power BI

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/")

Selecione o botão Iniciar para iniciar o utilitário M Query.

O arquivo <project>.query.pq é usado para testar a extensão sem precisar implantá-la na pasta bin do Power BI Desktop. Selecionar o botão Iniciar (ou pressionar F5) compila automaticamente a extensão e inicia o utilitário M Query.

A primeira execução da sua consulta resultará em um erro de credencial. No Power Query, o aplicativo de hospedagem converteria esse erro em um prompt de credencial. No Visual Studio, você receberá um prompt semelhante que indicará qual fonte de dados tem as credenciais ausentes e o caminho da fonte de dados. Selecione o mais curto dos caminhos da fonte de dados (https://services.odata.org/) – isso aplicará a credencial a todas as URLs nesse caminho.

Selecione o tipo de credencial Anônima e selecione Definir Credencial.

Selecione OK para fechar a caixa de diálogo e selecione o botão Iniciar mais uma vez. Você verá uma caixa de diálogo de status de execução de consulta e, por fim, uma tabela resultados da consulta mostrando os dados retornados da consulta.

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

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. No Visual Studio, selecione Compilar | Compilar Solução (F6) na barra de menus. Isso gerará o arquivo .mez para seu projeto. Por padrão, ele vai para a pasta bin\Debug do projeto.
2. Crie um diretório [My Documents]\Power BI Desktop\Custom Connectors.
3. Copie o arquivo de extensão neste diretório.
4. 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).
5. Reinicie o Power BI Desktop.
6. 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, pouca lógica é necessária 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 implementará 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