自動建置、測試和部署串流分析專案

發行項
03/20/2024

Azure 串流分析 (ASA) CI/CD npm 套件可讓您自動建置、測試及部署串流分析專案。本文示範如何將 npm 套件搭配使用任何 CI/CD 系統。如需使用 Azure DevOPs 設定管線，請參閱使用 Azure DevOps 以針對串流分析作業建立 CI/CD 管線。

如果您沒有串流分析專案，請使用 Visual Studio Code 建立專案，或從 Azure 入口網站匯出現有專案。

安裝

您可以從 npm 網站下載套件，或在終端執行下列命令。

npm install -g azure-streamanalytics-cicd

建置專案

注意

強烈建議您針對更新的 ARM 範本結構描述使用 --v2 選項。更新的結構描述具有較少參數，但會保留與舊版相同的功能。

未來將會取代舊 ARM 範本。從現在起，只有透過 build --v2 建立的範本會收到更新或錯誤 (bug) 修正。

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

build 命令會執行關鍵字語法檢查，並產生 Azure Resource Manager (ARM) 範本。

Argument	描述
`--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

如果專案建置成功，您會在輸出資料夾下看到所建立的兩個 JSON 檔案：

ARM 範本檔案：[ProjectName].JobTemplate.json
ARM 參數檔案：[ProjectName].JobTemplate.parameters.json

parameters.json 檔案預設值來自您的專案設定。如果您想要部署到其他環境，請據以取代值。

所有認證的預設值都是 Null。部署至 Azure 之前，必須先設定這些值。

"Input_EntryStream_sharedAccessPolicyKey": {
  "value": null
}

若要使用 Azure Data Lake Store Gen1 的受控識別作為輸出接收端，您必須在部署至 Azure 之前，使用 PowerShell 提供服務主體的存取權。深入了解如何使用 Resource Manager 範本部署具有受控識別的 ADLS Gen1。

在本機執行

如果您的專案已指定本機輸入檔案，您可以藉由使用 localrun 命令，在本機執行串流分析指令碼。

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

Argument	描述
`--project`	使用絕對或相對路徑指定 asaproj.json 檔案。
`--outputPath`	使用絕對或相對路徑來指定輸出資料夾，藉此儲存 ARM 範本。如果未指定 `outputPath`，範本會放在目前目錄中。
`--customCodeZipFilePath`	C# 自訂程式碼的 ZIP 檔案路徑，例如 UDF 或還原序列化程式 (如果已使用)。將 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 套件來設定和執行串流分析專案的自動化測試。

新增測試案例

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

您可以在測試設定檔中找到測試案例。

Argument	描述
`--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。您可以手動修改此設定。

如果您想要測試驗證以忽略特定輸出，請將預期輸出的 [必要] 欄位設定為 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>]

Argument	描述
`--project`	asaproj.json 檔案的路徑。
`--testConfigPath`	測試設定檔的路徑。如果未指定，將會在 asaproj.json 檔案的目前目錄下方 \test 中，搜尋檔案，其預設檔案名稱為 testConfig.json。
`--outputPath`	測試結果輸出資料夾的路徑。如果未指定，輸出結果檔案會放在目前目錄中。
`--customCodeZipFilePath`	自訂程式碼的 ZIP 檔案路徑，例如 UDF 或還原序列化程式 (如果已使用)。您必須將 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,
}

注意

如果查詢結果包含浮動值，您可能會在產生的值中發現些許差異，這有可能會導致測試失敗。這是以不同 .NET 架構為基礎，其分別為 Visual Studio 和 Visual Studio 引擎及測試處理引擎提供電源。如果您想要確定測試可成功執行，您必須減少所產生值的精確度，或手動將結果與產生的測試結果進行比對。

部署至 Azure

若要使用 ARM 範本部署串流分析專案，請遵循下列步驟：

連線至您的 Azure 帳戶：

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

部署串流分析專案：

$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 部署。

共用方式為

自動建置、測試和部署串流分析專案

安裝

建置專案

在本機執行

自動化測試

新增測試案例

執行單元測試

部署至 Azure

下一步

意見反應

其他資源