Power Query SDK 测试框架第 7 部分 - 管道指南

项目
03/25/2024

此参考包含多个部分，介绍适用于 Power Query 连接器开发人员的标准测试套件的设置和运行。应按顺序完成参考，以确保将环境设置用于测试自定义连接器。

本指南提供了为 Power Query SDK 测试框架设置管道所需的步骤。

本部分的操作：

设置管道概述
设置管道代理
了解如何配置连接器，包括驱动程序和凭证设置
运行测试以验证扩展连接器
生成测试运行的报告

Power Query 连接器的管道设置指南

本指南提供了为 Power Query SDK 测试框架设置管道所需的步骤。大致而言，它需要设置代理、配置正在测试的连接器（包括任何驱动程序设置）、使用支持的身份验证机制配置 PQTest 的凭证、运行测试并报告结果。本文档的所有示例均使用 Azure Pipelines 和资源。但是，这些概念可以应用于其他管道架构。

管道使用以下结构：

从存储库检索测试。
检索和/或设置凭证以使用支持的身份验证机制访问数据源。
运行在上一步中检索到的测试。
更新结果和日志。

Azure Pipelines 文档介绍了如何设置基本管道。有关设置这些功能的建议，请参阅以下部分。

代理必备组件
- 网络
- 权限
- PQTest
- 驱动程序
凭证
脚本
- 自动凭证访问
- 正在运行测试
- 自动化脚本

代理必备组件

管道代理需要包含 Power Query SDK 并配置为能够运行 PQTest。此配置包括对相关数据源和凭证管理器（如果适用）的访问。

可以使用自托管代理来满足这些要求。 Azure Pipelines 可以提供 Microsoft 托管的代理，但这些代理不太可能包含 Power Query SDK，并且可能会考虑网络障碍。使用虚拟机或物理计算机作为管道代理可以确保 PQTest 可以连接到数据源。

网络

若要运行连接器测试，代理需要能够访问相关数据源。访问云数据源（例如，Snowflake 和 Google Big Query）可能很容易，但访问本地数据源（例如，SAP BW 和 SQL Server）则需要更多配置。这些配置可能要求你确保代理连接到同一虚拟网络、代理的防火墙允许正确的端口，等等。

权限

如果你的目的是自动从密钥保管库中提取凭证，则代理需要通过一种方法来执行此操作。建议的方法是为虚拟机设置托管标识，并为密钥保管库分配必要的权限。

PQTest

需要在代理上安装 PQTest 可执行文件。建议的方法是下载 Power Query SDK NuGet 包并将其解压缩到代理上。

PQTest 可执行文件可以在 NuGet packages \tools 文件夹中找到。使用 --help 参数显示 PQTest.exe 的帮助信息并熟悉其命令。

驱动程序

对于 ODBC 连接器，需要将所有驱动程序添加到以下路径的 ODBC Drivers 文件夹中：

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

Contoso 驱动程序的示例，路径可能如下所示：

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

凭证

使用 Visual Studio Code 扩展或通过命令行的 set-credential 命令将凭证传递到 PQTest。设置后，可以重复使用这些凭证进行多次测试运行。

根据身份验证的类型，这些凭证可能只需要设置一次（用户名/密码）或保持更新（OAuth2 刷新令牌）。前一种情况可以使用 Visual Studio Code 界面轻松设置。后一种情况可以通过创建脚本来完成。

脚本

PQTest 可以完全从命令行使用，这允许通过脚本实现自动化。

自动凭证访问

若要自动执行 PQTest 的凭证访问，建议使用密钥保管库。这样就可以轻松刷新凭证，并且可以编写脚本。

第一步是向代理的托管身份授予访问权限。
然后，可以调用 Rest API 来访问数据。

获取机密后，可以将它们添加到 PQTest 的凭证缓存。

使用 credential-template 命令创建 JSON 模板。该模板包含占位符文本（$$USERNAME$$、$$REFRESH_TOKEN$$ 等），可以通过字符串替换函数动态更改这些文本。

$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)

使用管道 (|) 或输入 (<) 将更改后的 JSON 模板传递给 set-credential 命令。
```
$jsonCredential | & $pqTestExe set-credential -e $extensionFile -q $queryFile
```

现在凭证已设置，可以运行测试了。

注意：列表凭证命令可用于确认凭证已正确设置。

正在运行测试

可以使用 compare 命令通过命令运行测试。例如，若要运行单个测试，

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

若要运行多个测试：

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

自动化脚本

可以通过从管道任务运行脚本来自动化脚本。对于 Azure Pipelines，可以使用 PowerShell 任务：

# 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'

结束语

本部分介绍了如何设置和配置管道以使用 Power Query SDK 测试框架，使用提供的测试套件以及你自己的测试来验证扩展连接器。

总的来说，你现在应该能够可靠地对扩展进行更改，并在开发和发布期间对其进行验证。

通过