TripPin parte 1 - Conector de dados para um serviço OData

Artigo
05/22/2024

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

Nesta lição, você irá:

Criar um novo projeto do Data Connector usando o SDK do Power Query
Criar uma função base para extrair dados de uma fonte
Testar o conector no SDK do Power Query
Registar o conector no Power BI Desktop

Criando um conector OData básico

Nesta secção, cria um novo projeto do Data Connector, fornece algumas informações básicas e testa-o 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 secção SDK do Power Query, selecione o botão Criar um projeto de extensão.

Depois de selecionar esse botão, você será solicitado a inserir o nome do novo projeto. Nomeie este novo projeto TripPin.

Abra o arquivo TripPin.pq e cole na seguinte definição de conector.

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" }
];

Esta definição de conector contém:

Um registro de definição de fonte de dados para o conector TripPin
Uma declaração de que Implícito (Anônimo) é 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 registo de publicação de Origem 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 poder testar o conector, você precisa construí-lo. Para fazer isso, vá para o Terminal e selecione a opção Run Build Task... (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 o conector construído é armazenado como TripPin.mez.

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

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

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

Nota

Pode sempre limpar as credenciais utilizando o comando Limpar TODAS as credenciais ou verificar as credenciais disponíveis utilizando o comando Listar credenciais nas ferramentas do SDK do Power Query.

Com a credencial agora instalada, selecione o arquivo TripPin.query.pq e selecione com o botão direito do mouse no documento para Avaliar o arquivo atual do Power Query ou use 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 de resultados PQTest consiste em três guias:

Saída: exibe uma visualização de seus 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 muito mais.
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 alguns URLs OData diferentes no arquivo de teste para ver como resultados diferentes 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 únicas, 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 que guarda sempre os seus ficheiros enquanto trabalha. Se você fizer alterações no arquivo TripPin.pq, sempre acionará uma tarefa de compilação subsequente para garantir que está testando a versão mais recente do conector.

Abra o Fiddler para capturar o tráfego HTTP e execute a consulta. Você deve ver algumas solicitações diferentes para services.odata.org, geradas pelo processo de contêiner de mashup. Você pode ver que acessar a URL raiz do serviço resulta em um status 302 e um redirecionamento para a versão mais longa da URL. Seguir redirecionamentos é outro comportamento que você obtém "gratuitamente" das funções da biblioteca base.

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

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

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

Carregando 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.

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

Você pode localizar sua extensão digitando seu nome na caixa de pesquisa.

Caixa de diálogo Obter dados.

Selecione o nome da função e selecione Conectar. É apresentada uma mensagem de terceiros — selecione Continuar para continuar. 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.

Invoque a função.

Como esta é a primeira vez que você está acessando essa fonte de dados, você receberá uma solicitação de credenciais. Verifique se o URL mais curto está selecionado e, em seguida, selecione Conectar.

Imagem do prompt de credenciais definido como Anônimo e a configuração de nível definida como a URL mais curta.

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

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

Eu Record.

Conclusão

Esta lição guiou você pela criação de um conector simples baseado na função de biblioteca OData.Feed . Como você viu, pouca lógica é necessária para habilitar um conector totalmente funcional sobre a OData função base. 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 menos capaz — Web.Contents. Cada lição implementa mais recursos de conector, incluindo paginação, deteção de metadados/esquema e dobragem de consulta para a sintaxe de consulta OData, até que seu conector personalizado ofereça suporte ao mesmo intervalo de recursos que OData.Feed.

Próximos passos

TripPin Parte 2 - Conector de dados para um serviço REST

Partilhar via