Menjalankan dan menguji U-SQL dengan Azure Data Lake U-SQL SDK

Artikel
12/20/2023

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 .NET Framework 4.6 atau yang lebih baru.
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.