次の方法で共有

Power Query SDK テスト フレームワーク パート 7 - パイプライン ガイド

  • [アーティクル]

このマルチパート リファレンスでは、Power Query コネクタ開発者向けの標準テスト スイートのセットアップと実行について説明します。 このリファレンスは、カスタム コネクタをテストするために環境が確実にセットアップされるように、順番に行われることを意図しています。

このガイドでは、Power Query SDK テスト フレームワークのパイプラインを設定するために必要な手順について説明します。

このセクションでは、次の作業を行います。

  • パイプラインの設定の概要
  • パイプライン エージェントを設定する
  • ドライバーと認証情報のセットアップを含め、コネクタを構成する方法について説明
  • テストを実行して拡張コネクタを確認する
  • テスト実行のレポートを生成する

Power Query コネクタのパイプライン セットアップ ガイド

このガイドでは、Power Query SDK テスト フレームワークのパイプラインを設定するために必要な手順について説明します。 大まかに言えば、エージェントの設定、ドライバー設定を含むテスト対象のコネクタの構成、サポートされている認証メカニズムで PQTest の認証情報の構成、テストの実行、結果の報告が必要です。 このドキュメントは、すべての例で Azure Pipelines とリソースを使用します。 ただし、これらの概念はその他のパイプライン アーキテクチャに適用できます。

パイプラインは次の構造を使用します。

  1. リポジトリからテストを取得します。
  2. サポートされている認証メカニズムを使用し、データ ソースにアクセスするための認証情報の取得や設定します。
  3. 前の手順で取得したテストを実行します。
  4. 結果とログを更新します。

Azure Pipelines のドキュメントは、基本的なパイプラインの設定方法について説明します。 これらの機能の設定に関するアドバイスについては、次のセクションを参照してください。

  • エージェントの前提条件
    • ネットワーク
    • アクセス許可
    • PQTest
    • ドライバー
  • 資格情報
  • スクリプト
    • 認証情報アクセスの自動化
    • テストの実行
    • スクリプトを自動化する

エージェントの前提条件

パイプライン エージェントには Power Query SDK を含め、PQTest を実行できるように構成する必要があります。 この構成には、該当する場合、関連するデータ ソースと資格情報マネージャーへのアクセスが含まれます。

これらの要件は、セルフホステッド エージェントを使用してすべて満たすことができます。 Azure Pipelines は Microsoft ホステッド エージェントを提供できますが、これらのエージェントには Power Query SDK が含まれている可能性は低く、考慮すべきネットワーク上の問題がある可能性があります。 パイプライン エージェントとして仮想マシンまたは物理コンピューターを使用すると、PQTest がデータ ソースに接続できるようにします。

ネットワーク

コネクタ テストを実行するには、エージェントが関連するデータ ソースにアクセスする必要があります。 クラウド データ ソース(たとえば、Snowflake や Google Big Query)には簡単にアクセスできる可能性がありますが、オンプレミスのデータ ソース(たとえば、SAP BW や SQL Server)にはさらなる構成が必要です。 これらの構成では、エージェントが同じ仮想ネットワークに接続されていることや、エージェントのファイアウォールが正しいポートを許可していることなどを確認する必要がある場合があります。

アクセス許可

キー コンテナーから認証情報を自動的にプルすることを意図している場合、エージェントはそれを行う方法が必要です。 推奨される方法には、仮想マシンにマネージド ID を設定し、必要なアクセス許可をキー コンテナーに割り当てることです。

PQTest

PQTest の実行可能ファイルはエージェントにインストールされている必要があります。 推奨される方法には、Power Query SDK NuGet パッケージをダウンロードしてエージェントに解凍することです。

PQTest の実行可能ファイルは、NuGet パッケージの \tools フォルダーにあります。 --help 引数を使用し、PQTest.exe のヘルプ情報を表示してそのコマンドについて理解します。

ドライバー

ODBC コネクタの場合、次のパスにある ODBC ドライバー フォルダーに追加する必要があるすべてのドライバー。

<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 に渡されます。 設定すると、これらの認証情報を複数のテスト実行に再利用できます。

認証の種類によっては、これらの認証情報を 1 回のみ(ユーザー名/パスワード)設定するか、更新(OAuth2 更新トークン)を保持する必要がある場合があります。 前者の場合、Visual Studio Code インターフェイスを使用して簡単に設定できます。 後者の場合、スクリプトを作成することで実現できます。

スクリプト

PQTest はコマンド ラインから完全に使用できるため、スクリプトで自動化が可能になります。

認証情報アクセスの自動化

PQTest の認証情報アクセスを自動化するには、キー コンテナーを使用することをお勧めします。 これにより、認証情報を簡単に更新してスクリプトを作成できます。

  1. 最初のステップは、エージェントのマネージド ID に権利を与えることです。
  2. その後、Rest API を起動してデータにアクセスできます。

シークレットを取得する方法を得たため、PQTest の認証情報キャッシュに追加できます。

  1. 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)

  2. パイプ(|)または入力(<)のいずれかを使用して、変更された JSON テンプレートを set-credential コマンドに渡します。

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

認証情報が設定されたため、テストを実行できます。

メモ: list-credential コマンドを使用し、認証情報が正しく設定されていることを確認できます。

テストの実行

テストは、compare コマンドを使用してコマンドで実行できます。 たとえば、1 つのテストを実行する方法

.\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 テスト フレームワークを使用するようにパイプラインを設定と構成する方法について説明しました。

全体的に、拡張機能に確実に変更を加え、開発とリリース時に検証できるようになります。