Stream Analytics プロジェクトのビルド、テスト、デプロイを自動化する

[アーティクル]
03/23/2023

Azure Stream Analytics (ASA) の CI/CD npm パッケージを使用すると、Stream Analytics プロジェクトのビルド、テスト、デプロイを自動的に実行することができます。この記事では、CI/CD システムで npm パッケージを使用する方法について示します。 Azure DevOps を使用したパイプラインの設定については、Azure DevOps を使用して Stream Analytics ジョブの CI/CD パイプラインを作成する方法に関するページを参照してください。

Stream Analytics プロジェクトがない場合は、Visual Studio Code を使用して作成するか、Azure portal から既存のものをエクスポートします。

インストール

npm サイトからパッケージをダウンロードするか、ターミナルで次のコマンドを実行できます。

npm install -g azure-streamanalytics-cicd

プロジェクトをビルドする

注意

更新された ARM テンプレートスキーマの --v2 オプションを使用することを強くお勧めします。更新されたスキーマはパラメーターが少なくなりますが、以前のバージョンと同じ機能が保持されています。

古い ARM テンプレートは、今後非推奨になります。これ以降、build --v2 を使用して作成されたテンプレートのみが、更新プログラムまたはバグ修正プログラムを受け取ります。

azure-streamanalytics-cicd build --v2 --project <projectFullPath> [--outputPath <outputPath>]

build コマンドにより、キーワード構文チェックが実行され、Azure Resource Manager (ARM) テンプレートが作成されます。

引数	説明
`--project`	絶対パスまたは相対パスを使用して asaproj.json ファイルを指定します。
`--outputPath`	絶対パスまたは相対パスを使用して ARM テンプレートを格納する出力フォルダーを指定します。 `outputPath` が指定されていない場合、テンプレートは現在のディレクトリに格納されます。

例:

# Go to the project directory
cd <path-to-the-project>

# Build project
azure-streamanalytics-cicd build --v2 --project ./asaproj.json --outputPath ./Deploy

プロジェクトが正常にビルドされると、出力フォルダーの下に 2 つの JSON ファイルが作成されます。

ARM テンプレートファイル: [ProjectName].JobTemplate.json
ARM パラメーターファイル: [ProjectName].JobTemplate.parameters.json

parameters.json ファイルの既定値は、プロジェクト設定から取得されます。別の環境にデプロイする場合は、値を適宜置換します。

すべての資格情報の既定値は null です。 Azure にデプロイする前に、値を設定する必要があります。

"Input_EntryStream_sharedAccessPolicyKey": {
  "value": null
}

出力シンクとしての Azure Data Lake Store Gen1 にマネージド ID を使用するには、Azure にデプロイする前に、PowerShell を使用してサービスプリンシパルへのアクセス許可を提供する必要があります。詳細については、Resource Manager テンプレートによってマネージド ID を使用した ADLS Gen1 のデプロイを行う方法を確認してください。

ローカルで実行する

プロジェクトでローカルの入力ファイルが指定されている場合は、localrun コマンドを使用して Stream Analytics スクリプトをローカルで実行することができます。

azure-streamanalytics-cicd localrun -project <projectFullPath> [-outputPath <outputPath>] [-customCodeZipFilePath <zipFilePath>]

引数	説明
`--project`	絶対パスまたは相対パスを使用して asaproj.json ファイルを指定します。
`--outputPath`	絶対パスまたは相対パスを使用して ARM テンプレートを格納する出力フォルダーを指定します。 `outputPath` が指定されていない場合、テンプレートは現在のディレクトリに格納されます。
`--customCodeZipFilePath`	UDF やデシリアライザーなど、C# のカスタムコードが使用されている場合、その ZIP ファイルのパス。 DLL を ZIP ファイルにパッケージして、そのパスを指定してください。

例:

# Go to the project directory
cd <path-to-the-project>

# Run project locally
azure-streamanalytics-cicd localrun --project ./asaproj.json"

注意

JavaScript UDF は、Windows 上でのみ機能します。

自動テスト

CI/CD npm パッケージを使用して、Stream Analytics プロジェクトの自動テストを構成、実行できます。

テストケースを追加する

azure-streamanalytics-cicd addtestcase --project <projectFullPath> [-testConfigPath <testConfigFileFullPath>]

テストケースは、テスト構成ファイルにあります。

引数	説明
`--project`	絶対パスまたは相対パスを使用して asaproj.json ファイルを指定します。
`--testConfigPath`	テスト構成ファイルのパス。指定しなかった場合は、現在 asaproj.json ファイルが置かれているディレクトリの \test でファイルが検索されます。既定のファイル名は testConfig.json です。新しいファイルが存在しない場合は作成されます。

例:

# Go to the project directory
cd <path-to-the-project>

# Add a test case
azure-streamanalytics-cicd addtestcase --project ./asaproj.json

テスト構成ファイルが空の場合、次の内容がファイルに追加されます。それ以外の場合は、TestCases 配列にテストケースが追加されます。必要な入力構成は、入力構成ファイルに従って自動的に入力されます。テストを実行する前に、各入力の FilePath と必要な出力を指定する必要があります。この構成は手動で変更できます。

テスト検証で特定の出力を無視したい場合は、必要な出力の Required フィールドを false に設定してください。

{
  "Script": [Absolute path of your script],
  "TestCases": [
    {
      "Name": "Case 1",
      "Inputs": [
        {
          "InputAlias": [Input alias string],
          "Type": "Data Stream",
          "Format": "JSON",
          "FilePath": [Required],
          "ScriptType": "InputMock"
        }
      ],
      "ExpectedOutputs": [
        {
          "OutputAlias": [Output alias string],
          "FilePath": [Required],
          "IgnoreFields": [Fields to ignore for test validation, e.g., ["col1", "col2"]],
          "Required": true
        }
      ]
    }
  ]
}

単体テストを実行する

以下のコマンドを使用すると、プロジェクトのテストケースを複数実行することができます。テスト結果の概要は出力フォルダーに生成されます。このプロセスの終了コードは、すべてのテストに合格した場合は 0、例外が発生した場合は -1、テストで不合格となった場合は -2 になります。

azure-streamanalytics-cicd test --project <projectFullPath> [--testConfigPath <testConfigFileFullPath>] [--outputPath <outputPath>] [--customCodeZipFilePath <zipFilePath>]

引数	説明
`--project`	asaproj.json ファイルのパス。
`--testConfigPath`	テスト構成ファイルのパス。指定しなかった場合は、現在 asaproj.json ファイルが置かれているディレクトリの \test でファイルが検索されます。既定のファイル名は testConfig.json です。
`--outputPath`	テスト結果の出力フォルダーのパス。指定しなかった場合、出力結果ファイルは現在のディレクトリに格納されます。
`--customCodeZipFilePath`	UDF やデシリアライザーなどのカスタムコードが使用されている場合、その ZIP ファイルのパス。 DLL を zip ファイルにパッケージ化し、パスを指定する必要があります。

テストケースが実行された場合は、出力フォルダーに生成された testResultSummary.json ファイルが見つかります。

{
  "Total": (integer) total_number_of_test_cases,
  "Passed": (integer) number_of_passed_test_cases,
  "Failed": (integer) number_of_failed_test_cases,
  "Script": (string) absolute_path_to_asaql_file,
  "Results": [ (array) detailed_results_of_test_cases
    {
      "Name": (string) name_of_test_case,
      "Status": (integer) 0(passed)_or_1(failed),
      "Time": (string) time_span_of_running_test_case,
      "OutputMatched": [ (array) records_of_actual_outputs_equal_to_expected_outputs
        {
          "OutputAlias": (string) output_alias,
          "ExpectedOutput": (string) path_to_the_expected_output_file,
          "Output": (string) path_to_the_actual_output_file
        }
      ],
      "OutputNotEqual": [ (array) records_of_actual_outputs_not_equal_to_expected_outputs
        {
          "OutputAlias": (string) output_alias,
          "ExpectedOutput": (string) path_to_the_expected_output_file,
          "Output": (string) path_to_the_actual_output_file
        }
      ],
      "OutputMissing": [ (array) records_of_actual_outputs_missing
        {
          "OutputAlias": (string) output_alias,
          "ExpectedOutput": (string) path_to_the_expected_output_file,
          "Output": ""
        }
      ],
      "OutputUnexpected": [ (array) records_of_actual_outputs_unexpected
        {
          "OutputAlias": (string) output_alias,
          "ExpectedOutput": "",
          "Output": (string) path_to_the_actual_output_file
        }
      ],
      "OutputUnrequired": [ (array) records_of_actual_outputs_unrequired_to_be_checked
        {
          "OutputAlias": (string) output_alias,
          "ExpectedOutput": (string) path_to_the_expected_output_file,
          "Output": (string) path_to_the_actual_output_file
        }
      ]
    }
  ],
  "Time": (string) time_span_of_running_all_test_cases,
}

注意

クエリ結果に float 値が含まれている場合は、生成された値にわずかな違いが生じて、テストが失敗する可能性があります。これは、Visual Studio または Visual Studio エンジンとテスト処理エンジンを利用するさまざまな .NET フレームワークに基づいています。テストが確実に正しく実行されるようにする場合は、生成される値の精度を下げるか、生成されたテスト結果と比較する結果を手動で調整する必要があります。

Azure にデプロイ

ARM テンプレートを使用して Stream Analytics プロジェクトをデプロイするには、次の手順に従います。

Azure アカウントに接続します。

# Connect to Azure
Connect-AzAccount
# Set the Azure subscription
Set-AzContext [SubscriptionID/SubscriptionName]

Stream Analytics プロジェクトをデプロイします。

$templateFile = ".\Deploy\ClickStream-Filter.JobTemplate.json"
$parameterFile = ".\Deploy\ClickStream-Filter.JobTemplate.parameters.json"
New-AzResourceGroupDeployment `
  -Name devenvironment `
  -ResourceGroupName myResourceGroupDev `
  -TemplateFile $templateFile `
  -TemplateParameterFile $parameterFile

ARM テンプレートを使用したリソースのデプロイの詳細については、Resource Manager テンプレートファイルと Azure PowerShell を使用したリソースのデプロイに関するページを参照してください。

Stream Analytics プロジェクトのビルド、テスト、デプロイを自動化する

インストール

プロジェクトをビルドする

ローカルで実行する

自動テスト

テストケースを追加する

単体テストを実行する

Azure にデプロイ

次のステップ

その他のリソース

Stream Analytics プロジェクトのビルド、テスト、デプロイを自動化する

インストール

プロジェクトをビルドする

ローカルで実行する

自動テスト

テスト ケースを追加する

単体テストを実行する

Azure にデプロイ

次のステップ

その他のリソース

テストケースを追加する