Estrutura de teste do SDK do Power Query, parte 7 – Guia de pipeline

Esta referência com várias partes aborda a configuração e a execução de um conjunto padrão de testes para desenvolvedores do conector do Power Query. A referência deve ser seguida em sequência para garantir que o ambiente seja configurado para o teste do conector personalizado.

Este guia oferece as etapas necessárias para configurar um pipeline para a estrutura de teste do SDK do Power Query.

Nesta seção, você vai:

Guia de configuração de pipeline para conectores do Power Query

Este guia oferece as etapas necessárias para configurar um pipeline para a estrutura de teste do SDK do Power Query. Em nível alto, requer a configuração de um agente, a configuração do conector em teste, incluindo as configurações de drivers e das credenciais para PQTest com o mecanismo de autenticação suportado, a execução dos testes e o relatório dos resultados. Este documento usa o Azure Pipelines e recursos em todos os seus exemplos. No entanto, esses conceitos podem ser aplicados a outras arquiteturas de pipeline.

O pipeline usa estrutura a seguir:

1. Recuperar os testes de um repositório.
2. Recupere e/ou defina as credenciais para acessar a fonte de dados usando o mecanismo de autenticação com suporte.
3. Executar os testes recuperados na etapa anterior.
4. Atualizar os resultados e logs.

A documentação do Azure Pipelines descreve como configurar um pipeline básico. Confira as seções a seguir para ver recomendações sobre como configurar esses recursos.

• Pré-requisitos do agente
  • Rede
  • Permissões
  • PQTest
  • Drivers
• Credenciais
• Scripts
  • Acesso a credenciais automatizado
  • Executando testes
  • Automação de scripts

Pré-requisitos do agente

O agente de pipeline precisa incluir o SDK do Power Query e ser configurado para executar o PQTest. Essa configuração inclui o acesso à fonte de dados relevante e ao gerenciador de credenciais, se aplicável.

Todos esses requisitos podem ser atendidos com o uso de um agente auto-hospedado. Os Azure Pipelines podem fornecer agentes hospedados pela Microsoft, mas é improvável que esses agentes tenham o SDK do Power Query. Além disso, pode haver obstáculos de rede a serem considerados. O uso de uma máquina virtual ou de um computador físico como agente de pipeline pode garantir que o PQTest se conecte à fonte de dados.

Rede

Para executar testes de conector, o agente deve poder acessar a fonte de dados relevante. O acesso às fontes de dados de nuvem (por exemplo, Snowflake e Google Big Query) costuma ser fácil. No entanto, as fontes de dados locais (por exemplo, SAP BW e SQL Server) precisam de mais configurações. Essas configurações podem exigir que você verifique se o agente está conectado à mesma rede virtual, se o firewall do agente permite as portas corretas e assim por diante.

Permissões

Para extrair automaticamente as credenciais de um cofre de chaves, o agente precisa de um método. O método recomendado é definir uma identidade gerenciada para uma máquina virtual e atribuir as permissões necessárias ao cofre de chaves.

PQTest

O executável do PQTest precisa estar instalado no agente. O método recomendado é: baixe o pacote NuGet do SDK do Power Query e descompacte-o no agente.

O executável do PQTest pode ser encontrado na pasta \tools dos pacotes NuGet. Use o argumento --help para exibir as informações de ajuda do PQTest.exe e conhecer seus comandos.

Drivers

Para conectores ODBC, todos os drivers precisam ser adicionados a uma pasta de Drivers ODBC no seguinte caminho:

<power_query_sdk_extension_path>\Microsoft.PowerQuery.SdkTools.2.xxx.x\tools\ODBC Drivers<drivers>

Exemplo para o driver Contoso, o caminho pode ser o seguinte:

C:\Users\ContosoUser.vscode\extensions\powerquery.vscode-powerquery-sdk-0.2.3-win32-x64.nuget\Microsoft.PowerQuery.SdkTools.2.126.3\tools\ODBC Driver\Contoso

Credenciais

As credenciais são passadas para PQTest usando a extensão Visual Studio Code ou o comando set-credential pela linha de comando. Após sua definição, essas credenciais podem ser reutilizadas para várias execuções de teste.

Dependendo do tipo de autenticação, essas credenciais precisam ser definidas apenas uma vez (Nome de usuário/Senha) ou mantidas atualizadas (token de atualização OAuth2). O primeiro caso pode ser configurado com facilidade na interface do Visual Studio Code. O último caso pode ser feito por meio da criação de um script.

Scripts

O PQTest pode ser usado totalmente a partir da linha de comando, o que permite a automação por meio de scripts.

Acesso a credenciais automatizado

Para automatizar o acesso a credenciais para o PQTest, recomendamos o uso de um cofre de chaves. Dessa forma, as credenciais podem ser atualizadas com facilidade e programadas por script.

1. A primeira etapa é conceder acesso à identidade gerenciada do agente.
2. Em seguida, invoque uma API Rest para acessar os dados.

Agora que você tem uma maneira de obter segredos, pode adicioná-los ao cache de credenciais do PQTest.

1. Use o comando credential-template para criar o modelo JSON. Esse modelo contém texto de espaço reservado ($$USERNAME$$, $$REFRESH_TOKEN$$ e assim por diante), que pode ser alterado dinamicamente por meio de funções de substituição de cadeia de caracteres.

   $keyVaultOutput = invoke-expression 'Get-AzKeyVaultSecret -VaultName $keyVaultName -Name $secretName -AsPlainText'
   $jsonTemplate = invoke-expression "$pqTestExe credential-template -e $extensionFile -q $queryFile -ak $authenticationType"
   $jsonCredential = $jsonTemplate.Replace('$$USERNAME$$', $credentialName)
   $jsonCredential = $jsonCredential.Replace('$$PASSWORD$$', $keyVaultOutput)
   

2. Passe o modelo JSON alterado para o comando set-credential usando barra vertical (|) ou input (<).

   $jsonCredential | & $pqTestExe set-credential -e $extensionFile -q $queryFile
   

Agora que as credenciais estão definidas, os testes já podem ser executados.

Observação: o comando list-credential pode ser usado para confirmar se as credenciais estão definidas corretamente.

Executando testes

Os testes podem ser executados por meio do comando compare. Por exemplo, para executar um teste único:

.\PQTest.exe compare -e <connector file> -q <query file> -p

Para executar vários testes:

.\PQTest.exe compare -e <connector file> -q <query folder> -sq <base query file> -p

Automação de scripts

Os scripts podem ser automatizados executando-os a partir de uma tarefa de pipeline. Para o Azure Pipelines, a tarefa do PowerShell pode ser usada:

# Example Azure pipeline for running connector tests using PQTest.
# Azure Pipelines reference: https://aka.ms/yaml
trigger: none
pool:
  name: SelfHosted-AgentPool
steps:
  - task: PowerShell@2
    inputs:
      filePath: '<path_to_run_test_script>/RunConnectorTest.ps1'
    displayName: 'Run Connector Tests'

Conclusão

Esta seção mostrou como configurar o pipeline para usar a estrutura de teste do SDK do Power Query, usando o conjunto de testes fornecido e seus próprios testes para validar o conector de extensão.

No geral, agora você deve ser capaz de fazer alterações confiáveis na sua extensão e validá-la durante o desenvolvimento e o lançamento.