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 をインストールする

Azure Data Lake U-SQL SDK は、Nuget.org で入手 できます。使用する前に、次のように依存関係があることを確認する必要があります。

依存関係

Data Lake U-SQL SDK には、次の依存関係が必要です。

• Microsoft .NET Framework 4.6 以降。

• Microsoft Visual C++ 14 および Windows SDK 10.0.10240.0 以降 (この記事では CppSDK と呼ばれます)。 CppSDK を取得するには、次の 2 つの方法があります。

  • Visual Studio Community Edition をインストールします。 Program Files フォルダーの下に \Windows Kits\10 フォルダーがあります。たとえば、C:\Program Files (x86)\Windows Kits\10 などです。 Windows 10 SDK のバージョンは、\Windows Kits\10\Lib にあります。 これらのフォルダーが表示されない場合は、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環境変数を設定します。

  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 コマンドを使用してスクリプトをコンパイルし、コンパイルされた結果を実行します。 そのコマンド ライン引数は、 コンパイル と 実行からの引数の組み合わせです。

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

コンパイルと実行を組み合わせるだけでなく、コンパイルされた実行可能ファイルを個別にコンパイルして実行することもできます。

U-SQL スクリプトをコンパイルする

compile コマンドは、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]

execute のオプションの引数は以下の通りです。

使用例を次に示します。

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# 単体テスト プロジェクトと構成を作成する

• C# 単体テスト プロジェクトを作成するには、File > New > Project > Visual C# > Test > Unit Test Project を選択します。

• プロジェクトの参照として LocalRunHelper.exe を追加します。 LocalRunHelper.exe は NuGet パッケージの \build\runtime\LocalRunHelper.exe にあります。

  

• U-SQL SDK は x64 環境 のみを サポートし、ビルド プラットフォームのターゲットを x64 として設定してください。 これは、プロジェクト プロパティ > Build > Platform ターゲットを使用して設定できます。

  

• テスト環境を 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' またはその依存関係の 1 つを読み込めませんでした。 指定されたモジュールが見つかりません。

次のことを確認します。

• x64 環境があることを確認します。 ビルド ターゲット プラットフォームとテスト環境は x64 にする必要があります。上記の 「手順 1: C# 単体テスト プロジェクトと構成を作成 する」を参照してください。
• NugetPackage\build\runtime\ のすべての依存関係ファイルがプロジェクト作業ディレクトリにコピーされていることを確認します。

次のステップ

• U-SQL の詳細については、「 Azure Data Lake Analytics U-SQL 言語の概要」を参照してください。
• 診断情報をログに記録するには、「 Azure Data Lake Analytics の診断ログへのアクセス」を参照してください。
• より複雑なクエリを表示するには、「 Azure Data Lake Analytics を使用した Web サイト ログの分析」を参照してください。
• ジョブの詳細を表示するには、「 Azure Data Lake Analytics ジョブのジョブ ブラウザーとジョブ ビューを使用する」を参照してください。
• 頂点実行ビューを使用するには、「 Data Lake Tools for Visual Studio で頂点実行ビューを使用する」を参照してください。