Usar o Power Query SDK

Este artigo se concentra na experiência disponível para o SDK do Power Query encontrado no Visual Studio Code. Você pode saber mais sobre como instalar o SDK do Power Query para Visual Studio no artigo Instalando o SDK.

Crie um novo projeto

Dica

Antes de criar um projeto de extensão, recomendamos que você crie uma nova pasta para armazenar o projeto. Durante a criação de um novo projeto, se nenhuma pasta for selecionada, o SDK do Power Query ajudará você a localizar ou criar uma nova pasta antes de criar o projeto de extensão.

No Visual Studio Code, no painel principal Explorer do Visual Studio Code, há uma seção chamada SDK do Power Query. Esta seção tem apenas o botão Criar um projeto de extensão. Selecione esse botão.

Esse botão abre um campo de entrada na parte superior da interface do Visual Studio Code. Insira o nome do novo projeto de extensão e selecione Enter.

Depois de alguns segundos, a janela Visual Studio Code abre o arquivo *.pq principal do projeto de extensão que contém a lógica do conector. O SDK do Power Query executa automaticamente algumas tarefas necessárias para concluir a configuração do espaço de trabalho. Você pode verificar essas tarefas no console de saída no Visual Studio Code.

O SDK do Power Query cria automaticamente o seguinte conjunto de arquivos:

• Um arquivo settings.json que dita configurações específicas com as quais trabalhar no nível do espaço de trabalho.
• Ele cria a extensão como um arquivo .mez e a armazena em uma nova pasta bin\AnyCPU\Debug.
• Um conjunto de ícones de conector como arquivos .png.
• Um arquivo resources.resx que serve como o armazenamento principal para strings que são usadas na extensão.
• Um arquivo .pq que contém a lógica principal da extensão ou do conector.
• Um arquivo .query.pq cuja finalidade principal é ser usado como uma maneira de criar consultas de teste que você pode avaliar posteriormente.
• Um arquivo .proj com informações sobre o projeto de extensão.

Depois que um projeto de extensão é reconhecido pelo Visual Studio Code, a seção do SDK do Power Query muda de aparência e agora exibe uma lista de tarefas que você pode executar no novo projeto de extensão.

Credenciais

Importante

Antes de avaliar uma das consultas do conector de dados, um conjunto de credenciais deve primeiro ser criado para o projeto de extensão.

O SDK do Power Query oferece várias tarefas pela interface de usuário para permitir que você defina, liste e exclua credenciais do projeto de extensão.

Definir credencial

O SDK do Power Query é direcionado principalmente por tarefas que podem ser acionadas por vários pontos de entrada. A definição de uma credencial pode ser feita de duas maneiras (as outras tarefas de credencial podem ser feitas da mesma maneira).

• Pela entrada na seção SDK do Power Query no painel do Explorer.

  

• Pelo Terminal, selecionando a opção Executar Tarefa e, em seguida, selecionando a tarefa Definir credencial.

  

Quando você executa essa tarefa, o Visual Studio Code o guia por uma série de prompts para permitir a definição da credencial. Essas séries de prompts são previsíveis e sempre consistem nos mesmos estágios:

1. Escolha o tipo de fonte de dados.
2. Escolha o arquivo do conector.
3. Escolha um método de autenticação.

Para o projeto de extensão existente, o método de autenticação disponível é anônimo. Depois que a autenticação é definida, uma mensagem que confirma que uma credencial foi gerada é exibida no canto inferior direito da janela.

Credenciais da lista

Semelhante à definição de uma credencial, a tarefa de listar credenciais tem dois pontos de entrada nos mesmos locais: a seção SDK do Power Query no painel Explorer e dentro do menu Terminal.

Quando essa tarefa é executada, ela mostra as credenciais disponíveis dentro do terminal de saída.

Apagar TODAS as credenciais

Semelhante às duas tarefas anteriores, a tarefa para apagar todas as credenciais tem dois pontos de entrada nos mesmos locais: a seção SDK do Power Query no painel Explorer e dentro do menu Terminal.

Essa tarefa serve como uma maneira de apagar todas as credenciais da sessão atual quando você precisar definir uma nova credencial para avaliar suas consultas.

As mensagens informativas dessa tarefa também são mostradas no console de saída.

Avaliar uma consulta e o painel de resultados

Antes de avaliar qualquer consulta de teste, uma credencial deve ser definida. Usando o conector que foi criado na seção anterior, você pode abrir o arquivo *.query.pq que serve como arquivo de consulta de teste.

Para esse conector específico onde o nome do projeto era MyConnector, o código tem esta aparência:

// Use this file to write queries to test your data connector
let
    result = MyConnector.Contents()
in
    result

Antes de avaliar a consulta, vamos alterar o código da seguinte maneira:

// Use this file to write queries to test your data connector
let
    result = MyConnector.Contents("Hello World")
in
    result

Salve o arquivo depois de alterar o código.

Para avaliar essa consulta, você tem três opções:

• Selecione com o botão direito do mouse o arquivo que está em uso e selecione a opção Avaliar arquivo do Power Query atual.

• Percorra o menu Terminal e selecione a tarefa Avaliar arquivo atual.

• Use a opção nativa Executar e Depurar do Visual Studio Code, selecione o hiperlink para criar um arquivo launch.json e avalie o arquivo.

Depois de avaliar a consulta, os resultados são exibidos no console na parte inferior da janela e em um novo painel chamado resultados à direita.

O painel de resultados contém três guias:

• Guia Saída: exibe uma visualização de dados da consulta avaliada. Se os dados forem uma tabela, eles serão exibidos como grade.

  

• Resumo: exibe um resumo da atividade que executou as avaliações, juntamente com as estatísticas associadas a essa atividade.

  

• DataSource: exibe informações gerais sobre a fonte de dados usada para a avaliação.

  

Para avaliar uma consulta diferente, basta modificar o arquivo *.query.pq, salvá-lo e executar a tarefa de avaliação novamente com qualquer um dos três métodos.

Observação

O SDK do Power Query não gerencia nenhum tipo de mecanismo de cache para as avaliações.

Trazer um projeto de extensão herdado para o novo SDK

Esta seção ajuda os desenvolvedores de conectores que têm projetos de extensão que foram criados com o SDK do Power Query baseado no Visual Studio herdado.

Para acompanhar, recomendamos baixar os projetos de conector disponíveis no repositório DataConnectors para o exemplo TripPin, especificamente o exemplo 9-TestConnection.

Para trazer o projeto de extensão herdado para o novo SDK, realize estas etapas:

1. No Visual Studio Code, selecione Arquivo>Abrir pasta e, em seguida, navegue até a pasta onde seu projeto de extensão está localizado.

2. Configure um espaço de trabalho usando a pasta existente e o conteúdo usando um dos dois métodos a seguir:

   • O SDK do Power Query tem um mecanismo para reconhecer o conteúdo da pasta e sugere que você ative a conversão para um novo espaço de trabalho do SDK do Power Query.

     

   • Execute o Configurar espaço de trabalho e a Tarefa de Criação no menu do terminal. Eles criarão efetivamente o arquivo .mez e os arquivos settings.json necessários para o espaço de trabalho.

A adição de duas novas pastas e arquivos é o que transforma o espaço de trabalho atual em um novo espaço de trabalho do SDK do Power Query.

Configurar um espaço de trabalho

O que a tarefa Configurar espaço de trabalho faz é criar um arquivo settings.json para seu espaço de trabalho que dita algumas variáveis que serão usadas para o espaço de trabalho quando se trata de avaliações e configurações gerais.

Criar um arquivo de extensão

A tarefa de compilação permite que você crie o arquivo .mez para a extensão sob demanda.

Executar a função TestConnection

TestConnection é uma função que permite que seu conector seja atualizado na Microsoft Cloud por serviços como o Power BI. É um registro implementado dentro do registro da fonte de dados do conector. Você pode saber mais sobre a implementação do manipulador TestConnection no exemplo disponível para conexão de teste.

A tarefa para executar TestConnection permite que você teste o manipulador dentro do SDK do Power Query sem precisar usar manualmente esse manipulador na Microsoft Cloud.

Para executar essa tarefa, primeiro defina uma credencial para o conector e, em seguida, execute a tarefa na seção SDK do Power Query no Explorer ou na lista de tarefas dentro do menu do terminal.

O resultado dessa tarefa é exibido no terminal de saída na parte inferior da janela.

Comentários e bugs

Você tem algum feedback, sugestão ou bug que gostaria de relatar? Visite nosso repositório público oficial no GitHub.

Você pode usar o fórum da Comunidade do Power BI para postar perguntas gerais sobre o Power Query, a linguagem M e o desenvolvimento de conectores personalizados.