Uruchamianie i testowanie języka U-SQL przy użyciu zestawu AZURE Data Lake U-SQL SDK
Ważne
Usługa Azure Data Lake Analytics została wycofana 29 lutego 2024 r. Dowiedz się więcej z tym ogłoszeniem.
W przypadku analizy danych organizacja może używać Azure Synapse Analytics lub Microsoft Fabric.
Podczas tworzenia skryptu U-SQL często uruchamia się i testuje skrypt U-SQL lokalnie przed przesłaniem go do chmury. Usługa Azure Data Lake udostępnia pakiet NuGet o nazwie Azure Data Lake U-SQL SDK dla tego scenariusza, za pomocą którego można łatwo skalować uruchamianie i testowanie języka U-SQL. Istnieje również możliwość zintegrowania tego testu U-SQL z systemem ciągłej integracji (ciągła integracja), aby zautomatyzować kompilowanie i testowanie.
Jeśli interesuje Cię ręczne uruchamianie lokalne i debugowanie skryptu U-SQL za pomocą narzędzi graficznego interfejsu użytkownika, możesz użyć Azure Data Lake Tools for Visual Studio tego celu. Więcej informacji można znaleźć tutaj.
Instalowanie zestawu AZURE Data Lake U-SQL SDK
Zestaw SDK U-SQL usługi Azure Data Lake można uzyskać tutaj w Nuget.org. Przed użyciem należy upewnić się, że masz zależności w następujący sposób.
Zależności
Zestaw SDK języka U-SQL usługi Data Lake wymaga następujących zależności:
Microsoft Visual C++ 14 i Windows SDK 10.0.10240.0 lub nowsze (czyli CppSDK w tym artykule). Istnieją dwa sposoby pobierania zestawu CppSDK:
Zainstaluj Visual Studio Community Edition. W folderze Program Files znajduje się folder \Windows Kits\10— na przykład C:\Program Files (x86)\Windows Kits\10. Znajdziesz również wersję zestawu SDK Windows 10 w obszarze \Windows Kits\10\Lib. Jeśli te foldery nie są widoczne, zainstaluj ponownie program Visual Studio i podczas instalacji wybierz zestaw SDK Windows 10. Jeśli masz to zainstalowane w programie Visual Studio, lokalny kompilator U-SQL znajdzie go automatycznie.
Zainstaluj narzędzia Data Lake Tools for Visual Studio. Wstępnie spakowane pliki Visual C++ i Windows SDK można znaleźć na stronie
C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.W takim przypadku lokalny kompilator U-SQL nie może automatycznie znaleźć zależności. Należy określić dla niego ścieżkę CppSDK. Możesz skopiować pliki do innej lokalizacji lub użyć jej tak, jak to jest.
Omówienie podstawowych pojęć
Katalog główny danych
Folder główny danych jest "magazynem lokalnym" dla lokalnego konta obliczeniowego. Jest to równoważne kontu usługi Azure Data Lake Store konta Data Lake Analytics. Przełączanie do innego folderu głównego danych jest tak samo jak przełączenie na inne konto magazynu. Jeśli chcesz uzyskać dostęp do często udostępnianych danych innym folderom głównym danych, musisz użyć ścieżek bezwzględnych w skryptach. Możesz też utworzyć łącza symboliczne systemu plików (na przykład mklink w systemie plików NTFS) w folderze głównym danych w celu wskazania udostępnionych danych.
Folder główny danych jest używany do:
- Przechowuj metadane lokalne, w tym bazy danych, tabele, funkcje wartości tabeli (TVFs) i zestawy.
- Wyszukaj ścieżki wejściowe i wyjściowe zdefiniowane jako ścieżki względne w języku U-SQL. Użycie ścieżek względnych ułatwia wdrażanie projektów U-SQL na platformie Azure.
Ścieżka pliku w języku U-SQL
Ścieżkę względną i lokalną ścieżkę bezwzględną można użyć w skryptach U-SQL. Ścieżka względna jest względna względem określonej ścieżki folderu głównego danych. Zalecamy użycie ciągu "/" jako separatora ścieżki, aby skrypty były zgodne z stroną serwera. Oto kilka przykładów ścieżek względnych i ich równoważnych ścieżek bezwzględnych. W tych przykładach C:\LocalRunDataRoot jest folderem data-root.
| Ścieżka względna | Ścieżka bezwzględna |
|---|---|
| /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 |
Katalog roboczy
Podczas lokalnego uruchamiania skryptu U-SQL podczas kompilacji w bieżącym katalogu uruchomionym jest tworzony katalog roboczy. Oprócz danych wyjściowych kompilacji potrzebne pliki środowiska uruchomieniowego do wykonania lokalnego będą kopiowane w tle do tego katalogu roboczego. Folder główny katalogu roboczego nosi nazwę "ScopeWorkDir", a pliki w katalogu roboczym są następujące:
| Katalog/plik | Katalog/plik | Katalog/plik | Definicja | Opis |
|---|---|---|---|---|
| C6A101DDCB470506 | Ciąg skrótu wersji środowiska uruchomieniowego | Kopia w tle plików środowiska uruchomieniowego wymaganych do wykonania lokalnego | ||
| Script_66AE4909AA0ED06C | Nazwa skryptu i ciąg skrótu ścieżki skryptu | Dane wyjściowe kompilacji i rejestrowanie kroków wykonywania | ||
| _script_.abr | Dane wyjściowe kompilatora | Plik algebra | ||
| _ScopeCodeGen_.* | Dane wyjściowe kompilatora | Wygenerowany kod zarządzany | ||
| _ScopeCodeGenEngine_.* | Dane wyjściowe kompilatora | Wygenerowany kod natywny | ||
| zestawy, do których odwołuje się odwołanie | Dokumentacja zestawu | Przywoływania plików zestawów | ||
| deployed_resources | Wdrażanie zasobów | Pliki wdrażania zasobów | ||
| xxxxxxxx.xxx[1..n]_*.* | Dziennik wykonywania | Dziennik kroków wykonywania |
Korzystanie z zestawu SDK z wiersza polecenia
Interfejs wiersza polecenia aplikacji pomocniczej
W obszarze katalog SDK\build\runtime LocalRunHelper.exe to aplikacja pomocnika wiersza polecenia, która udostępnia interfejsy najczęściej używanych funkcji uruchamiania lokalnego. Zarówno polecenie, jak i przełączniki argumentów są uwzględniane wielkości liter. Aby go wywołać:
LocalRunHelper.exe <command> <Required-Command-Arguments> [Optional-Command-Arguments]
Uruchom LocalRunHelper.exe bez argumentów lub za pomocą przełącznika pomocy , aby wyświetlić informacje pomocy:
> 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
W informacjach pomocy:
- Polecenie daje nazwę polecenia.
- Wymagane argumenty wyświetlają argumenty, które należy podać.
- Opcjonalny argument zawiera argumenty opcjonalne z wartościami domyślnymi. Opcjonalne argumenty logiczne nie mają parametrów, a ich wygląd oznacza ujemną wartość domyślną.
Zwracana wartość i rejestrowanie
Aplikacja pomocnika zwraca wartość 0 dla powodzenia i -1 w przypadku niepowodzenia. Domyślnie pomocnik wysyła wszystkie komunikaty do bieżącej konsoli. Jednak większość poleceń obsługuje argument -MessageOut path_to_log_file opcjonalny, który przekierowuje dane wyjściowe do pliku dziennika.
Konfigurowanie zmiennej środowiskowej
Lokalne uruchomienie U-SQL wymaga określonego katalogu głównego danych jako konta magazynu lokalnego i określonej ścieżki CppSDK dla zależności. Argument można ustawić w wierszu polecenia lub ustawić dla nich zmienną środowiskową.
Ustaw zmienną środowiskową SCOPE_CPP_SDK.
Jeśli otrzymasz Microsoft Visual C++ i Windows SDK, instalując narzędzia Data Lake Tools for Visual Studio, sprawdź, czy masz następujący folder:
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\CppSDKZdefiniuj nową zmienną środowiskową o nazwie SCOPE_CPP_SDK , aby wskazać ten katalog. Możesz też skopiować folder do innego miejsca i określić SCOPE_CPP_SDK w następujący sposób.
Oprócz ustawiania zmiennej środowiskowej można określić argument -CppSDK podczas korzystania z wiersza polecenia. Ten argument zastępuje domyślną zmienną środowiskową CppSDK.
Ustaw zmienną środowiskową LOCALRUN_DATAROOT .
Zdefiniuj nową zmienną środowiskową o nazwie LOCALRUN_DATAROOT wskazującą katalog główny danych.
Oprócz ustawiania zmiennej środowiskowej można określić argument -DataRoot ze ścieżką katalogu głównego danych podczas korzystania z wiersza polecenia. Ten argument zastępuje domyślną zmienną środowiskową katalogu głównego danych. Ten argument należy dodać do każdego uruchomionego wiersza polecenia, aby zastąpić domyślną zmienną środowiskową katalogu głównego danych dla wszystkich operacji.
Przykłady użycia wiersza polecenia zestawu SDK
Kompilowanie i uruchamianie
Polecenie run służy do kompilowania skryptu, a następnie wykonywania skompilowanych wyników. Jego argumenty wiersza polecenia są kombinacją tych z kompilowania i wykonywania.
LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]
Poniżej przedstawiono opcjonalne argumenty uruchamiania:
| Argument | Wartość domyślna | Opis |
|---|---|---|
| -CodeBehind | Fałsz | Skrypt ma .cs kod za sobą |
| -CppSDK | Katalog CppSDK | |
| -DataRoot | Zmienna środowiskowa DataRoot | Element DataRoot dla uruchamiania lokalnego, domyślnie zmienna środowiskowa "LOCALRUN_DATAROOT" |
| -MessageOut | Zrzut komunikatów w konsoli do pliku | |
| -Równoległe | 1 | Uruchamianie planu z określonym równoległością |
| -Odwołania | Lista ścieżek do dodatkowych zestawów odwołań lub plików danych kodu za, oddzielonych ciągami ";" | |
| -UdoRedirect | Fałsz | Generowanie konfiguracji przekierowania zestawu Udo |
| -UseDatabase | master | Baza danych do użycia na potrzeby kodu za tymczasową rejestracją zestawu |
| -Pełne | Fałsz | Pokaż szczegółowe dane wyjściowe ze środowiska uruchomieniowego |
| -WorkDir | Bieżący katalog | Katalog użycia i danych wyjściowych kompilatora |
| -RunScopeCEP | 0 | Tryb ScopeCEP do użycia |
| -ScopeCEPTempPath | tymczasowe | Ścieżka tymczasowa do użycia na potrzeby danych przesyłanych strumieniowo |
| -OptFlags | Rozdzielona przecinkami lista flag optymalizatora |
Oto przykład:
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
Oprócz łączenia kompilowania i wykonywania można skompilować i wykonać skompilowane pliki wykonywalne oddzielnie.
Kompilowanie skryptu U-SQL
Polecenie kompilowania służy do kompilowania skryptu U-SQL do plików wykonywalnych.
LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]
Poniżej przedstawiono opcjonalne argumenty kompilowania:
| Argument | Opis |
|---|---|
| -CodeBehind [wartość domyślna "Fałsz"] | Skrypt ma .cs kod za sobą |
| -CppSDK [wartość domyślna ''] | Katalog CppSDK |
| -DataRoot [wartość domyślna "Zmienna środowiskowa DataRoot"] | Element DataRoot dla uruchamiania lokalnego, domyślnie zmienna środowiskowa "LOCALRUN_DATAROOT" |
| -MessageOut [wartość domyślna ''] | Zrzut komunikatów w konsoli do pliku |
| -Odwołania [wartość domyślna ''] | Lista ścieżek do dodatkowych zestawów odwołań lub plików danych kodu za, oddzielonych ciągami ";" |
| -Płytkie [wartość domyślna "Fałsz"] | Płytki kompilator |
| -UdoRedirect [wartość domyślna "Fałsz"] | Generowanie konfiguracji przekierowania zestawu Udo |
| -UseDatabase [wartość domyślna 'master'] | Baza danych do użycia na potrzeby kodu za tymczasową rejestracją zestawu |
| -WorkDir [wartość domyślna "Bieżący katalog"] | Katalog użycia i danych wyjściowych kompilatora |
| -RunScopeCEP [wartość domyślna "0"] | Tryb ScopeCEP do użycia |
| -ScopeCEPTempPath [wartość domyślna 'temp'] | Ścieżka tymczasowa do użycia na potrzeby danych przesyłanych strumieniowo |
| -OptFlags [wartość domyślna ''] | Rozdzielona przecinkami lista flag optymalizatora |
Oto kilka przykładów użycia.
Skompiluj skrypt U-SQL:
LocalRunHelper compile -Script d:\test\test1.usql
Skompiluj skrypt U-SQL i ustaw folder data-root. Spowoduje to zastąpienie ustawionej zmiennej środowiskowej.
LocalRunHelper compile -Script d:\test\test1.usql –DataRoot c:\DataRoot
Skompiluj skrypt U-SQL i ustaw katalog roboczy, zestaw referencyjny i bazę danych:
LocalRunHelper compile -Script d:\test\test1.usql -WorkDir d:\test\bin -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB
Wykonywanie skompilowanych wyników
Polecenie execute służy do wykonywania skompilowanych wyników.
LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]
Poniżej przedstawiono opcjonalne argumenty do wykonania:
| Argument | Wartość domyślna | Opis |
|---|---|---|
| -DataRoot | '' | Katalog główny danych na potrzeby wykonywania metadanych. Domyślnie jest to zmienna środowiskowa LOCALRUN_DATAROOT . |
| -MessageOut | '' | Zrzuty komunikatów w konsoli do pliku. |
| -Równoległe | '1' | Wskaźnik uruchamiania wygenerowanych kroków uruchamiania lokalnego z określonym poziomem równoległości. |
| -Pełne | "Fałsz" | Wskaźnik pokazujący szczegółowe dane wyjściowe ze środowiska uruchomieniowego. |
Oto przykład użycia:
LocalRunHelper execute -Algebra d:\test\workdir\C6A101DDCB470506\Script_66AE4909AA0ED06C\__script__.abr –DataRoot c:\DataRoot –Parallel 5
Używanie zestawu SDK z interfejsami programowania
Wszystkie interfejsy programowania znajdują się w LocalRunHelper.exe. Można ich użyć do zintegrowania funkcji zestawu U-SQL SDK i platformy testowej języka C# w celu skalowania lokalnego testu skryptu U-SQL. W tym artykule użyję standardowego projektu testów jednostkowych języka C#, aby pokazać, jak używać tych interfejsów do testowania skryptu U-SQL.
Krok 1. Tworzenie projektu i konfiguracji testu jednostkowego języka C#
Utwórz projekt testu jednostkowego w języku C# za pomocą projektu File New > Project Visual C# Test Unit Test Project (Projekt > nowego projektu > Visual C# > Test jednostkowy > projektu).
Dodaj LocalRunHelper.exe jako odwołanie do projektu. LocalRunHelper.exe znajduje się w \build\runtime\LocalRunHelper.exe w pakiecie NuGet.
Zestaw U-SQL SDK obsługuje tylko środowisko x64. Upewnij się, że ustawiono element docelowy platformy kompilacji jako x64. Można to ustawić za pomocą obiektu docelowego platformy kompilacji > właściwości > projektu.
Pamiętaj, aby ustawić środowisko testowe jako x64. W programie Visual Studio można ustawić ją za pomocą opcji Test Test > Settings Default Processor Architecture x64 (Domyślna architektura > procesora x64).>
Pamiętaj, aby skopiować wszystkie pliki zależności w folderze NugetPackage\build\runtime\ do katalogu roboczego projektu, który jest zwykle w folderze ProjectFolder\bin\x64\Debug.
Krok 2. Tworzenie przypadku testowego skryptu U-SQL
Poniżej znajduje się przykładowy kod testu skryptu U-SQL. Do testowania należy przygotować skrypty, pliki wejściowe i oczekiwane pliki wyjściowe.
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);
}
}
}
Interfejsy programowania w LocalRunHelper.exe
LocalRunHelper.exe udostępnia interfejsy programowania dla lokalnego kompilowania, uruchamiania i uruchamiania języka U-SQL. Interfejsy są wymienione w następujący sposób.
Konstruktor
public LocalRunHelper([System.IO.TextWriter messageOutput = null])
| Parametr | Typ | Opis |
|---|---|---|
| messageOutput | System.IO.TextWriter | w przypadku komunikatów wyjściowych ustaw wartość null na wartość null, aby użyć konsoli |
Właściwości
| Właściwość | Typ | Opis |
|---|---|---|
| AlgebraPath | ciąg | Ścieżka do pliku algebra (plik algebra jest jednym z wyników kompilacji) |
| CodeBehindReferences | ciąg | Jeśli skrypt ma inny kod związany z odwołaniami, określ ścieżki rozdzielone znakami ";" |
| CppSdkDir | ciąg | Katalog CppSDK |
| CurrentDir | ciąg | Bieżący katalog |
| DataRoot | ciąg | Ścieżka katalogu głównego danych |
| DebuggerMailPath | ciąg | Ścieżka do debugera mailslot |
| GenerateUdoRedirect | bool | Jeśli chcemy wygenerować konfigurację przekierowania ładowania zestawu |
| HasCodeBehind | bool | Jeśli skrypt ma kod za |
| InputDir | ciąg | Katalog danych wejściowych |
| MessagePath | ciąg | Ścieżka pliku zrzutu komunikatu |
| OutputDir | ciąg | Katalog danych wyjściowych |
| Równoległości prostych | int | Równoległość uruchamiania algebry |
| ParentPid | int | Identyfikator PID elementu nadrzędnego, na którym usługa monitoruje zamknięcie, ustawioną na wartość 0 lub ujemną, aby zignorować |
| Resultpath | ciąg | Ścieżka pliku zrzutu wyniku |
| RuntimeDir | ciąg | Katalog środowiska uruchomieniowego |
| ScriptPath | ciąg | Gdzie znaleźć skrypt |
| Płytkie | bool | Płytkie kompilowanie lub nie |
| TempDir | ciąg | Katalog tymczasowy |
| UseDataBase | ciąg | Określ bazę danych do użycia na potrzeby kodu za tymczasową rejestracją zestawu, domyślnie master |
| Pracadir | ciąg | Preferowany katalog roboczy |
Metoda
| Metoda | Opis | Zwrot | Parametr |
|---|---|---|---|
| public bool DoCompile() | Kompilowanie skryptu U-SQL | Prawda w przypadku powodzenia | |
| public bool DoExec() | Wykonywanie skompilowanego wyniku | Prawda w przypadku powodzenia | |
| public bool DoRun() | Uruchamianie skryptu U-SQL (kompilowanie i wykonywanie) | Prawda w przypadku powodzenia | |
| public bool IsValidRuntimeDir(ścieżka ciągu) | Sprawdź, czy dana ścieżka jest prawidłową ścieżką środowiska uruchomieniowego | True dla prawidłowego | Ścieżka katalogu środowiska uruchomieniowego |
Często zadawane pytania dotyczące typowego problemu
Błąd 1
E_CSC_SYSTEM_INTERNAL: Błąd wewnętrzny! Nie można załadować pliku lub zestawu "ScopeEngineManaged.dll" lub jednej z jego zależności. Nie można odnaleźć określonego modułu.
Sprawdź następujące kwestie:
- Upewnij się, że masz środowisko x64. Platforma docelowa kompilacji i środowisko testowe powinny mieć wartość x64. Zapoznaj się z artykułem Krok 1. Tworzenie projektu testów jednostkowych języka C# i konfiguracji powyżej.
- Upewnij się, że zostały skopiowane wszystkie pliki zależności w folderze NugetPackage\build\runtime\ do katalogu roboczego projektu.
Następne kroki
- Aby dowiedzieć się więcej o języku U-SQL, zobacz Wprowadzenie do języka U-SQL w usłudze Azure Data Lake Analytics.
- Aby rejestrować informacje diagnostyczne, zobacz Uzyskiwanie dostępu do dzienników diagnostycznych dla usługi Azure Data Lake Analytics.
- Aby wyświetlić bardziej złożone zapytanie, zobacz Analizowanie dzienników witryn internetowych przy użyciu usługi Azure Data Lake Analytics.
- Aby wyświetlić szczegóły zadania, zobacz Use Job Browser and Job View for Azure Data Lake Analytics jobs (Używanie przeglądarki zadań i widoku zadań dla zadań platformy Azure Data Lake Analytics).
- Aby użyć widoku wykonywania wierzchołków, zobacz Używanie widoku wykonywania wierzchołka w narzędziach Data Lake Tools for Visual Studio.