A U-SQL futtatása és tesztelése az Azure Data Lake U-SQL SDK-val

Fontos

Az Azure Data Lake Analytics 2024. február 29-én megszűnt. További információ ezzel a bejelentéssel.

Az adatelemzéshez a szervezet használhatja a Azure Synapse Analyticset vagy a Microsoft Fabricet.

Az U-SQL-szkript fejlesztésekor gyakran előfordul, hogy helyileg futtatja és teszteli az U-SQL-szkriptet, mielőtt elküldené a felhőbe. Az Azure Data Lake egy Azure Data Lake U-SQL SDK nevű NuGet-csomagot biztosít ehhez a forgatókönyvhöz, amelyen keresztül egyszerűen skálázhatja az U-SQL-futtatást és a tesztelést. Ez az U-SQL-teszt integrálható a CI (Folyamatos integráció) rendszerrel a fordítás és a tesztelés automatizálásához.

Ha érdekli a helyi futtatás és az U-SQL-szkriptek manuális hibakeresése a GUI-eszközökkel, akkor ehhez használhatja az Azure Data Lake Tools for Visual Studiót. További információt itt talál.

Az Azure Data Lake U-SQL SDK telepítése

Az Azure Data Lake U-SQL SDK-t itt szerezheti be a Nuget.org. A használat előtt meg kell győződnie arról, hogy az alábbiak szerint rendelkezik függőségekkel.

Függőségek

A Data Lake U-SQL SDK-nak a következő függőségekre van szüksége:

• Microsoft .NET-keretrendszer 4.6 vagy újabb.

• Microsoft Visual C++ 14 és Windows SDK 10.0.10240.0 vagy újabb (a jelen cikkben CppSDK néven ismert). A CppSDK kétféleképpen szerezhető be:

  • Telepítse Visual Studio Community Editiont. A Program Files mappa alatt egy \Windows Kits\10 mappa található – például C:\Program Files (x86)\Windows Kits\10. A Windows 10 SDK-verziót a \Windows Kits\10\Lib területen találja. Ha nem látja ezeket a mappákat, telepítse újra a Visual Studiót, és a telepítés során mindenképpen válassza ki a Windows 10 SDK-t. Ha ezt a Visual Studióval telepítette, az U-SQL helyi fordítója automatikusan megtalálja.

    

  • Telepítse a Data Lake Tools for Visual Studiót. Az előre csomagolt Visual C++ és Windows SDK fájlokat itt találja:C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.

    Ebben az esetben az U-SQL helyi fordítója nem találja automatikusan a függőségeket. Meg kell adnia a CppSDK elérési útját. A fájlokat átmásolhatja egy másik helyre, vagy használhatja az adott helyen.

Alapfogalmak ismertetése

Adatgyökér

Az adatgyökér mappa a helyi számítási fiók "helyi tárolója". Ez egyenértékű egy Data Lake Analytics fiók Azure Data Lake Store-fiókjával. Ha másik adatgyökerű mappára vált, az olyan, mintha másik tárfiókra váltana. Ha a gyakran megosztott adatokat különböző adatgyökerű mappákkal szeretné elérni, abszolút elérési utakat kell használnia a szkriptekben. Vagy hozzon létre fájlrendszerbeli szimbolikus hivatkozásokat (például mklink NTFS-en) az adatgyökerű mappa alatt, hogy a megosztott adatokra mutasson.

Az adatgyökér mappa a következőre szolgál:

• Tárolhatja a helyi metaadatokat, beleértve az adatbázisokat, táblákat, táblaértékű függvényeket (TVF-eket) és szerelvényeket.
• Keresse meg a relatív elérési utakként definiált bemeneti és kimeneti elérési utakat az U-SQL-ben. A relatív elérési utak használatával egyszerűbben helyezheti üzembe U-SQL-projektjeit az Azure-ban.

Fájl elérési útja az U-SQL-ben

U-SQL-szkriptekben relatív és helyi abszolút elérési utat is használhat. A relatív elérési út a megadott data-root mappa elérési úthoz van viszonyítva. Javasoljuk, hogy a "/" karaktert használja elérésiút-elválasztóként, hogy a szkriptek kompatibilisek legyenek a kiszolgálóoldallal. Íme néhány példa a relatív elérési utakra és azok egyenértékű abszolút elérési útjaira. Ezekben a példákban a C:\LocalRunDataRoot az adatgyökér mappa.

Relatív elérési út	Abszolút elérési út
/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

Munkakönyvtár

Az U-SQL-szkript helyi futtatásakor egy munkakönyvtár jön létre a fordítás során az aktuálisan futó könyvtárban. A fordítási kimenetek mellett a helyi végrehajtáshoz szükséges futtatókörnyezeti fájlok árnyékolva lesznek ebbe a munkakönyvtárba. A munkakönyvtár gyökérmappájának neve "ScopeWorkDir", a munkakönyvtárban lévő fájlok pedig a következők:

Könyvtár/fájl	Könyvtár/fájl	Könyvtár/fájl	Definíció	Description
C6A101DDCB470506			A futtatókörnyezet verziójának kivonatsztringje	A helyi végrehajtáshoz szükséges futtatókörnyezeti fájlok árnyékmásolata
	Script_66AE4909AA0ED06C		Szkript neve és a szkript elérési útjának kivonatsztringje	Kimenetek fordítása és végrehajtási lépés naplózása
		_script_.abr	Fordító kimenete	Algebra-fájl
		_ScopeCodeGen_.*	Fordító kimenete	Létrehozott felügyelt kód
		_ScopeCodeGenEngine_.*	Fordító kimenete	Létrehozott natív kód
		hivatkozott szerelvények	Szerelvény referenciája	Hivatkozott szerelvényfájlok
		deployed_resources	Erőforrás üzembe helyezése	Erőforrás-üzembehelyezési fájlok
		xxxxxxxx.xxx[1..n]_*.*	Végrehajtási napló	Végrehajtási lépések naplója

Az SDK használata a parancssorból

A segédalkalmazás parancssori felülete

Az SDK directory\build\runtime területen a LocalRunHelper.exe a parancssori segédalkalmazás, amely interfészeket biztosít a leggyakrabban használt helyi futtatású függvényekhez. A parancs és az argumentumkapcsolók egyaránt megkülönböztetik a kis- és nagybetűket. Meghívása:

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

Futtassa LocalRunHelper.exe argumentumok nélkül vagy a súgókapcsolóval a súgóinformációk megjelenítéséhez:

> 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

A súgóban:

• A parancs megadja a parancs nevét.
• A kötelező argumentumok a megadandó argumentumokat sorolják fel.
• A Nem kötelező argumentumok az alapértelmezett értékekkel listázza a nem kötelező argumentumokat. Az opcionális logikai argumentumok nem rendelkeznek paraméterekkel, és a megjelenéseik negatívak az alapértelmezett értékükre.

Érték visszaadott értéke és naplózása

A segédalkalmazás 0-t ad vissza a sikerességhez, a -1-et pedig a sikertelenséghez. Alapértelmezés szerint a segítő az összes üzenetet az aktuális konzolra küldi. A parancsok többsége azonban támogatja a -MessageOut path_to_log_file opcionális argumentumot, amely átirányítja a kimeneteket egy naplófájlba.

Környezeti változó konfigurálása

A helyi U-SQL-futtatáshoz egy megadott adatgyökerre van szükség helyi tárfiókként, valamint egy megadott CppSDK-elérési útra a függőségekhez. Az argumentumot a parancssorban is beállíthatja, vagy környezeti változót is beállíthat hozzájuk.

• Állítsa be a SCOPE_CPP_SDK környezeti változót.

  Ha a Microsoft Visual C++ és a Windows SDK a Data Lake Tools for Visual Studio telepítésével kapja meg, ellenőrizze, hogy a következő mappával rendelkezik-e:

  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

  Definiáljon egy SCOPE_CPP_SDK nevű új környezeti változót, amely erre a könyvtárra mutat. Vagy másolja a mappát a másik helyre, és adja meg a SCOPE_CPP_SDK .

  A környezeti változó beállítása mellett a -CppSDK argumentumot is megadhatja a parancssor használatakor. Ez az argumentum felülírja az alapértelmezett CppSDK környezeti változót.

• Állítsa be a LOCALRUN_DATAROOT környezeti változót.

  Definiáljon egy LOCALRUN_DATAROOT nevű új környezeti változót, amely az adatgyökerre mutat.

  A környezeti változó beállítása mellett a -DataRoot argumentumot is megadhatja az adatgyökér elérési útjával, amikor parancssort használ. Ez az argumentum felülírja az alapértelmezett data-root környezeti változót. Ezt az argumentumot minden futtatott parancssorhoz hozzá kell adnia, hogy felülírhassa az alapértelmezett adatgyökerező környezeti változót az összes művelethez.

SDK parancssori használati minták

Fordítás és futtatás

A futtatási parancs a szkript fordítására, majd a lefordított eredmények végrehajtására szolgál. A parancssori argumentumai a fordításból és végrehajtásból származó argumentumok kombinációja.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

A futtatáshoz az alábbi argumentumok választhatók:

Argumentum	Alapértelmezett érték	Description
-CodeBehind	Hamis	A szkript mögött .cs kód található
-CppSDK		CppSDK-címtár
-DataRoot	DataRoot környezeti változó	DataRoot helyi futtatáshoz, alapértelmezés szerint "LOCALRUN_DATAROOT" környezeti változó
-MessageOut		Üzenetek memóriaképe a konzolon egy fájlba
-Párhuzamos	1	A terv futtatása a megadott párhuzamossággal
-Hivatkozások		A további referenciaszerelvényekhez vagy a mögöttes kód adatfájljaihoz vezető elérési utak listája, ";" elválasztva
-UdoRedirect	Hamis	Udo-szerelvény átirányítási konfigurációjának létrehozása
-UseDatabase	master	Az ideiglenes szerelvényregisztráció mögötti kódhoz használandó adatbázis
-Részletes	Hamis	Részletes kimenetek megjelenítése a futtatókörnyezetből
-WorkDir	Aktuális könyvtár	Könyvtár a fordítók használatához és kimeneteihez
-RunScopeCEP	0	Használandó ScopeCEP mód
-ScopeCEPTempPath	temp	Streamelési adatokhoz használandó ideiglenes elérési út
-OptFlags		Optimalizáló jelzők vesszővel tagolt listája

Bemutatunk egy példát:

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

A fordítás és a végrehajtás kombinálása mellett a lefordított végrehajtható elemeket külön is lefordíthatja és végrehajthatja.

U-SQL-szkript fordítása

A fordítási parancs egy U-SQL-szkript végrehajtható fájlokhoz való fordítására szolgál.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

A fordításhoz a következő választható argumentumok használhatók:

Argumentum	Description
-CodeBehind [alapértelmezett "False" érték]	A szkript mögött .cs kód található
-CppSDK [alapértelmezett érték"	CppSDK-címtár
-DataRoot [alapértelmezett érték "DataRoot környezeti változó"	DataRoot helyi futtatáshoz, alapértelmezés szerint "LOCALRUN_DATAROOT" környezeti változó
-MessageOut [alapértelmezett érték"	Üzenetek memóriaképe a konzolon egy fájlba
-Hivatkozások [alapértelmezett érték"	A további referenciaszerelvényekhez vagy a mögöttes kód adatfájljaihoz vezető elérési utak listája, ";" elválasztva
-Shallow [alapértelmezett érték "False"	Sekély fordítás
-UdoRedirect [alapértelmezett "False" érték]	Udo-szerelvény átirányítási konfigurációjának létrehozása
-UseDatabase [default value 'master]	Az ideiglenes szerelvényregisztráció mögötti kódhoz használandó adatbázis
-WorkDir [alapértelmezett érték " Current Directory"	Könyvtár a fordítók használatához és kimeneteihez
-RunScopeCEP [alapértelmezett érték: '0]	Használandó ScopeCEP mód
-ScopeCEPTempPath [alapértelmezett "temp" érték]	Streamelési adatokhoz használandó ideiglenes elérési út
-OptFlags [alapértelmezett érték"	Optimalizáló jelzők vesszővel tagolt listája

Íme néhány használati példa.

U-SQL-szkript fordítása:

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

Állítson össze egy U-SQL-szkriptet, és állítsa be az adatgyökér mappát. Ez felülírja a beállított környezeti változót.

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

Állítson össze egy U-SQL-szkriptet, és állítson be egy munkakönyvtárat, referenciaszerelvényt és adatbázist:

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

Lefordított eredmények végrehajtása

A végrehajtási parancs a lefordított eredmények végrehajtására szolgál.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

A végrehajtáshoz az alábbi argumentumok választhatók:

Argumentum	Alapértelmezett érték	Description
-DataRoot	''	A metaadatok végrehajtásának adatgyökere. Alapértelmezés szerint a LOCALRUN_DATAROOT környezeti változó.
-MessageOut	''	Üzenetek memóriaképe a konzolon egy fájlba.
-Párhuzamos	'1'	A létrehozott helyi futtatási lépések a megadott párhuzamossági szinttel való futtatására mutató.
-Részletes	"Hamis"	Mutató a futtatókörnyezetből származó részletes kimenetek megjelenítéséhez.

Íme egy használati példa:

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

Az SDK használata programozási felületekkel

A programozási felületek mind a LocalRunHelper.exe találhatók. A használatával integrálhatja az U-SQL SDK és a C# tesztkeret funkcióit az U-SQL-szkript helyi tesztjének skálázásához. Ebben a cikkben a standard C# egységtesztelési projektet használom, amely bemutatja, hogyan használhatja ezeket a felületeket az U-SQL-szkript teszteléséhez.

1. lépés: C#-egység tesztprojekt létrehozása és konfigurálása

• Hozzon létre egy C#-egység tesztprojektet a File > New > Project > Visual C# > Test > Unit Test Project projekten keresztül.

• Adja hozzá LocalRunHelper.exe a projekt hivatkozásaként. A LocalRunHelper.exe a NuGet-csomagban \build\runtime\LocalRunHelper.exe található.

  

• Az U-SQL SDK csak az x64-környezetet támogatja, ügyeljen arra, hogy a buildplatform-célértéket x64-ként állítsa be. Ezt a Project Property > Build > Platform-célon keresztül állíthatja be.

  

• Ügyeljen arra, hogy a tesztkörnyezetet x64-ként állítsa be. A Visual Studióban a Tesztbeállítások >> alapértelmezett processzorarchitektúra > x64-ben állítható be.

  

• Mindenképpen másolja a NugetPackage\build\runtime\ alatti összes függőségfájlt a Project Working Directoryba, amely általában a ProjectFolder\bin\x64\Debug mappában található.

2. lépés: U-SQL-szkripttesztelési eset létrehozása

Az alábbiakban látható az U-SQL-szkriptteszt mintakódja. A teszteléshez elő kell készítenie a szkripteket, a bemeneti fájlokat és a várt kimeneti fájlokat.

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);
        }
    }
}

Programozási felületek LocalRunHelper.exe

LocalRunHelper.exe biztosítja az U-SQL helyi fordításához, futtatásához stb. használható programozási felületeket. Az interfészek az alábbiak szerint vannak felsorolva.

Konstruktor

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

Paraméter	Típus	Description
messageOutput	System.IO.TextWriter	kimeneti üzenetek esetén állítsa null értékre a Konzol használatához

Tulajdonságok

Tulajdonság	Típus	Description
AlgebraPath	sztring	Az algebrafájl elérési útja (az algebra fájl az egyik fordítási eredmény)
CodeBehindReferences	sztring	Ha a szkript más kóddal rendelkezik a hivatkozások mögött, adja meg az elérési utakat a következővel: ";"
CppSdkDir	sztring	CppSDK-könyvtár
CurrentDir	sztring	Aktuális könyvtár
DataRoot	sztring	Adatgyökér elérési útja
DebuggerMailPath	sztring	A mailslot hibakeresőjének elérési útja
GenerateUdoRedirect	logikai	Ha szerelvénybetöltés átirányítási felülbírálási konfigurációt szeretnénk létrehozni
HasCodeBehind	logikai	Ha a szkript mögött kód található
InputDir	sztring	Bemeneti adatok könyvtára
MessagePath	sztring	Üzenetképfájl elérési útja
OutputDir	sztring	Kimeneti adatok könyvtára
Párhuzamosság	int	Párhuzamosság az algebra futtatásához
ParentPid	int	Annak a szülőnek a PID-értéke, amelyen a szolgáltatás ki szeretne lépni, 0 vagy negatív értékre van állítva, hogy figyelmen kívül hagyja
ResultPath	sztring	Eredményképfájl elérési útja
RuntimeDir	sztring	Futtatókörnyezet könyvtára
ScriptPath	sztring	Hol található a szkript?
Sekély	logikai	Sekély fordítás vagy sem
TempDir	sztring	Ideiglenes könyvtár
UseDataBase	sztring	Adja meg az ideiglenes szerelvényregisztráció mögötti kódhoz használandó adatbázist, alapértelmezés szerint főkiszolgáló
WorkDir	sztring	Előnyben részesített munkakönyvtár

Metódus

Metódus	Leírás	Visszaküldés	Paraméter
public bool DoCompile()	Az U-SQL-szkript fordítása	Igaz a sikerre
public bool DoExec()	A lefordított eredmény végrehajtása	Igaz a sikerre
nyilvános bool DoRun()	Futtassa az U-SQL-szkriptet (Fordítás és végrehajtás)	Igaz a sikerre
public bool IsValidRuntimeDir(sztring elérési útja)	Ellenőrizze, hogy a megadott útvonal érvényes futtatókörnyezeti elérési út-e	Érvényes érték esetén igaz	A futtatókörnyezeti könyvtár elérési útja

Gyakori kérdések a gyakori problémáról

1.hiba

E_CSC_SYSTEM_INTERNAL: Belső hiba! Nem tölthető be a fájl vagy a szerelvény "ScopeEngineManaged.dll" vagy valamelyik függősége. A megadott modul nem található.

Ellenőrizze az alábbiakat:

• Győződjön meg arról, hogy x64-környezettel rendelkezik. A build célplatformjának és a tesztkörnyezetnek x64-nek kell lennie, lásd a fenti 1. lépés: C# egységtesztelési projekt és konfiguráció létrehozása című szakaszt .
• Győződjön meg arról, hogy a NugetPackage\build\runtime\ alatt található összes függőségfájlt átmásolta a project working directoryba.

Következő lépések

• A U-SQL nyelv megismerése: Get started with Azure Data Lake Analytics U-SQL language (Ismerkedés az Azure Data Lake Analytics U-SQL nyelvével).
• A diagnosztikai adatok naplózásához lásd: Az Azure Data Lake Analytics diagnosztikai naplóinak elérése.
• Egy összetettebb lekérdezés megtekintéséhez lásd: Webhelynaplók elemzése az Azure Data Lake Analytics használatával.
• A feladatok részleteinek megtekintéséhez lásd: A Feladatböngésző és a Feladatnézet használata Azure-Data Lake Analytics-feladatokhoz.
• A csúcsvégrehajtási nézet használatához lásd : Csúcsvégrehajtási nézet használata a Data Lake Tools for Visual Studióban.