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 로컬 컴파일러에서 자동으로 찾을 수 있습니다.

    

  • Data Lake Tools for Visual Studio를 설치합니다. 미리 패키지된 Visual C++ 및 Windows SDK 파일은 C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.

    이 경우 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 디렉터리\build\runtime, LocalRunHelper.exe 아래에는 일반적으로 사용되는 대부분의 로컬 실행 함수에 인터페이스를 제공하는 명령줄 도우미 애플리케이션이 있습니다. 명령과 인수 스위치는 모두 대/소문자를 구분합니다. 호출하려면 다음을 수행합니다.

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

인수 없이 또는 도움말 스위치를 사용하여 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

도움말 정보:

• 명령은 명령의 이름을 지정합니다.
• 필수 인수 는 제공해야 하는 인수를 나열합니다.
• 선택적 인수 는 선택 사항인 인수를 기본값으로 나열합니다. 선택적 부울 인수에는 매개 변수가 없으며 해당 인수가 나타나면 기본값의 반대값을 의미합니다.

반환 값 및 로깅

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

환경 변수 구성

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

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

  Visual Studio용 Data Lake Tools를 설치하여 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 명령줄 사용 샘플

컴파일 및 실행

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

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

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

예제는 다음과 같습니다.

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

컴파일 및 실행을 결합하는 것 외에도 컴파일된 실행 파일을 별도로 컴파일하고 실행할 수 있습니다.

U-SQL 스크립트 컴파일

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

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

컴파일에 대한 선택적 인수는 다음과 같습니다.

다음은 몇 가지 사용 예입니다.

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]

다음은 실행을 위한 선택적 인수입니다.

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

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 스크립트 로컬 테스트의 크기를 조정할 수 있습니다. 이 문서에서는 표준 C# 단위 테스트 프로젝트를 사용하여 이러한 인터페이스를 사용하여 U-SQL 스크립트를 테스트하는 방법을 보여 줍니다.

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

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

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

  

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

  

• 테스트 환경을 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 사용을 참조하세요.