Visão geral do SDK do Power Query

  • Artigo

O SDK do Power Query é um conjunto de ferramentas projetado para ajudá-lo a criar conectores do Power Query. Esses conectores geralmente são chamados de conectores personalizados ou extensões do Power Query.

Os conectores personalizados permitem que você crie novas fontes de dados ou personalize e estenda uma fonte existente. Os casos de uso comuns incluem:

  • Criar uma exibição de uma API REST fácil de usar por analistas de negócios.
  • Fornecer identidade visual usando um conector existente para uma fonte que o Power Query suporta (como por exemplo, um serviço OData ou driver ODBC).
  • Implementar o fluxo de autenticação do OAuth v2 para uma oferta de SaaS.
  • Expor uma exibição limitada ou filtrada sobre a fonte de dados para aprimorar a usabilidade.
  • Habilitar o DirectQuery para uma fonte de dados usando um driver ODBC.

Instalação do SDK do Power Query

Atualmente, há duas versões do SDK do Power Query disponíveis:

  • SDK do Power Query para Visual Studio: Lançado em 2017 como uma extensão para Visual Studio 2017 e 2019.
  • SDK do Power Query para Visual Studio Code (Versão Preliminar): lançado em 2022 como a maneira nova e recomendada de criar conectores do Power Query.

Incentivamos todos os desenvolvedores a instalar e usar o recém-lançado SDK do Power Query para Visual Studio Code (Versão Preliminar), pois essa versão será eventualmente o SDK padrão daqui para frente.

SDK do Power Query para Visual Studio

Siga as etapas abaixo para instalar o SDK do Power Query para Visual Studio:

  1. Instale o SDK do Power Query no Visual Studio Marketplace.
  2. Crie um projeto de conector de dados.
  3. Defina a logica do seu conector.
  4. Crie o projeto para produzir um arquivo de extensão.

Versão prévia do recurso.

SDK do Power Query para Visual Studio Code (Versão Preliminar)

Observação

O novo SDK do Power Query para Visual Studio Code está atualmente em visualização pública desde setembro de 2022.

Instale o novo SDK do Power Query para Visual Studio Code na seção Visual Studio Code do Visual Studio Marketplace. Selecione Instalar para instalar o SDK.

Processo de desenvolvimento de conector

Embora você possa usar tanto o SDK do Power Query para Visual Studio Code quanto para Visual Studio, ambos utilizam um processo semelhante para o desenvolvimento de um conector em um nível mais alto.

As seguintes seções descrevem, em um nível mais alto, o processo mais comum para criar um conector do Power Query usando o SDK.

Criando uma nova extensão

Ao criar um novo projeto (SDK do Power Query para Visual Studio) ou um novo espaço de trabalho (SDK do Power Query para Visual Studio Code), você começa com os seguintes arquivos principais:

  • Arquivo de definição do conector (<connectorName>.pq)
  • Um arquivo de consulta (<connectorName>.query.pq)
  • Um arquivo de recurso de cadeia de caracteres (resources.resx)
  • Arquivos PNG de vários tamanhos usados para criar ícones

O arquivo de definição do conector começará com uma descrição vazia da fonte de dados. Você pode saber mais sobre uma fonte de dados no contexto do SDK do Power Query no artigo Lidando com o acesso a dados.

Testando

O SDK do Power Query fornece recursos básicos de execução de consulta, permitindo que você teste sua extensão sem precisar alternar para o Power BI Desktop.

Arquivo de teste de consulta

Além do arquivo de extensão, os projetos do Conector de Dados podem ter um arquivo de consulta (name.query.pq). Esse arquivo pode ser usado para executar consultas de teste no Visual Studio. A avaliação da consulta incluirá automaticamente seu código de extensão, sem precisar registrar seu arquivo .pqx, permitindo que você chame ou teste quaisquer funções compartilhadas em seu código de extensão.

O arquivo de consulta pode conter uma única expressão (por exemplo, HelloWorld.Contents()), uma expressão let (como o que Power Query geraria) ou um documento de seção.

Criar e implantar

A construção do seu projeto gera o arquivo .mez ou arquivo de extensão.

As extensões do Power Query são agrupadas em um arquivo ZIP e recebem uma extensão de arquivo .mez. Em tempo de execução, o Power BI Desktop carrega extensões de [Documents]\Microsoft Power BI Desktop\Custom Connectors.

Observação

Os projetos do Conector de Dados não dão suporte a etapas personalizadas após a compilação para copiar o arquivo de extensão para o diretório [Documentos]\Microsoft Power BI Desktop\Conectores Personalizados. Se isso é algo que você deseja fazer, convém usar uma extensão de terceiros. Se isso é algo que deseja fazer, você pode usar uma extensão de terceiros.

As extensões são definidas em um documento da seção M. Um documento de seção tem um formato ligeiramente diferente dos documentos de consulta gerados no Power Query. O código importado do Power Query normalmente requer modificação para caber em um documento de seção, mas as alterações são secundárias. As diferenças de documento da seção que você deve conhecer incluem:

  • Eles começam com uma declaração de seção (por exemplo, section HelloWorld;).
  • Cada expressão termina com um ponto e vírgula (por exemplo, a = 1; ou b = let c = 1 + 2 in c;).
  • Todas as funções e variáveis são locais ao documento de seção, a menos que estejam marcadas como compartilhadas. As funções compartilhadas tornam-se visíveis para outras consultas/funções e podem ser consideradas como exportações para sua extensão (ou seja, elas podem ser chamadas do Power Query).

Mais informações sobre os documentos da seção M podem ser encontradas na Especificação da Linguagem M..

Distribuição de conectores de dados

Os conectores do Power Query podem ser usados no Power BI Desktop ou na experiência do Power Query Online, como fluxos de dados do Power BI, datamarts do Power BI e outras experiências.

Power BI Desktop

Os usuários do Power BI Desktop podem seguir as etapas abaixo para consumir um conector personalizado do Power Query:

  1. Copie o arquivo de extensão (.mez ou .pqx) para [Documentos]/Power BI Desktop/Conectores Personalizados.
  2. No Power BI Desktop, selecione a opção (Não recomendado) Permitir que qualquer extensão seja carregada sem validação ou aviso em Arquivo>Opções e configurações>Opções>Segurança>Extensões de Dados.
  3. Reinicie o Power BI Desktop.

O Power BI Desktop carregará automaticamente as extensões na reinicialização.

Alternativamente, como proprietário da fonte de dados e do conector, você pode enviar seu conector para o programa Certificação de Conector do Power Query para que ele seja incluído no Power BI Desktop em cada versão lançada.

Power Query Online

Observação

A equipe do Power Query está trabalhando muito para habilitar todos os conectores certificados do Power Query na experiência do Power Query Online.

Apenas os conectores certificados do Power Query são exibidos na experiência do Power Query Online. Para saber mais sobre o programa de certificação de conector do Power Query, acesse Certificação de Conector do Power Query.