次の方法で共有


Azure Data Lake U-SQL SDK を使用して U-SQL の実行およびテストする

重要

Azure Data Lake Analyticsは、2024 年 2 月 29 日に廃止されました。 詳細については、このお知らせを参照してください。

データ分析の場合、organizationは Azure Synapse Analytics または Microsoft Fabric を使用できます。

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 エディションをインストールします。 たとえば C:\Program Files (x86)\Windows Kits\10 のように、Program Files フォルダー内に \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 ローカル実行の Windows 10 SDK

    • 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" がデータルート フォルダーです。

相対パス 絶対パス
/abc/def/input.csv C:\LocalRunDataRoot\abc\def\input.csv
abc/def/input.csv C:\LocalRunDataRoot\abc\def\input.csv
D:/abc/def/input.csv D:\abc\def\input.csv

作業ディレクトリ

U-SQL スクリプトをローカルで実行すると、コンパイル時に、現在実行中のディレクトリの下に作業ディレクトリが作成されます。 この作業ディレクトリには、コンパイル出力だけでなく、ローカル実行に必要なランタイム ファイルがシャドウ コピーされます。 作業ディレクトリのルート フォルダーは "ScopeWorkDir" と呼ばれ、作業ディレクトリには次のファイルが含まれます。

ディレクトリ/ファイル ディレクトリ/ファイル ディレクトリ/ファイル 定義 説明
C6A101DDCB470506 ランタイム バージョンのハッシュ文字列 ローカル実行に必要なランタイム ファイルのシャドウ コピー
Script_66AE4909AA0ED06C スクリプト名 + スクリプト パスのハッシュ文字列 コンパイル出力と実行ステップのログ記録
_script_.abr コンパイラの出力 代数ファイル
_ScopeCodeGen_.* コンパイラの出力 生成されたマネージド コード
_ScopeCodeGenEngine_.* コンパイラの出力 生成されたネイティブ コード
参照されたアセンブリ アセンブリ参照 参照されたアセンブリ ファイル
deployed_resources リソースのデプロイ リソースのデプロイ ファイル
xxxxxxxx.xxx[1..n]_*.* 実行ログ 実行ステップのログ

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

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

run の省略可能な引数を次に示します。

引数 既定値 説明
-分離コード False スクリプトには .cs 分離コードがあります
-CppSDK CppSDK ディレクトリ
-DataRoot DataRoot 環境変数 ローカル実行用の DataRoot。既定値は "LOCALRUN_DATAROOT" 環境変数です
-MessageOut ファイルにダンプされるコンソール上のメッセージ
-Parallel 1 指定された並列処理でプランを実行します
-References 分離コードの追加の参照アセンブリまたはデータ ファイルへのパスから成る、";" で区切られたリスト
-UdoRedirect False Udo アセンブリ リダイレクトの構成を生成します
-UseDatabase master 分離コードの一時アセンブリ登録に使用するデータベース
-Verbose False ランタイムからの詳細な出力を表示します
-WorkDir 現在のディレクトリ コンパイラの使用と出力用のディレクトリ
-RunScopeCEP 0 使用する ScopeCEP モード
-ScopeCEPTempPath temp データをストリーミングするために使用する一時パス
-OptFlags オプティマイザー フラグのコンマ区切りリスト

次に例を示します。

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

compileexecute を組み合わせた方法に加え、コンパイルと、コンパイル済みの実行可能ファイルの実行を個別に行う方法もあります。

U-SQL スクリプトのコンパイル

compile コマンドは、U-SQL スクリプトを実行可能ファイルにコンパイルするために使用します。

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

compileの省略可能な引数を次に示します。

引数 説明
-CodeBehind (既定値 "False") スクリプトには .cs 分離コードがあります
-CppSDK (既定値 "") CppSDK ディレクトリ
-DataRoot [既定値 "DataRoot 環境変数"] ローカル実行用の DataRoot。既定値は "LOCALRUN_DATAROOT" 環境変数です
-MessageOut (既定値 "") ファイルにダンプされるコンソール上のメッセージ
-References (既定値 "") 分離コードの追加の参照アセンブリまたはデータ ファイルへのパスから成る、";" で区切られたリスト
-Shallow (既定値 "False") 簡易コンパイル
-UdoRedirect (既定値 "False") Udo アセンブリ リダイレクトの構成を生成します
-UseDatabase (既定値 "master") 分離コードの一時アセンブリ登録に使用するデータベース
-WorkDir [既定値 "現在のディレクトリ"] コンパイラの使用と出力用のディレクトリ
-RunScopeCEP [既定値 "0"] 使用する ScopeCEP モード
-ScopeCEPTempPath [既定値 "temp"] データをストリーミングするために使用する一時パス
-OptFlags [既定値 ''] オプティマイザー フラグのコンマ区切りリスト

使用例をいくつか以下に示します。

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 の省略可能な引数を次に示します。

引数 既定値 説明
-DataRoot '' メタデータ実行のデータ ルート。 既定値は LOCALRUN_DATAROOT 環境変数です。
-MessageOut '' ファイルにダンプされるコンソール上のメッセージ。
-Parallel '1' 生成されたローカル実行ステップが、指定された並列処理レベルで実行されることを示します。
-Verbose "False" ランタイムから詳細な出力が表示されることを示します。

使用例を次に示します。

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 にあります。

    Azure Data Lake U-SQL SDK での参照の追加

  • U-SQL SDK では x64 環境 のみが サポートされています。ビルド プラットフォームターゲットを x64 に設定してください。 これは、[プロジェクトのプロパティ]、[ビルド]、[プラットフォーム ターゲット] の順に選択することで設定できます。

    Azure Data Lake U-SQL SDK での x64 プロジェクトの構成

  • テスト環境が x64 に設定されていることを確認します。 Visual Studio で、[テスト]、[テストの設定]、[既定のプロセッサ アーキテクチャ]、[x64] の順に選択することで設定できます。

    Azure Data Lake U-SQL SDK での 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 のローカル コンパイルや実行などのプログラミング インターフェイスを提供します。これらのインターフェイスを次に示します。

Constructor

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

パラメーター Type 説明
messageOutput System.IO.TextWriter 出力メッセージ用。コンソールで使用するには null に設定します

Properties

プロパティ Type 説明
AlgebraPath string 代数ファイルへのパス (代数ファイルは、コンパイル結果の 1 つです)
CodeBehindReferences string スクリプトに他の分離コード参照がある場合は、';' で区切られたパスを指定します。
CppSdkDir string CppSDK ディレクトリ
CurrentDir string 現在のディレクトリ
DataRoot string データ ルート パス
DebuggerMailPath string デバッガーのメール スロットのパス
GenerateUdoRedirect [bool] アセンブリ読み込みリダイレクトのオーバーライド構成を生成するかどうかを示します
HasCodeBehind [bool] スクリプトに分離コードがあるかどうか
InputDir string 入力データ用のディレクトリ
MessagePath string メッセージ ダンプ ファイルのパス
OutputDir string 出力データ用のディレクトリ
Parallelism INT 代数を実行する並列処理
ParentPid INT サービスの監視が終了する親の PID。無視する場合は 0 または負数を設定します
ResultPath string 結果ダンプ ファイルのパス
RuntimeDir string ランタイム ディレクトリ
ScriptPath string スクリプトの検出場所
Shallow [bool] 簡易コンパイルかどうか
TempDir string Temp ディレクトリ
UseDataBase string 分離コードの一時アセンブリ登録に使用するデータベース。既定では master
WorkDir string 任意の作業ディレクトリ

Method

Method 説明 戻り値 パラメーター
public bool DoCompile() U-SQL スクリプトをコンパイルします 成功時に True
public bool DoExec() コンパイル結果を実行します 成功時に True
public bool DoRun() U-SQL スクリプトを実行します (コンパイル + 実行) 成功時に True
public bool IsValidRuntimeDir(string path) 指定されたパスが有効なランタイム パスかどうかを確認します 有効な場合は True ランタイム ディレクトリのパス

一般的な問題に関する FAQ

エラー 1

E_CSC_SYSTEM_INTERNAL:内部エラーです。 ファイルを読み込めないか、'ScopeEngineManaged.dll' またはいずれかの依存関係をアセンブルできません。 指定されたモジュールが見つかりません。

次の点を確認します。

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

次のステップ