Stream Analytics 프로젝트의 빌드, 테스트 및 배포 자동화

아티클
03/07/2024

ASA(Azure Stream Analytics) 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 명령은 키워드 구문 검사를 수행하고 ARM(Azure Resource Manager) 템플릿을 생성합니다.

인수	설명
`--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용 관리 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 를 지정 해야 합니다. 이 구성을 수동으로 수정할 수 있습니다.

테스트 유효성 검사에서 특정 출력을 무시하도록 하려면 예상 출력의 필수 필드를 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,
}

참고 항목

쿼리 결과에 부동 소수점 값이 포함된 경우 생성된 값에 약간의 차이가 발생하여 테스트에 실패할 수 있습니다. 이는 Visual Studio 또는 Visual Studio 엔진과 테스트 처리 엔진을 구동하는 다양한 .Net Frameworks를 기반으로 합니다. 테스트가 성공적으로 실행되도록 하려면 생성된 값의 정밀도를 낮추거나 생성된 테스트 결과와 수동으로 비교할 결과를 정렬해야 합니다.

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에 배포

다음 단계

추가 리소스