Azure Data Lake U-SQL SDK를 사용하여 U-SQL 실행 및 테스트

U-SQL 스크립트를 개발할 때 클라우드로 제출하기 전에 로컬에서 U-SQL 스크립트를 실행하고 테스트하는 것이 일반적입니다. Azure Data Lake는 이 시나리오에 대해 Azure Data Lake U-SQL SDK라는 NuGet 패키지를 제공합니다. 이를 통해 U-SQL 실행 및 테스트 규모를 쉽게 조정할 수 있습니다. 이 U-SQL 테스트를 CI(연속 통합) 시스템에 통합하여 컴파일 및 테스트를 자동화할 수도 있습니다.

GUI 도구를 사용하여 U-SQL 스크립트를 수동으로 로컬 실행 및 디버깅하는 방법에 관심이 있는 경우 Azure Data Lake Tools for Visual Studio를 사용할 수 있습니다. 여기에서 자세히 알아볼 수 있습니다.

Azure Data Lake U-SQL SDK 설치

Nuget.org에서 Azure Data Lake U-SQL SDK를 다운로드할 수 있지만 다음 종속성이 있는지 확인한 후 사용해야 합니다.

종속성

Data Lake U-SQL SDK에는 다음과 같은 종속성이 필요합니다.

• Microsoft .NET Framework 4.6 이상.

• Microsoft Visual C++ 14 및 Windows SDK 10.0.10240.0 이상(이 문서에서는 CppSDK로 지칭함). CppSDK는 다음 두 가지 방법으로 다운로드할 수 있습니다.

  • Visual Studio Community Edition을 설치합니다. 프로그램 파일 폴더 아래에 \Windows Kits\10 폴더가 생성됩니다(예: C:\Program Files (x86)\Windows Kits\10). 또한 \Windows Kits\10\Lib 아래에서 Windows 10 SDK 버전을 찾습니다. 이들 폴더가 보이지 않으면 Visual Studio를 다시 설치하고 설치하는 동중 Windows 10 SDK를 선택해야 합니다. Visual Studio와 함께 설치된 경우에는 U-SQL 로컬 컴파일러가 해당 버전을 자동으로 찾습니다.

    

  • Visual Studio용 Data Lake 도구를 설치합니다. C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.에서 미리 패키지된 Visual C++ 및 Windows SDK 파일을 찾을 수 있습니다.

    이 경우 U-SQL 로컬 컴파일러는 이러한 종속성을 자동으로 찾을 수 없습니다. 이에 대한 CppSDK 경로를 지정해야 합니다. 파일을 다른 위치로 복사하거나 그대로 사용할 수 있습니다.

기본 개념 이해

데이터 루트

데이터 루트 폴더는 로컬 컴퓨팅 계정의 "로컬 저장소"입니다. 이는 Data Lake Analytics 계정의 Azure Data Lake Store 계정과 동일합니다. 다른 데이터 루트 폴더로 전환하는 것은 다른 저장소 계정으로 전환하는 것과 같습니다. 다른 데이터 루트 폴더와 공유된 데이터에 액세스하려는 경우 스크립트에서 절대 경로를 사용해야 합니다. 또는 데이터 루트 폴더 아래에 파일 시스템 심볼 링크를 만들어 공유 데이터를 가리키도록 합니다(예, NTFS의 mklink).

데이터 루트 폴더는 다음 용도로 사용됩니다.

• 데이터베이스, 테이블, TVF(테이블 반환 함수), 어셈블리 등의 로컬 메타데이터를 저장합니다.
• U-SQL에서 상대 경로로 정의된 입력 및 출력 경로 조회 - 상대 경로를 사용하면 U-SQL 프로젝트를 Azure에 보다 쉽게 배포할 수 있습니다.

U-SQL의 파일 경로

U-SQL 스크립트의 상대 경로 및 로컬 절대 경로를 사용할 수 있습니다. 상대 경로는 지정된 데이터-루트 폴더 경로 기준으로 하는 것입니다. 스크립트를 서버 쪽과 호환되게 하려면 경로 구분 기호로 "/"를 사용하는 것이 좋습니다. 다음은 상대 경로 및 이와 대등한 절대 경로의 몇 가지 예입니다. 이 예에서 C:\LocalRunDataRoot는 데이터 루트 폴더입니다.

작업 디렉터리

U-SQL 스크립트를 로컬로 실행하면 컴파일 중에 현재 실행 중인 디렉터리 아래에 작업 디렉터리가 만들어집니다. 컴파일 결과 외에도 로컬 실행에 필요한 런타임 파일이 이 작업 디렉터리에 섀도 복사됩니다. 작업 디렉터리 루트 폴더를 "ScopeWorkDir"이라고 하고 작업 디렉터리 아래의 파일은 다음과 같습니다.

명령줄에서 SDK 사용

도우미 애플리케이션의 명령줄 인터페이스

SDK directory\build\runtime에서 LocalRunHelper.exe는 일반적으로 사용되는 대부분의 로컬 실행 기능에 대한 인터페이스를 제공하는 명령줄 도우미 애플리케이션입니다. 명령 및 인수 스위치는 모두 대/소문자를 구분합니다. 도우미를 호출하려면 다음 명령을 사용합니다.

LocalRunHelper.exe <command> <Required-Command-Arguments> [Optional-Command-Arguments]

인수를 사용하지 않거나 다음과 같이 help 스위치와 함께 LocalRunHelper.exe를 실행하여 도움말 정보를 표시합니다.

> LocalRunHelper.exe help
    Command 'help' :  Show usage information
    Command 'compile' :  Compile the script
    Required Arguments :
        -Script param
                Script File Path
    Optional Arguments :
        -Shallow [default value 'False']
                Shallow compile

도움말 정보에서 다음과 같이 구성됩니다.

• Command: 명령의 이름을 제공합니다.
• Required Argument: 제공해야 하는 인수를 나열합니다.
• Optional Argument: 선택적이며 기본값을 갖는 인수를 나열합니다. 선택적 부울 인수에는 매개 변수가 없으며, 이 매개 변수의 출현은 기본값에 부정적이라는 것을 의미합니다.

반환 값 및 로깅

도우미 애플리케이션은 성공한 경우 0을, 실패한 경우 -1을 반환합니다. 기본적으로 도우미는 모든 메시지를 현재 콘솔로 보냅니다. 그러나 대부분의 명령은 출력을 로그 파일로 리디렉션하는 -MessageOut path_to_log_file 선택적 인수를 지원합니다.

환경 변수 구성

U-SQL 로컬 실행을 위해서는 로컬 스토리지 계정으로 지정된 데이터 루트와 종속성에 대해 지정된 CppSDK 경로가 필요합니다. 명령줄에서 인수를 설정하고 그에 대한 환경 변수를 설정할 수 있습니다.

• SCOPE_CPP_SDK 환경 변수를 설정합니다.

  Data Lake Tools for Visual Studio를 설치하여 Microsoft Visual C++ 및 Windows SDK를 가져온 경우 다음 폴더가 있는지 확인합니다.

  C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\Microsoft Azure Data Lake Tools for Visual Studio 2015\X.X.XXXX.X\CppSDK

  이 디렉터리를 가리키도록 SCOPE_CPP_SDK라는 새로운 환경 변수를 정의합니다. 또는 다른 위치에 폴더를 복사하고 SCOPE_CPP_SDK를 지정합니다.

  환경 변수를 설정하는 것 외에도 명령줄을 사용할 때 -CppSDK 인수를 지정할 수도 있습니다. 이 인수는 기본 CppSDK 환경 변수를 덮어씁니다.

• LOCALRUN_DATAROOT 환경 변수를 설정합니다.

  데이터 루트를 가리키는 LOCALRUN_DATAROOT라는 새로운 환경 변수를 정의합니다.

  환경 변수를 설정하는 것 외에도 명령줄을 사용할 때 데이터 루트 경로로 -DataRoot 인수를 지정할 수 있습니다. 이 인수는 기본 데이터 루트 환경 변수를 덮어씁니다. 모든 작업에 대해 기본 데이터 루트 환경 변수를 덮어 쓸 수 있도록 실행 중인 모든 명령줄에 이 인수를 추가해야 합니다.

SDK 명령줄 사용 샘플

컴파일 및 실행

run 명령은 스크립트를 컴파일한 다음 컴파일 결과를 실행하는 데 사용됩니다. 명령줄 인수는 compile과 execute의 조합입니다.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

다음은 run에 대한 선택적 인수입니다.

예를 들면 다음과 같습니다.

LocalRunHelper run -Script d:\test\test1.usql -WorkDir d:\test\bin -CodeBehind -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB –Parallel 5 -Verbose

compile과 execute를 조합하는 것 외에도 컴파일된 실행 파일을 개별적으로 컴파일하고 실행할 수 있습니다.

U-SQL 스크립트 컴파일

compile 명령은 U-SQL 스크립트를 실행 파일로 컴파일하는 데 사용됩니다.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

다음은 compile에 대한 선택적 인수입니다.

몇 가지 사용 예제는 다음과 같습니다.

U-SQL 스크립트를 컴파일합니다.

LocalRunHelper compile -Script d:\test\test1.usql

U-SQL 스크립트를 컴파일하고 데이터 루트 폴더를 설정합니다. 이렇게 하면 환경 변수 설정을 덮어씁니다.

LocalRunHelper compile -Script d:\test\test1.usql –DataRoot c:\DataRoot

U-SQL 스크립트를 컴파일하고 작업 디렉터리, 참조 어셈블리 및 데이터베이스를 설정합니다.

LocalRunHelper compile -Script d:\test\test1.usql -WorkDir d:\test\bin -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB

컴파일된 결과 실행

execute 명령은 컴파일된 결과를 실행하는 데 사용됩니다.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

다음은 compile에 대한 선택적 인수입니다.

사용 예는 다음과 같습니다.

LocalRunHelper execute -Algebra d:\test\workdir\C6A101DDCB470506\Script_66AE4909AA0ED06C\__script__.abr –DataRoot c:\DataRoot –Parallel 5

프로그래밍 인터페이스와 함께 SDK 사용

프로그래밍 인터페이스는 모두 LocalRunHelper.exe에 있습니다. 이 인터페이스를 사용하여 U-SQL SDK 및 C# 테스트 프레임워크의 기능을 통합하여 U-SQL 스크립트 로컬 테스트의 크기를 조정할 수 있습니다. 이 문서에서는 이러한 인터페이스를 사용하여 U-SQL 스크립트를 테스트하는 방법을 보여 주기 위해 표준 C# 단위 테스트 프로젝트를 사용합니다.

1단계: C# 단위 테스트 프로젝트 및 구성 만들기

• 파일 > 새로 만들기 > 프로젝트 > Visual C# > 테스트 > 단위 테스트 프로젝트를 통해 C# 단위 테스트 프로젝트를 만듭니다.

• 프로젝트에 대한 참조로 LocalRunHelper.exe를 추가합니다. LocalRunHelper.exe는 NuGet 패키지의 \build\runtime\LocalRunHelper.exe에 있습니다.

  

• U-SQL SDK는 x64 환경만 지원합니다. 따라서 빌드 플랫폼 대상을 x64로 설정해야 합니다. 프로젝트 속성 > 빌드 > 플랫폼 대상을 통해 설정할 수 있습니다.

  

• 테스트 환경을 x64로 설정해야 합니다. Visual Studio에서 테스트 > 테스트 설정 > 기본 프로세서 아키텍처 > x64를 통해 설정할 수 있습니다.

  

• NugetPackage\build\runtime\ 아래에 있는 모든 종속성 파일을 일반적으로 ProjectFolder\bin\x64\Debug 아래에 있는 프로젝트 작업 디렉터리로 복사해야 합니다.

2단계: U-SQL 스크립트 테스트 사례 만들기

다음은 U-SQL 스크립트 테스트에 대한 샘플 코드입니다. 테스트를 위해 스크립트, 입력 파일 및 예상 출력 파일을 준비해야 합니다.

using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System.IO;
using System.Text;
using System.Security.Cryptography;
using Microsoft.Analytics.LocalRun;
namespace UnitTestProject1
{
    [TestClass]
    public class USQLUnitTest
    {
        [TestMethod]
        public void TestUSQLScript()
        {
            //Specify the local run message output path
            StreamWriter MessageOutput = new StreamWriter("../../../log.txt");
            LocalRunHelper localrun = new LocalRunHelper(MessageOutput);
            //Configure the DateRoot path, Script Path and CPPSDK path
            localrun.DataRoot = "../../../";
            localrun.ScriptPath = "../../../Script/Script.usql";
            localrun.CppSdkDir = "../../../CppSDK";
            //Run U-SQL script
            localrun.DoRun();
            //Script output
            string Result = Path.Combine(localrun.DataRoot, "Output/result.csv");
            //Expected script output
            string ExpectedResult = "../../../ExpectedOutput/result.csv";
            Test.Helpers.FileAssert.AreEqual(Result, ExpectedResult);
            //Don't forget to close MessageOutput to get logs into file
            MessageOutput.Close();
        }
    }
}
namespace Test.Helpers
{
    public static class FileAssert
    {
        static string GetFileHash(string filename)
        {
            Assert.IsTrue(File.Exists(filename));
            using (var hash = new SHA1Managed())
            {
                var clearBytes = File.ReadAllBytes(filename);
                var hashedBytes = hash.ComputeHash(clearBytes);
                return ConvertBytesToHex(hashedBytes);
            }
        }
        static string ConvertBytesToHex(byte[] bytes)
        {
            var sb = new StringBuilder();
            for (var i = 0; i < bytes.Length; i++)
            {
                sb.Append(bytes[i].ToString("x"));
            }
            return sb.ToString();
        }
        public static void AreEqual(string filename1, string filename2)
        {
            string hash1 = GetFileHash(filename1);
            string hash2 = GetFileHash(filename2);
            Assert.AreEqual(hash1, hash2);
        }
    }
}

LocalRunHelper.exe의 프로그래밍 인터페이스

LocalRunHelper.exe는 U-SQL 로컬 컴파일, 실행 등을 위한 프로그래밍 인터페이스를 제공합니다. 인터페이스는 다음과 같습니다.

생성자

public LocalRunHelper([System.IO.TextWriter messageOutput = null])

속성

방법

일반적인 문제에 대한 FAQ

오류 1

E_CSC_SYSTEM_INTERNAL: 내부 오류입니다. 파일 또는 어셈블리 'ScopeEngineManaged.dll'이나 해당 종속성 중 하나를 로드할 수 없습니다. 지정된 모듈을 찾을 수 없습니다.

다음 사항을 확인합니다.

• X64 환경인지 확인합니다. 빌드 대상 플랫폼 및 테스트 환경은 x64여야 합니다. 위의 1단계: C# 단위 테스트 프로젝트 및 구성 만들기를 참조하세요.
• NugetPackage\build\runtime\ 아래의 모든 종속 파일을 프로젝트 작업 디렉터리로 복사했는지 확인합니다.

다음 단계

• U-SQL을 알아보려면 Azure Data Lake Analytics U-SQL 언어 시작을 참조하세요.
• 진단 정보를 기록하려면 Azure Data Lake Analytics에 대한 진단 로그에 액세스를 참조하세요.
• 더 복잡한 쿼리를 보려면 Azure Data Lake Analytics을 사용하여 웹 사이트 로그 분석을 참조하세요.
• 작업 세부 정보를 보려면, Azure Data lake Analytics 작업에 대한 작업 브라우저 및 작업 보기 사용하기를 참조하세요.
• 꼭짓점 실행 보기를 사용하려면 Data Lake Tools for Visual Studio에서 Vertex Execution View 사용을 참조하세요.