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

Artigo
03/21/2024

Esta referência com várias partes abrange a configuração e a execução de um conjunto padrão de testes para programadores de conectores do Power Query. A referência deve ser feita sequencialmente para garantir que seu ambiente esteja configurado para testar seu conector personalizado.

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

Nesta secção, pode:

Visão geral da configuração do pipeline
Configurar um agente de pipeline
Aprenda a configurar o conector, incluindo a configuração de driver e credenciais
Execute os testes para verificar o conector de extensão
Gerar o relatório da execução de teste

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

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

O pipeline usa a seguinte estrutura:

Recupere os testes de um repositório.
Recupere e/ou defina as credenciais para acessar a fonte de dados usando o mecanismo de autenticação suportado.
Execute os testes recuperados na etapa anterior.
Atualize os resultados e logs.

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

Pré-requisitos do agente
- Rede
- Permissões
- PQTest
- Controladores
Credencial
Roteiros
- Acesso automatizado a credenciais
- Executando testes
- Automatizando scripts

Pré-requisitos do agente

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

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

Rede

Para executar testes de conector, o agente precisa ser capaz de acessar a fonte de dados relevante. As fontes de dados na nuvem (por exemplo, Snowflake e Google Big Query) provavelmente são facilmente acessíveis, 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ê garanta que o agente esteja conectado à mesma rede virtual, que o firewall do agente permita as portas corretas e assim por diante.

Permissões

Se sua intenção é extrair automaticamente as credenciais de um cofre de chaves, o agente precisa de um método para fazê-lo. 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 PQTest precisa estar instalado no agente. O método recomendado é baixar o pacote NuGet do SDK do Power Query e descompactá-lo no agente.

O executável PQTest pode ser encontrado na pasta NuGet packages \tools. Use o argumento --help para exibir informações de ajuda para PQTest.exe e familiarizar-se com seus comandos.

Controladores

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

Credencial

As credenciais são passadas para PQTest usando a extensão Visual Studio Code ou o comando set-credential através da linha de comando. Uma vez definidas, essas credenciais podem ser reutilizadas para várias execuções de teste.

Dependendo do tipo de autenticação, essas credenciais podem precisar ser definidas apenas uma vez (Nome de usuário/Senha) ou mantidas atualizadas (token de atualização OAuth2). O primeiro caso pode ser configurado facilmente usando a interface de código do Visual Studio. O último caso pode ser realizado através da criação de um script.

Scripts

O PQTest pode ser usado inteiramente a partir da linha de comando, o que permite a automação através de scripts.

Acesso automatizado a credenciais

Para automatizar o acesso de credenciais para PQTest, recomendamos o uso de um cofre de chaves. Desta forma, as credenciais podem ser atualizadas facilmente e podem ser roteirizadas.

A primeira etapa é conceder acesso à identidade gerenciada do agente.
Em seguida, você pode invocar uma API Rest para acessar dados.

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

Use o comando credential-template para criar um modelo JSON. Este 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)

Passe o modelo JSON alterado para o comando set-credential usando pipe (|) ou input (<).
```
$jsonCredential | & $pqTestExe set-credential -e $extensionFile -q $queryFile
```

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

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

Executando testes

Os testes podem ser executados através do comando usando o comando compare . Por exemplo, para executar um único teste:

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

Automatizando scripts

Os scripts podem ser automatizados executando-os a partir de uma tarefa de pipeline. Para Pipelines do Azure, a tarefa 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 também seus próprios testes para validar seu conector de extensão.

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

Partilhar via