Menjalankan dan menguji U-SQL dengan Azure Data Lake U-SQL SDK
Penting
Azure Data Lake Analytics pensiun pada 29 Februari 2024. Pelajari lebih lanjut dengan pengumuman ini.
Untuk analitik data, organisasi Anda dapat menggunakan Azure Synapse Analytics atau Microsoft Fabric.
Saat mengembangkan skrip U-SQL, biasanya menjalankan dan menguji skrip U-SQL secara lokal sebelum mengirimkannya ke cloud. Azure Data Lake menyediakan paket NuGet yang disebut Azure Data Lake U-SQL SDK untuk skenario ini, di mana Anda dapat dengan mudah menskalakan eksekusi dan pengujian U-SQL. Dimungkinkan juga untuk mengintegrasikan pengujian U-SQL ini dengan sistem CI (Integrasi Berkelanjutan) untuk mengotomatiskan kompilasi dan pengujian.
Jika Anda peduli tentang cara menjalankan secara manual dan men-debug skrip U-SQL dengan peralatan GUI, maka Anda dapat menggunakan Azure Data Lake Tools for Visual Studio untuk tujuan itu. Anda dapat mempelajari lebih lanjut dari sini.
Menginstal Azure Data Lake U-SQL SDK
Anda bisa mendapatkan Azure Data Lake U-SQL SDK di sini pada Nuget.org. Dan sebelum menggunakannya, Anda perlu memastikan Bahwa Anda memiliki dependensi sebagai berikut.
Dependensi
Data Lake U-SQL SDK memerlukan dependensi berikut:
Microsoft Visual C++ 14 dan Windows SDK 10.0.10240.0 atau yang lebih baru (yang disebut CppSDK dalam artikel ini). Terdapat dua cara untuk mendapatkan peran:
Instal Visual Studio Community Edition. Anda akan memiliki folder \Windows Kits\10 di bawah folder Program Files--misalnya, C:\Program Files (x86)\Windows Kits\10. Anda juga akan menemukan versi Windows 10 SDK di bawah \Windows Kits\10\Lib. Jika Anda tidak melihat folder ini, instal Visual Studio dan pastikan untuk memilih Windows 10 SDK selama instalasi. Jika Anda telah menginstalnya dengan Visual Studio, pengompilasi lokal U-SQL akan menemukannya secara otomatis.
Instal Data Lake Tools for Visual Studio. Anda dapat menemukan file Visual C++ dan Windows SDK yang sudah dikemas sebelumnya di
C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.
Dalam hal ini, pengkompilasi lokal U-SQL tidak dapat menemukan dependensi secara otomatis. Anda perlu menentukan jalur CppSDK untuk itu. Anda dapat menyalin file ke lokasi lain atau menggunakannya apa adanya.
Memahami konsep dasar
Root data
Folder root data adalah "penyimpanan lokal" untuk akun komputasi lokal. Folder tersebut setara dengan akun Azure Data Lake Store dari akun Data Lake Analytics. Beralih ke folder root data yang berbeda sama seperti beralih ke akun penyimpanan yang berbeda. Jika Anda ingin mengakses data yang dibagikan secara umum dengan folder root data yang berbeda, Anda harus menggunakan jalur absolut dalam skrip Anda. Atau, buat tautan simbolis sistem file (misalnya, mklink pada NTFS) di bawah folder root data untuk menunjuk ke data bersama.
Folder root data digunakan untuk:
- Menyimpan metadata lokal, termasuk database, tabel, fungsi bernilai tabel (TVF), dan perakitan.
- Mencari jalur input dan output yang didefinisikan sebagai jalur relatif di U-SQL. Menggunakan jalur relatif yang memudahkan menerapkan proyek U-SQL Anda ke Azure.
Jalur file dalam U-SQL
Anda dapat menggunakan jalur relatif dan jalur absolut lokal dalam skrip U-SQL. Jalur relatif tergantung pada jalur folder root data yang ditentukan. Kami menyarankan agar Anda menggunakan "/" sebagai pemisah jalur untuk membuat skrip Anda kompatibel dengan sisi server. Berikut adalah beberapa contoh jalur relatif dan jalur absolut yang setara. Dalam contoh ini, C:\LocalRunDataRoot adalah folder root data.
Jalur relatif | Jalur absolut |
---|---|
/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 |
Direktori Kerja
Saat menjalankan skrip U-SQL secara lokal, direktori kerja dibuat selama kompilasi di bawah direktori yang sedang berjalan. Selain output kompilasi, file runtime yang diperlukan untuk eksekusi lokal akan disalin bayangan ke direktori kerja ini. Folder root direktori kerja disebut "ScopeWorkDir" dan file di bawah direktori kerja adalah sebagai berikut:
Directory/file | Directory/file | Directory/file | Definisi | Deskripsi |
---|---|---|---|---|
C6A101DDCB470506 | String hash dari versi runtime | Salinan bayangan file runtime yang diperlukan untuk eksekusi lokal | ||
Script_66AE4909AA0ED06C | Nama skrip + string hash dari jalur skrip | Luaran kompilasi dan pencatatan langkah eksekusi | ||
_script_.abr | Luaran kompiler | File Algebra | ||
_ScopeCodeGen_.* | Luaran kompiler | Kode terkelola yang dihasilkan | ||
_ScopeCodeGenEngine_.* | Luaran kompiler | Kode asli yang dihasilkan | ||
assembly yang direferensikan | Referensi assembly | File assembly yang direferensikan | ||
deployed_resources | Penyebaran sumber daya | File penyebaran sumber daya | ||
xxxxxxxx.xxx[1..n]_*.* | Log eksekusi | Log langkah-langkah eksekusi |
Menggunakan SDK dari baris perintah
Antarmuka baris perintah dari aplikasi pembantu
Di bawah SDK directory\build\runtime, LocalRunHelper.exe adalah aplikasi pembantu baris perintah yang menyediakan antarmuka yang umum digunakan ke sebagian besar fungsi yang dijalankan secara lokal. Sakelar perintah dan argumen peka huruf besar/kecil. Untuk menggunakannya:
LocalRunHelper.exe <command> <Required-Command-Arguments> [Optional-Command-Arguments]
Jalankan LocalRunHelper.exe tanpa argumen atau dengan pengalih bantuan untuk memperlihatkan informasi bantuan:
> 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
Dalam informasi bantuan:
- Perintah memberikan nama perintah.
- Argumen yang Diperlukan mencantumkan argumen yang harus disediakan.
- Argumen Opsional mencantumkan argumen yang opsional, dengan nilai default. Argumen Boolean opsional tidak memiliki parameter, dan kemunculannya berarti negatif terhadap nilai defaultnya.
Nilai yang dikembalikan dan pembuatan log
Aplikasi pembantu mengembalikan 0 untuk yang berhasil dan -1 untuk yang gagal. Secara default, pembantu mengirim semua pesan ke konsol saat ini. Namun, sebagian besar perintah mendukung argumen opsional -MessageOut path_to_log_file yang mengalihkan output ke file log.
Konfigurasi variabel lingkungan
Eksekusi lokal U-SQL memerlukan akar data tertentu sebagai akun penyimpanan lokal, dan jalur CppSDK tertentu untuk dependensi. Anda dapat secara menyeluruh mengatur argumen di baris perintah atau mengatur variabel lingkungan untuk mereka.
Atur variabel lingkungan SCOPE_CPP_SDK.
Jika Anda mendapatkan Microsoft Visual C++ dan Windows SDK dengan menginstal Data Lake Tools for Visual Studio, verifikasi bahwa Anda memiliki folder berikut:
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
Tentukan variabel lingkungan baru yang disebut SCOPE_CPP_SDK untuk menunjuk ke direktori ini. Atau salin folder ke lokasi lain dan tentukan SCOPE_CPP_SDK atau yang semacamnya.
Selain menyetel variabel lingkungan, Anda dapat menentukan argumen -CppSDK saat Anda menggunakan baris perintah. Argumen ini menimpa variabel lingkungan Cpp SDK default Anda.
Setel variabel lingkungan LOCALRUN_DATAROOT.
Tentukan variabel lingkungan baru yang disebut LOCALRUN_DATAROOT yang menunjuk ke akar data.
Selain mengatur variabel lingkungan, Anda dapat menentukan argumen -DataRoot dengan jalur data-root saat Anda menggunakan baris perintah. Argumen ini menimpa variabel lingkungan root data default Anda. Anda perlu menambahkan argumen ini ke setiap baris perintah yang Anda jalankan sehingga Anda dapat menimpa variabel lingkungan root data default untuk semua operasi.
Sampel penggunaan baris perintah SDK
Mengompilasi dan menjalankan
Perintah jalankan digunakan untuk mengompilasi skrip lalu menjalankan hasil yang dikompilasi. Argumen baris perintahnya adalah kombinasi dari argumen dari kompilasi dan eksekusi.
LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]
Berikut ini adalah argumen opsional untuk menjalankan:
Argumen | Nilai default | Deskripsi |
---|---|---|
-CodeBehind | Salah | Skrip memiliki node .cs di belakang |
-CppSDK | Direktori CppSDK | |
-DataRoot | Variabel lingkungan DataRoot | DataRoot untuk dijalankan secara lokal, default ke variabel lingkungan 'LOCALRUN_DATAROOT' |
-MessageOut | Membuang pesan di konsol ke file | |
-Parallel | 1 | Jalankan rencana dengan paralelisme yang ditentukan |
-Referensi | Daftar jalur untuk rakitan referensi tambahan atau file data kode di belakang, dipisahkan oleh ';' | |
-UdoRedirect | Salah | Hasilkan konfigurasi pengalihan assembly Udo |
-UseDatabase | master | Database yang digunakan untuk kode di balik pendaftaran assembly sementara |
-Verbose | Salah | Tampilkan output terperinci dari runtime |
-WorkDir | Direktori Saat Ini | Direktori untuk penggunaan kompilasi dan output |
-RunScopeCEP | 0 | Mode ScopeCEP yang akan digunakan |
-ScopeCEPTempPath | temp | Jalur sementara yang digunakan untuk streaming data |
-OptFlags | Daftar bendera pengoptimal yang dipisahkan koma |
Berikut contohnya:
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
Selain menggabungkan kompilasi dan eksekusi, Anda dapat mengompilasi dan menjalankan kompilasi yang dapat dieksekusi secara terpisah.
Menyusun skrip U-SQL
Perintah kompilasi digunakan untuk mengompilasi skrip U-SQL ke perintah eksekusi.
LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]
Berikut ini adalah argumen opsional untuk kompilasi:
Argumen | Deskripsi |
---|---|
-CodeBehind [nilai default 'False'] | Skrip memiliki node .cs di belakang |
-CppSDK [nilai default ''] | Direktori CppSDK |
-DataRoot [nilai default 'DataRoot environment variable'] | DataRoot untuk dijalankan secara lokal, default ke variabel lingkungan 'LOCALRUN_DATAROOT' |
-MessageOut [nilai default ''] | Membuang pesan di konsol ke file |
-References [nilai default ''] | Daftar jalur untuk rakitan referensi tambahan atau file data kode di belakang, dipisahkan oleh ';' |
-Shallow [nilai default 'False'] | Kompilasi dangkal |
-UdoRedirect [nilai default 'False'] | Hasilkan konfigurasi pengalihan assembly Udo |
-UseDatabase [nilai default 'master'] | Database yang digunakan untuk kode di balik pendaftaran assembly sementara |
-WorkDir [nilai default 'Current Directory'] | Direktori untuk penggunaan kompilasi dan output |
-RunScopeCEP [nilai default '0'] | Mode ScopeCEP yang akan digunakan |
-ScopeCEPTempPath [nilai default 'temp'] | Jalur sementara yang digunakan untuk streaming data |
-OptFlags [nilai default ''] | Daftar bendera pengoptimal yang dipisahkan koma |
Berikut adalah beberapa contoh penggunaan.
Menyusun skrip U-SQL:
LocalRunHelper compile -Script d:\test\test1.usql
Menyusun skrip U-SQL dan mengatur folder root data. Ini akan menimpa variabel lingkungan yang ditetapkan.
LocalRunHelper compile -Script d:\test\test1.usql –DataRoot c:\DataRoot
Kompilasi skrip U-SQL dan atur direktori kerja, rakitan referensi, dan database:
LocalRunHelper compile -Script d:\test\test1.usql -WorkDir d:\test\bin -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB
Jalankan hasil yang dikompilasi
Perintah eksekusi digunakan untuk menjalankan hasil yang dikompilasi.
LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]
Berikut ini adalah argumen opsional untuk menjalankan:
Argumen | Nilai default | Deskripsi |
---|---|---|
-DataRoot | '' | Root data untuk eksekusi metadata. Root data tersebut bersifat default ke variabel lingkungan LOCALRUN_DATAROOT. |
-MessageOut | '' | Buang pesan pada konsol ke file. |
-Parallel | '1' | Indikator untuk menjalankan langkah-langkah local-run yang dihasilkan dengan tingkat paralelisme yang ditentukan. |
-Verbose | 'False' | Indikator untuk menampilkan output terperinci dari runtime. |
Berikut contoh penggunaannya:
LocalRunHelper execute -Algebra d:\test\workdir\C6A101DDCB470506\Script_66AE4909AA0ED06C\__script__.abr –DataRoot c:\DataRoot –Parallel 5
Gunakan SDK dengan antarmuka pemrograman
Antarmuka pemrograman semuanya terletak di LocalRunHelper.exe. Anda dapat menggunakannya untuk mengintegrasikan fungsionalitas SDK U-SQL dan kerangka kerja uji C# untuk menskalakan uji lokal skrip U-SQL Anda. Dalam artikel ini, saya akan menggunakan proyek pengujian unit C# standar untuk menunjukkan cara menggunakan antarmuka ini untuk menguji skrip U-SQL Anda.
Langkah 1: Buat proyek dan konfigurasi pengujian unit C#
Buat proyek pengujian unit C# melalui Proyek > Baru Proyek > Visual > C# > Uji > Unit Uji Proyek.
Tambahkan LocalRunHelper.exe sebagai referensi untuk proyek. LocalRunHelper.exe terletak di \build\runtime\LocalRunHelper.exe dalam paket NuGet.
U-SQL SDK hanya mendukung lingkungan x64, pastikan untuk menetapkan target platform build sebagai x64. Anda dapat mengaturnya melalui target Project Property > Build > Platform.
Memastikan untuk mengatur lingkungan pengujian Anda sebagai x64. Di Visual Studio, Anda dapat mengaturnya melalui Pengujian > Pengaturan > Pengujian Arsitektur > Prosesor Default x64.
Pastikan untuk menyalin semua file dependensi di bawah NugetPackage\build\runtime\ ke direktori kerja proyek, yang biasanya berada di bawah ProjectFolder\bin\x64\Debug.
Langkah 2: Membuat kasus uji skrip U-SQL
Di bawah ini adalah kode sampel untuk uji skrip U-SQL. Untuk pengujian, Anda perlu menyiapkan skrip, file input, dan file output yang diharapkan.
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);
}
}
}
Antarmuka pemrograman di LocalRunHelper.exe
LocalRunHelper.exe menyediakan antarmuka pemrograman untuk kompilasi lokal U-SQL, menjalankan, dll. Antarmuka terdaftar sebagai berikut.
Konstruktor
public LocalRunHelper([System.IO.TextWriter messageOutput = null])
Parameter | Jenis | Deskripsi |
---|---|---|
messageOutput | System.IO.TextWriter | untuk pesan output, atur ke null untuk menggunakan Konsol |
Properti
Properti | Jenis | Deskripsi |
---|---|---|
AlgebraPath | string | Jalur ke berkas algebra (berkas algebra adalah salah satu hasil kompilasi) |
CodeBehindReferences | string | Jika skrip memiliki kode lain di belakang referensi, tentukan jalur yang dipisahkan dengan ';' |
CppSdkDir | string | Direktori CppSDK |
CurrentDir | string | Direktori saat ini |
DataRoot | string | Jalur root data |
DebuggerMailPath | string | Jalur untuk debugger mailslot |
GenerateUdoRedirect | bool | Jika kita ingin membuat konfigurasi pengambil alihan penggantian pemuatan assembly |
HasCodeBehind | bool | Jika skrip memiliki kode di belakang |
InputDir | string | Direktori untuk memasukkan data |
MessagePath | string | Jalur file cadangan pesan |
OutputDir | string | Direktori untuk data output |
Paralelisme | int | Paralelisme untuk menjalankan algebra |
ParentPid | int | PID induk tempat layanan memantau untuk keluar, diatur ke 0 atau negatif untuk diabaikan |
ResultPath | string | Jalur file cadangan hasil |
RuntimeDir | string | Direktori runtime |
ScriptPath | string | Tempat untuk menemukan skrip |
Dangkal | bool | Mengompilasi secara dangkal atau tidak |
TempDir | string | Direktori sementara |
UseDataBase | string | Menentukan database yang akan digunakan untuk kode di balik pendaftaran assembly sementara, master secara default |
WorkDir | string | Direktori ke pekerjaan yang dipilih |
Metode
Metode | Deskripsi | Kembali | Parameter |
---|---|---|---|
bool publik DoCompile() | Mengompilasi skrip U-SQL | Benar tentang kesuksesan | |
bool publik DoExec() | Menjalankan hasil yang dikompilasi | Benar tentang kesuksesan | |
bool publik DoRun() | Menjalankan skrip U-SQL (Kompilasi + Eksekusi) | Benar tentang kesuksesan | |
bool publik IsValidRuntimeDir(jalur string) | Memeriksa apakah jalur yang diberikan adalah jalur runtime yang valid | Berlaku untuk valid | Jalur direktori runtime |
Tanya Jawab Umum masalah umum
Kesalahan 1
E_CSC_SYSTEM_INTERNAL: Internal error! Tidak dapat memuat file atau rakitan 'ScopeEngineManaged.dll' atau salah satu dependensinya. Modul yang ditentukan tak dapat ditemukan.
Periksa hal berikut:
- Pastikan Anda memiliki lingkungan x64. Platform target build dan lingkungan pengujian harus x64, lihat Langkah 1: Buat proyek dan konfigurasi pengujian unit C# di atas.
- Pastikan Anda telah menyalin semua file dependensi di bawah NugetPackage\build\runtime\ ke direktori kerja proyek.
Langkah berikutnya
- Untuk mempelajari U-SQL, lihat Mulai menggunakan bahasa U-SQL Azure Data Lake Analytics.
- Untuk mencatat informasi diagnostik, lihat Mengakses log diagnostik untuk Azure Data Lake Analytics
- Untuk melihat kueri yang lebih kompleks, lihat Analisis log Situs Web menggunakan Azure Data Lake Analytics.
- Untuk melihat detail pekerjaan, lihat Gunakan Browser Pekerjaan dan Tampilan Pekerjaan untuk pekerjaan Azure Data Lake Analytics.
- Untuk menggunakan tampilan eksekusi vertex, lihat Gunakan Tampilan Eksekusi Vertex di Alat Data Lake untuk Visual Studio.