Azure Data Lake U-SQL SDK'sı ile U-SQL'i çalıştırma ve test edin

Önemli

Azure Data Lake Analytics 29 Şubat 2024'te kullanımdan kaldırıldı. Bu duyuruyla daha fazla bilgi edinin.

Veri analizi için kuruluşunuz Azure Synapse Analytics veya Microsoft Fabric kullanabilir.

U-SQL betiği geliştirirken, U-SQL betiğini buluta göndermeden önce yerel olarak çalıştırmak ve test etmek yaygın bir işlemdir. Azure Data Lake, bu senaryo için U-SQL çalıştırmasını ve testlerini kolayca ölçeklendirebileceğiniz Azure Data Lake U-SQL SDK adlı bir NuGet paketi sağlar. Derlemeyi ve testi otomatikleştirmek için bu U-SQL testini CI (Sürekli Tümleştirme) sistemiyle tümleştirmek de mümkündür.

GUI araçlarıyla el ile yerel çalıştırmayı ve U-SQL betiğinin hatalarını ayıklamayı düşünüyorsanız bunun için Visual Studio için Azure Data Lake Araçları'nı kullanabilirsiniz. Buradan daha fazla bilgi edinebilirsiniz.

Azure Data Lake U-SQL SDK'sı yükleme

Azure Data Lake U-SQL SDK'sını buradan Nuget.org alabilirsiniz. Bunu kullanmadan önce aşağıdaki bağımlılıklara sahip olduğunuzdan emin olmanız gerekir.

Bağımlılıklar

Data Lake U-SQL SDK'sı aşağıdaki bağımlılıkları gerektirir:

Microsoft .NET Framework 4.6 veya üzeri.
Microsoft Visual C++ 14 ve Windows SDK 10.0.10240.0 veya üzeri (bu makalede CppSDK olarak adlandırılır). CppSDK almanın iki yolu vardır:
- Visual Studio Community Edition'ı yükleyin. Program Dosyaları klasörünün altında bir \Windows Kits\10 klasörünüz olur; örneğin, C:\Program Files (x86)\Windows Kits\10. Windows 10 SDK sürümünü \Windows Kits\10\Lib altında da bulabilirsiniz. Bu klasörleri görmüyorsanız Visual Studio'yu yeniden yükleyin ve yükleme sırasında Windows 10 SDK'sını seçtiğinizden emin olun. Bunu Visual Studio ile yüklediyseniz, U-SQL yerel derleyicisi bunu otomatik olarak bulur.
- Visual Studio için Data Lake Araçları'nı yükleyin. Önceden paketlenmiş Visual C++ ve Windows SDK dosyalarını şu konumda bulabilirsiniz: C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.
  
  Bu durumda, U-SQL yerel derleyicisi bağımlılıkları otomatik olarak bulamaz. Bunun için CppSDK yolunu belirtmeniz gerekir. Dosyaları başka bir konuma kopyalayabilir veya olduğu gibi kullanabilirsiniz.

Temel kavramları anlama

Veri kök dizini

Veri kökü klasörü, yerel işlem hesabı için bir "yerel depodur". Data Lake Analytics hesabının Azure Data Lake Store hesabına eşdeğerdir. Farklı bir veri kök klasörüne geçmek, farklı bir mağaza hesabına geçiş yapmak gibidir. Yaygın olarak paylaşılan verilere farklı veri kök klasörleriyle erişmek istiyorsanız, betiklerinizde mutlak yollar kullanmanız gerekir. Alternatif olarak, paylaşılan verilere işaret etmek için veri kök klasörünün altında dosya sistemi sembolik bağlantıları (örneğin, NTFS'de mklink ) oluşturun.

Veri kök klasörü aşağıdakiler için kullanılır:

Veritabanları, tablolar, tablo değerli işlevler (TVF'ler) ve derlemeler gibi yerel meta verileri depolayın.
U-SQL'de göreli yollar olarak tanımlanan giriş ve çıkış yollarını arayın. Göreli yolları kullanmak, U-SQL projelerinizi Azure'a dağıtmanızı kolaylaştırır.

U-SQL'de dosya yolu

U-SQL betiklerinde hem göreli yol hem de yerel mutlak yol kullanabilirsiniz. Göreli yol, belirtilen veri-kök klasör yoluna göredir. Betiklerinizi sunucu tarafıyla uyumlu hale getirmek için yol ayırıcı olarak "/" kullanmanızı öneririz. Göreli yollara ve bunların eşdeğer mutlak yollarına bazı örnekler aşağıda verilmiştir. Bu örneklerde C:\LocalRunDataRoot, veri-kök klasörüdür.

Göreli yol	Mutlak yol
/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

Çalışma dizini

U-SQL betiğini yerel olarak çalıştırırken, derleme sırasında geçerli çalışan dizin altında bir çalışma dizini oluşturulur. Derleme çıkışlarına ek olarak, yerel yürütme için gereken çalıştırma zamanı dosyaları arka planda bu çalışma dizinine kopyalanır. Çalışma dizini kök klasörü "ScopeWorkDir" olarak adlandırılır ve çalışma dizininin altındaki dosyalar aşağıdaki gibidir:

Dizin/dosya	Dizin/dosya	Dizin/dosya	Tanım	Açıklama
C6A101DDCB470506			Çalışma zamanı sürümünün hash dizesi	Yerel yürütme için gereken çalışma zamanı dosyalarının gölge kopyası
	Script_66AE4909AA0ED06C		Betik adı + betik yolunun hash dizesi	Derleme çıkışları ve yürütme aşamalarının günlüğü
		_script_.abr	Derleyici çıkışı	Cebir dosyası
		_ScopeCodeGen_.*	Derleyici çıkışı	Oluşturulan yönetilen kod
		_ScopeCodeGenEngine_.*	Derleyici çıkışı	Oluşturulan yerel kod
		atıfta bulunulan modüller	Assembly referansı	Başvurulan derleme dosyaları
		dağıtılan kaynaklar	Kaynak dağıtımı	Kaynak dağıtım dosyaları
		xxxxxxxx.xxx[1..n]_.	Yürütme günlüğü	Yürütme adımları günlüğü

Komut satırından SDK'yi kullanma

Yardımcı uygulamanın komut satırı arabirimi

SDK dizini\build\runtime, LocalRunHelper.exe altında, yaygın olarak kullanılan yerel çalıştırma işlevlerinin çoğuna arabirimler sağlayan komut satırı yardımcı uygulaması bulunur. Hem komut hem de argüman seçenekleri büyük/küçük harfe duyarlıdır. Bunu çalıştırmak için:

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

LocalRunHelper.exe'ı bağımsız değişken olmadan veya yardım anahtarıyla çalıştırın ve yardım bilgilerini görüntüleyin.

> 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

Yardım bilgilerinde:

Komut , komutun adını verir.
Gerekli Bağımsız Değişken , sağlanması gereken bağımsız değişkenleri listeler.
İsteğe Bağlı Bağımsız Değişken , varsayılan değerlerle isteğe bağlı bağımsız değişkenleri listeler. İsteğe bağlı Boolean argümanlarının parametreleri yoktur ve bunların kullanımı varsayılan değerlerinin tersini belirtir.

Dönüş değeri ve kayıt işlemi

Yardımcı uygulama başarı için 0 ve başarısızlık için -1 döndürür. Varsayılan olarak, yardımcı tüm iletileri geçerli konsola gönderir. Ancak komutların çoğu çıkışları günlük dosyasına yönlendiren isteğe bağlı -MessageOut path_to_log_file bağımsız değişkenini destekler.

Ortam değişkeni yapılandırma

U-SQL yerel çalıştırması, yerel depolama hesabı olarak belirtilen bir veri köküne ve bağımlılıklar için belirtilen bir CppSDK yoluna ihtiyaç duyar. Bağımsız değişkeni komut satırında ayarlayabilir veya onlar için bir ortam değişkeni belirleyebilirsiniz.

SCOPE_CPP_SDK ortam değişkenini ayarlayın.

Visual Studio için Data Lake Araçları'nı yükleyerek Microsoft Visual C++ ve Windows SDK'sını alırsanız aşağıdaki klasöre sahip olduğunuzu doğrulayın:

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

Bu dizine işaret etmek için SCOPE_CPP_SDK adlı yeni bir ortam değişkeni tanımlayın. Veya klasörü diğer konuma kopyalayın ve SCOPE_CPP_SDK olarak belirtin.

Ortam değişkenini ayarlamaya ek olarak, komut satırını kullanırken -CppSDK bağımsız değişkenini belirtebilirsiniz. Bu bağımsız değişken, CppSDK varsayılan ortam değişkeninizi geçersiz kılar.
LOCALRUN_DATAROOT ortam değişkenini ayarlayın.

Veri köküne işaret eden LOCALRUN_DATAROOT adlı yeni bir ortam değişkeni tanımlayın.

Ortam değişkenini ayarlamaya ek olarak, komut satırını kullanırken veri kök yolunu belirterek -DataRoot bağımsız değişkenini belirtebilirsiniz. Bu bağımsız değişken, varsayılan veri kök çevresel değişkeninize yeni değer atar. Tüm işlemler için varsayılan veri kök ortam değişkeninin üzerine yazabilmek için bu bağımsız değişkeni çalıştırdığınız her komut satırına eklemeniz gerekir.

SDK komut satırı kullanım örnekleri

Derleyin ve çalıştırın

Run komutu, betiği derlemek ve ardından derlenmiş sonuçları çalıştırmak için kullanılır. Komut satırı parametreleri, derleme ve yürütmeden alınanların bir bileşimidir.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

çalıştır komutu için isteğe bağlı bağımsız değişkenler şunlardır:

Tartışma	Varsayılan değer	Açıklama
-CodeBehind	Yanlış	Betiğin arkasında C# kodu bulunuyor.
-CppSDK		CppSDK Dizini
-DataRoot	DataRoot ortam değişkeni	Yerel çalıştırma için DataRoot, varsayılan olarak 'LOCALRUN_DATAROOT' ortam değişkeni
-MessageOut		Konsoldaki iletileri dosyaya döküm etme
-Paralel	1	Planı belirtilen paralellikle çalıştırma
-Kaynakça		';' ile ayrılmış ek başvuru derlemelerine veya arka planda kod veri dosyalarına giden yolların listesi
-UdoRedirect	Yanlış	Udo bileşen yeniden yönlendirme yapılandırmasını oluşturma
-VeritabanıKullan	usta	Geçici derleme kaydının arkasındaki kod için kullanılacak veritabanı
-Fazla Ayrıntılı	Yanlış	Çalışma zamanından ayrıntılı çıktıları göster
-ÇalışmaDizini	Geçerli Dizin	Derleyici kullanımı ve çıkışları için dizin
-RunScopeCEP	0	Kullanılacak olan ScopeCEP modu
-ScopeCEPTempPath	sıcaklık	Akış verileri için geçici olarak kullanılacak yol
-OptFlags		İyileştirici bayraklarının virgülle ayrılmış listesi

İşte bir örnek:

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

Derleme ve yürütmeyi birleştirmenin yanı sıra, derlenmiş yürütülebilir dosyaları ayrı ayrı derleyebilir ve yürütebilirsiniz.

U-SQL betiğini derle

Derleme komutu, yürütülebilir dosyalara U-SQL betiğini derlemek için kullanılır.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Derleme için isteğe bağlı bağımsız değişkenler şunlardır:

Tartışma	Açıklama
-CodeBehind [varsayılan değer 'False']	Betik, .cs kodu içeriyor.
-CppSDK [varsayılan değer '']	CppSDK Dizini
-DataRoot [varsayılan değer 'DataRoot ortam değişkeni']	Yerel çalıştırma için DataRoot, varsayılan olarak 'LOCALRUN_DATAROOT' ortam değişkeni
-MessageOut [varsayılan değer '']	Konsoldaki iletileri dosyaya döküm etme
-Referanslar [varsayılan değer '']	';' ile ayrılmış ek başvuru derlemelerine veya arka planda kod veri dosyalarına giden yolların listesi
-Shallow [varsayılan değer 'Yanlış']	Yüzeysel derleme
-UdoRedirect [varsayılan değer 'False']	Udo bileşen yeniden yönlendirme yapılandırmasını oluşturma
-UseDatabase [varsayılan değer 'master']	Geçici derleme kaydının arkasındaki kod için kullanılacak veritabanı
-WorkDir [varsayılan değer 'Current Directory']	Derleyici kullanımı ve çıkışları için dizin
-RunScopeCEP [varsayılan değer '0']	Kullanılacak olan ScopeCEP modu
-ScopeCEPTempPath [varsayılan değer 'temp']	Akış verileri için geçici olarak kullanılacak yol
-OptFlags [varsayılan değer '']	İyileştirici bayraklarının virgülle ayrılmış listesi

Aşağıda bazı kullanım örnekleri verilmiştir.

U-SQL betiğini derleyin:

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

Bir U-SQL betiği derleyin ve data-root klasörünü ayarlayın. Bu, ayarlanan ortam değişkenini değiştirecek.

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

Bir U-SQL betiği derleyin ve bir çalışma dizini, başvuru derlemesi ve veritabanı ayarlayın:

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

Derlenmiş sonuçları yürütme

Execute komutu derlenmiş sonuçları yürütmek için kullanılır.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Yürütme için isteğe bağlı bağımsız değişkenler şunlardır:

Tartışma	Varsayılan değer	Açıklama
-DataRoot	''	Meta veri yürütme için veri kök dizini. Varsayılan olarak LOCALRUN_DATAROOT ortam değişkenidir.
-MessageOut	''	Konsoldaki iletileri bir dosyaya döküm etme.
-Paralel	'1'	Oluşturulan yerel çalıştırma adımlarını belirtilen paralellik düzeyiyle çalıştırma göstergesi.
-Fazla Ayrıntılı	Yanlış	Çalışma zamanından gelen ayrıntılı çıktıları gösteren bir gösterge.

Kullanım örneği aşağıda verilmiştir:

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

SDK'yi programlama arabirimleriyle kullanma

Programlama arabirimlerinin tümü LocalRunHelper.exe'da bulunur. U-SQL SDK'sının ve C# test çerçevesinin işlevlerini tümleştirerek U-SQL betik yerel testinizi ölçeklendirmek için bunları kullanabilirsiniz. Bu makalede, U-SQL betiğinizi test etmek için bu arabirimlerin nasıl kullanılacağını göstermek için standart C# birim testi projesini kullanacağım.

1. Adım: C# birim testi projesi ve yapılandırması oluşturma

Dosya > Yeni > Proje > Visual C# > Test > Birim Test Projesi aracılığıyla bir C# birim testi projesi oluşturun.
Projeye LocalRunHelper.exe'ı referans olarak ekleyin. LocalRunHelper.exe, NuGet paketinde \build\runtime\LocalRunHelper.exe yer alır.
U-SQL SDK yalnızca x64 ortamını destekler, derleme platformu hedefini x64 olarak ayarladığınızdan emin olun. Bunu Proje Özelliği > Derleme > Platform hedefi aracılığıyla ayarlayabilirsiniz.
Test ortamınızı x64 olarak ayarladığınızdan emin olun. Visual Studio'da Test > Test Ayarları > Varsayılan İşlemci Mimarisi > x64 aracılığıyla ayarlayabilirsiniz.
NugetPackage\build\runtime\ altındaki tüm bağımlılık dosyalarını genellikle ProjectFolder\bin\x64\Debug altındaki project çalışma dizinine kopyaladığınızdan emin olun.

2. Adım: U-SQL betik testi çalışması oluşturma

Aşağıda U-SQL betik testi için örnek kod verilmiştir. Test için betikleri, giriş dosyalarını ve beklenen çıkış dosyalarını hazırlamanız gerekir.

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 programlama arabirimleri

LocalRunHelper.exe, U-SQL yerel derleme, çalıştırma vb. için programlama arabirimleri sağlar. Arabirimler aşağıdaki gibi listelenir.

Yapıcı

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

Parametre	Türü	Açıklama
mesajÇıktısı	System.IO.TextWriter	çıkış iletilerini Konsol kullanmak için null olarak ayarlayın

Özellikler

Mülkiyet	Türü	Açıklama
AlgebraPath	String	Cebir dosyasının yolu (cebir dosyası derleme sonuçlarından biridir)
CodeBehindReferences	String	Betikte başka arka plan kodu referansları varsa, yolları ';' ile ayrılmış olarak belirtin.
CppSdkDir	String	CppSDK dizini
MevcutDizin	String	Geçerli dizin
DataRoot	String	Veri kök yolu
DebuggerMailPath	String	Hata ayıklayıcı için mailslot yolu
GenerateUdoRedirect	Boole	Derleme yüklemesi için yeniden yönlendirme geçersiz kılma yapılandırması üretmek istiyorsak
HasCodeBehind	Boole	Scriptin arkasında destekleyici kod varsa
InputDir	String	Giriş verileri için dizin
Mesaj Yolu	String	Mesaj döküm dosyasının yolu
OutputDir	String	Çıktı verileri için dizin
Paralellik	Int	Cebir işlemlerini yürütmek için paralellik
ParentPid	Int	Hizmetin çıkışını izlediği üst öğeye ait PID, yoksaymak için 0 veya negatif olarak ayarlanır
ResultPath	String	Sonuç dökümü dosya yolu
RuntimeDir	String	Çalışma Zamanı Klasörü
ScriptPath	String	Betiği nerede bulabilirim?
Sığ	Boole	Sığ derleme veya değil
TempDir	String	Geçici dizin
VeritabanıKullan	String	Geçici derleme kaydının arkasındaki kod için kullanılacak veritabanını varsayılan olarak ana değer olarak belirtin
WorkDir	String	Tercih edilen çalışma dizini

Yöntem

Yöntem	Açıklama	Dönmek	Parametre
public bool DoCompile()	U-SQL betiğini derleme	Başarılı olduğunda doğru
public bool DoExec()	Derlenen sonucu yürütme	Başarılı olduğunda doğru
public bool DoRun()	U-SQL betiğini çalıştırma (Derleme + Yürütme)	Başarılı olduğunda doğru
public bool IsValidRuntimeDir(dize yolu)	Verilen yolun geçerli bir çalışma zamanı yolu olup olmadığını denetleyin	Geçerliyse doğru	Çalışma zamanı dizininin yolu

SSS: Yaygın Sorunlar Hakkında

Hata 1

E_CSC_SYSTEM_INTERNAL: Dahili hata! 'ScopeEngineManaged.dll' dosyası veya derlemesi veya bağımlılıklarından biri yüklenemedi. Belirtilen modül bulunamadı.

Aşağıdakileri denetleyin:

x64 ortamınız olduğundan emin olun. Derleme hedef platformu ve test ortamı x64 olmalıdır. Yukarıdaki 1. Adım: C# birim testi projesi ve yapılandırması oluşturma bölümüne bakın.
NugetPackage\build\runtime\ altındaki tüm bağımlılık dosyalarını project working dizinine kopyaladığınızdan emin olun.

Sonraki adımlar

U-SQL öğrenmek için bkz. Azure Data Lake Analytics U-SQL dilini kullanmaya başlama .
Tanılama bilgilerini günlüğe kaydetmek için bkz. Azure Data Lake Analytics için tanılama günlüklerine erişme.
Daha karmaşık bir sorgu görmek için bkz . Azure Data Lake Analytics kullanarak web sitesi günlüklerini analiz etme.
İş ayrıntılarını görüntülemek için bkz. Azure Data Lake Analytics işleri için İş Tarayıcısı ve İş Görünümü'nü kullanma.
Köşe yürütme görünümünü kullanmak için bkz. Visual Studio için Data Lake Araçları'nda Köşe Yürütme Görünümünü Kullanma.

Last updated on 2023-12-20

Aracılığıyla paylaş