تشغيل واختبار U-SQL باستخدام Azure Data Lake U-SQL SDK

مقالة
12/20/2023

هام

تم إيقاف Azure Data Lake Analytics في 29 فبراير 2024. تعرف على المزيد من خلال هذا الإعلان.

بالنسبة لتحليلات البيانات، يمكن لمؤسستك استخدام Azure Synapse Analytics أو Microsoft Fabric.

عند تطوير البرنامج النصي U-SQL، من الشائع تشغيل البرنامج النصي U-SQL واختباره محليا قبل إرساله إلى السحابة. يوفر Azure Data Lake حزمة NuGet تسمى Azure Data Lake U-SQL SDK لهذا السيناريو، والتي يمكنك من خلالها بسهولة توسيع نطاق تشغيل U-SQL واختباره. من الممكن أيضا دمج اختبار U-SQL هذا مع نظام CI (التكامل المستمر) لأتمتة التحويل البرمجي والاختبار.

إذا كنت تهتم بكيفية تشغيل البرنامج النصي U-SQL وتصحيحه يدويا باستخدام أدوات واجهة المستخدم الرسومية، فيمكنك استخدام Azure Data Lake Tools ل Visual Studio لذلك. يمكنك معرفة المزيد من هنا.

تثبيت Azure Data Lake U-SQL SDK

يمكنك الحصول على Azure Data Lake U-SQL SDK هنا على Nuget.org. وقبل استخدامه، تحتاج إلى التأكد من أن لديك تبعيات كما يلي.

التبعيات

يتطلب Data Lake U-SQL SDK التبعيات التالية:

Microsoft .NET Framework 4.6 أو أحدث.
Microsoft Visual C++ 14 و Windows SDK 10.0.10240.0 أو أحدث (والذي يسمى CppSDK في هذه المقالة). هناك طريقتان للحصول على CppSDK:
- تثبيت Visual Studio Community Edition. سيكون لديك مجلد \Windows Kits\10 ضمن مجلد ملفات البرنامج- على سبيل المثال، C:\Program Files (x86)\Windows Kits\10. ستجد أيضا إصدار Windows 10 SDK ضمن \Windows Kits\10\Lib. إذا لم تشاهد هذه المجلدات، فقم بإعادة تثبيت Visual Studio وتأكد من تحديد Windows 10 SDK أثناء التثبيت. إذا كان لديك هذا مثبتا مع Visual Studio، فسيجده المحول البرمجي المحلي U-SQL تلقائيا.
- تثبيت Data Lake Tools ل Visual Studio. يمكنك العثور على ملفات Visual C++ وملفات Windows SDK الجاهزة فيC:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.
  
  في هذه الحالة، لا يمكن للمحول البرمجي المحلي U-SQL العثور على التبعيات تلقائيا. تحتاج إلى تحديد مسار CppSDK له. يمكنك إما نسخ الملفات إلى موقع آخر أو استخدامها كما هي.

فهم المفاهيم الأساسية

جذر البيانات

مجلد جذر البيانات هو "مخزن محلي" لحساب الحساب المحلي. وهو يعادل حساب Azure Data Lake Store لحساب Data Lake Analytics. يعد التبديل إلى مجلد جذر بيانات مختلف تماما مثل التبديل إلى حساب مخزن مختلف. إذا كنت ترغب في الوصول إلى البيانات المشتركة بشكل شائع مع مجلدات مختلفة لجذر البيانات، فيجب عليك استخدام مسارات مطلقة في البرامج النصية الخاصة بك. أو قم بإنشاء ارتباطات رمزية لنظام الملفات (على سبيل المثال، mklink على NTFS) ضمن مجلد جذر البيانات للإشارة إلى البيانات المشتركة.

يتم استخدام مجلد جذر البيانات من أجل:

تخزين بيانات التعريف المحلية، بما في ذلك قواعد البيانات والجداول والوظائف ذات القيمة الجدولية (TVFs) والتجميعات.
ابحث عن مسارات الإدخال والإخراج التي تم تعريفها على أنها مسارات نسبية في U-SQL. يسهل استخدام المسارات النسبية نشر مشاريع U-SQL إلى Azure.

مسار الملف في U-SQL

يمكنك استخدام مسار نسبي ومسار مطلق محلي في البرامج النصية U-SQL. المسار النسبي نسبة إلى مسار مجلد جذر البيانات المحدد. نوصي باستخدام "/" كفاصل المسار لجعل البرامج النصية متوافقة مع جانب الخادم. فيما يلي بعض الأمثلة على المسارات النسبية والمسارات المطلقة المكافئة لها. في هذه الأمثلة، C:\LocalRunDataRoot هو مجلد جذر البيانات.

المسار النسبي	المسار المطلق
/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

دليل العمل

عند تشغيل البرنامج النصي U-SQL محليا، يتم إنشاء دليل عمل أثناء التحويل البرمجي ضمن دليل قيد التشغيل الحالي. بالإضافة إلى مخرجات التحويل البرمجي، سيتم نسخ ملفات وقت التشغيل المطلوبة للتنفيذ المحلي ظلا إلى دليل العمل هذا. يسمى المجلد الجذر لدليل العمل "ScopeWorkDir" والملفات الموجودة ضمن دليل العمل كما يلي:

الدليل/الملف	الدليل/الملف	الدليل/الملف	التعريف	الوصف
C6A101DDCB470506			سلسلة التجزئة لإصدار وقت التشغيل	نسخة ظلية من ملفات وقت التشغيل اللازمة للتنفيذ المحلي
	Script_66AE4909AA0ED06C		اسم البرنامج النصي + سلسلة التجزئة لمسار البرنامج النصي	مخرجات التحويل البرمجي وتسجيل خطوة التنفيذ
		_script_.abr	إخراج المحول البرمجي	ملف الجبر
		_ScopeCodeGen_.*	إخراج المحول البرمجي	التعليمات البرمجية المدارة التي تم إنشاؤها
		_ScopeCodeGenEngine_.*	إخراج المحول البرمجي	التعليمات البرمجية الأصلية التي تم إنشاؤها
		التجميعات المشار إليها	مرجع التجميع	ملفات التجميع المشار إليها
		deployed_resources	توزيع الموارد	ملفات توزيع الموارد
		xxxxxxxx.xxx[1..n]_.	سجل التنفيذ	سجل خطوات التنفيذ

استخدام SDK من سطر الأوامر

واجهة سطر الأوامر لتطبيق المساعد

ضمن دليل SDK\build\runtime، LocalRunHelper.exe هو تطبيق مساعد سطر الأوامر الذي يوفر واجهات لمعظم وظائف التشغيل المحلي شائعة الاستخدام. كل من الأمر ومفاتيح تبديل الوسيطة حساسة لحالة الأحرف. لاستدعائه:

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

قم بتشغيل LocalRunHelper.exe بدون وسيطات أو باستخدام مفتاح التعليمات لإظهار معلومات التعليمات:

> 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

في معلومات التعليمات:

يعطي الأمر اسم الأمر.
تسرد الوسيطة المطلوبة الوسيطات التي يجب توفيرها.
تسرد الوسيطة الاختيارية الوسيطات الاختيارية، مع القيم الافتراضية. لا تحتوي الوسيطات المنطقية الاختيارية على معلمات، وتعني مظاهرها سلبية على قيمتها الافتراضية.

القيمة المرجعة والتسجيل

يقوم تطبيق المساعد بإرجاع 0 للنجاح و-1 للفشل. بشكل افتراضي، يرسل المساعد جميع الرسائل إلى وحدة التحكم الحالية. ومع ذلك، تدعم معظم الأوامر الوسيطة -MessageOut path_to_log_file الاختيارية التي تعيد توجيه المخرجات إلى ملف سجل.

تكوين متغير البيئة

يحتاج التشغيل المحلي U-SQL إلى جذر بيانات محدد كحساب تخزين محلي، ومسار CppSDK محدد للتبعيات. يمكنك تعيين الوسيطة في سطر الأوامر أو تعيين متغير البيئة لها.

تعيين متغير البيئة SCOPE_CPP_SDK .

إذا حصلت على Microsoft Visual C++ Windows SDK عن طريق تثبيت Data Lake Tools ل Visual Studio، فتحقق من أن لديك المجلد التالي:

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

تعريف متغير بيئة جديد يسمى SCOPE_CPP_SDK للإشارة إلى هذا الدليل. أو انسخ المجلد إلى الموقع الآخر وحدد SCOPE_CPP_SDK على هذا النحو.

بالإضافة إلى تعيين متغير البيئة، يمكنك تحديد الوسيطة -CppSDK عند استخدام سطر الأوامر. تستبدل هذه الوسيطة متغير بيئة CppSDK الافتراضي.
تعيين متغير البيئة LOCALRUN_DATAROOT .

حدد متغير بيئة جديدا يسمى LOCALRUN_DATAROOT يشير إلى جذر البيانات.

بالإضافة إلى تعيين متغير البيئة، يمكنك تحديد الوسيطة -DataRoot مع مسار جذر البيانات عند استخدام سطر أوامر. تستبدل هذه الوسيطة متغير بيئة جذر البيانات الافتراضي. تحتاج إلى إضافة هذه الوسيطة إلى كل سطر أوامر تقوم بتشغيله بحيث يمكنك الكتابة فوق متغير البيئة الافتراضي لجذر البيانات لجميع العمليات.

نماذج استخدام سطر أوامر SDK

تجميع وتشغيل

يتم استخدام أمر التشغيل لتحويل البرنامج النصي برمجيا ثم تنفيذ النتائج المحولة برمجيا. وسيطات سطر الأوامر الخاصة به هي مزيج من تلك من التحويل البرمجيوالتنفيذ.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

فيما يلي وسيطات اختيارية للتشغيل:

وسيطة	القيمة الافتراضية	الوصف
-CodeBehind	خطأ	يحتوي البرنامج النصي على تعليمات برمجية .cs في الخلف
-CppSDK		دليل CppSDK
-DataRoot	متغير بيئة DataRoot	DataRoot للتشغيل المحلي، افتراضيا إلى متغير البيئة "LOCALRUN_DATAROOT"
-MessageOut		تفريغ الرسائل على وحدة التحكم إلى ملف
-موازيه	1	تشغيل الخطة بالتوازي المحدد
-مراجع		قائمة المسارات إلى تجميعات مرجعية إضافية أو ملفات بيانات التعليمات البرمجية في الخلف، مفصولة ب ';'
-UdoRedirect	خطأ	إنشاء تكوين إعادة توجيه تجميع Udo
-UseDatabase	الرئيسي	قاعدة بيانات لاستخدامها في التعليمات البرمجية خلف التسجيل المؤقت للتجميع
رسالة مطولة	خطأ	إظهار المخرجات التفصيلية من وقت التشغيل
-WorkDir	الدليل الحالي	دليل لاستخدام المحول البرمجي والمخرجات
-RunScopeCEP	0	وضع ScopeCEP المراد استخدامه
-ScopeCEPTempPath	Temp	المسار المؤقت لاستخدامه في دفق البيانات
-OptFlags		قائمة مفصولة بفواصل من علامات المحسن

وفيما يلي مثال على ذلك:

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

بالإضافة إلى الجمع بين التحويل البرمجيوالتنفيذ، يمكنك تحويل الملفات التنفيذية المحولة برمجيا وتنفيذها بشكل منفصل.

تحويل برنامج نصي U-SQL برمجيا

يتم استخدام أمر التحويل البرمجي لتحويل برنامج نصي U-SQL برمجيا إلى ملفات تنفيذية.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

فيما يلي وسيطات اختيارية للترجمة البرمجية:

وسيطة	الوصف
-CodeBehind [القيمة الافتراضية 'False']	يحتوي البرنامج النصي على تعليمات برمجية .cs في الخلف
-CppSDK [القيمة الافتراضية '']	دليل CppSDK
-DataRoot [القيمة الافتراضية 'متغير بيئة DataRoot']	DataRoot للتشغيل المحلي، افتراضيا إلى متغير البيئة "LOCALRUN_DATAROOT"
-MessageOut [القيمة الافتراضية '']	تفريغ الرسائل على وحدة التحكم إلى ملف
-المراجع [القيمة الافتراضية '']	قائمة المسارات إلى تجميعات مرجعية إضافية أو ملفات بيانات التعليمات البرمجية في الخلف، مفصولة ب ';'
-الضحلة [القيمة الافتراضية 'خطأ']	التحويل البرمجي الضحل
-UdoRedirect [القيمة الافتراضية 'False']	إنشاء تكوين إعادة توجيه تجميع Udo
-UseDatabase [القيمة الافتراضية 'master']	قاعدة بيانات لاستخدامها في التعليمات البرمجية خلف التسجيل المؤقت للتجميع
-WorkDir [القيمة الافتراضية 'الدليل الحالي']	دليل لاستخدام المحول البرمجي والمخرجات
-RunScopeCEP [القيمة الافتراضية '0']	وضع ScopeCEP المراد استخدامه
-ScopeCEPTempPath [القيمة الافتراضية 'temp']	المسار المؤقت لاستخدامه في دفق البيانات
-OptFlags [القيمة الافتراضية '']	قائمة مفصولة بفواصل من علامات المحسن

فيما يلي بعض أمثلة الاستخدام.

تحويل برنامج نصي U-SQL برمجيا:

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

تجميع برنامج نصي U-SQL وتعيين مجلد جذر البيانات. سيؤدي ذلك إلى الكتابة فوق متغير البيئة المحدد.

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

تجميع برنامج نصي U-SQL وتعيين دليل عمل وتجميع مرجعي وقاعدة بيانات:

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

تنفيذ النتائج المحولة برمجيا

يتم استخدام أمر التنفيذ لتنفيذ النتائج المحولة برمجيا.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

فيما يلي وسيطات اختيارية للتنفيذ:

وسيطة	القيمة الافتراضية	الوصف
-DataRoot	''	جذر البيانات لتنفيذ بيانات التعريف. يتم تعيينه افتراضيا إلى متغير البيئة LOCALRUN_DATAROOT .
-MessageOut	''	تفريغ الرسائل على وحدة التحكم إلى ملف.
-موازيه	'1'	مؤشر لتشغيل خطوات التشغيل المحلي التي تم إنشاؤها بمستوى التوازي المحدد.
رسالة مطولة	"خطأ"	مؤشر لإظهار المخرجات التفصيلية من وقت التشغيل.

فيما يلي مثال على الاستخدام:

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

استخدام SDK مع واجهات البرمجة

توجد جميع واجهات البرمجة في LocalRunHelper.exe. يمكنك استخدامها لدمج وظائف U-SQL SDK وإطار عمل اختبار C# لتوسيع نطاق الاختبار المحلي للبرنامج النصي U-SQL. في هذه المقالة، سأستخدم مشروع اختبار وحدة C# القياسي لإظهار كيفية استخدام هذه الواجهات لاختبار البرنامج النصي U-SQL.

الخطوة 1: إنشاء مشروع اختبار وحدة C# وتكوينها

إنشاء مشروع اختبار وحدة C# من خلال مشروع اختبار وحدة اختبار File > New > Project > Visual C#>.>
أضف LocalRunHelper.exe كمرجع للمشروع. يقع LocalRunHelper.exe في \build\runtime\LocalRunHelper.exe في حزمة NuGet.
يدعم U-SQL SDK بيئة x64 فقط ، وتأكد من تعيين هدف النظام الأساسي للبناء على أنه x64. يمكنك تعيين ذلك من خلال هدف Project Property > Build > Platform.
تأكد من تعيين بيئة الاختبار الخاصة بك على x64. في Visual Studio، يمكنك تعيينه من خلال Test > Test Settings > Default Processor Architecture > x64.
تأكد من نسخ جميع ملفات التبعية ضمن NugetPackage\build\runtime\ إلى دليل عمل المشروع، والذي يكون عادة ضمن ProjectFolder\bin\x64\Debug.

الخطوة 2: إنشاء حالة اختبار البرنامج النصي U-SQL

فيما يلي نموذج التعليمات البرمجية لاختبار البرنامج النصي U-SQL. للاختبار، تحتاج إلى إعداد البرامج النصية وملفات الإدخال وملفات الإخراج المتوقعة.

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

يوفر LocalRunHelper.exe واجهات البرمجة للترجمة البرمجية المحلية U-SQL وتشغيلها وما إلى ذلك. يتم سرد الواجهات على النحو التالي.

الدالمنشئ

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

المعلَمة	النوع	الوصف
معدل نقل الرسائل	System.IO.TextWriter	لرسائل الإخراج، قم بتعيين إلى خال لاستخدام وحدة التحكم

الخصائص

الخاصية	النوع	الوصف
مسار الجبر	سلسلة	المسار إلى ملف الجبر (ملف الجبر هو أحد نتائج التحويل البرمجي)
CodeBehindReferences	سلسلة	إذا كان البرنامج النصي يحتوي على تعليمات برمجية أخرى خلف المراجع، فحدد المسارات المفصولة ب ';'
CppSdkDir	سلسلة	دليل CppSDK
CurrentDir	سلسلة	الدليل الحالي
DataRoot	سلسلة	مسار جذر البيانات
DebuggerMailPath	سلسلة	المسار إلى مصحح الأخطاء mailslot
GenerateUdoRedirect	Bool	إذا أردنا إنشاء تجاوز إعادة توجيه تحميل التجميع
HasCodeBehind	Bool	إذا كان البرنامج النصي يحتوي على تعليمات برمجية في الخلف
InputDir	سلسلة	دليل لبيانات الإدخال
مسار الرسالة	سلسلة	مسار ملف تفريغ الرسائل
OutputDir	سلسلة	دليل لبيانات الإخراج
تماثل	int	التوازي لتشغيل الجبر
ParentPid	int	PID للأصل الذي تراقب الخدمة الخروج منه، أو تعيينه إلى 0 أو سالب لتجاهله
مسار النتائج	سلسلة	مسار ملف تفريغ النتائج
وقت التشغيلDir	سلسلة	دليل وقت التشغيل
مسار البرنامج النصي	سلسلة	مكان العثور على البرنامج النصي
الضحله	Bool	التحويل البرمجي الضحل أم لا
TempDir	سلسلة	الدليل المؤقت
UseDataBase	سلسلة	حدد قاعدة البيانات لاستخدامها للتعليمات البرمجية خلف تسجيل التجميع المؤقت، رئيسي بشكل افتراضي
WorkDir	سلسلة	دليل العمل المفضل

الأسلوب

الأسلوب	الوصف	العوده	المعلمة
bool DoCompile العام()	تحويل البرنامج النصي U-SQL برمجيا	صواب في النجاح
bool DoExec() العام	تنفيذ النتيجة المحولة برمجيا	صواب في النجاح
bool DoRun() العامة	تشغيل البرنامج النصي U-SQL (التحويل البرمجي + التنفيذ)	صواب في النجاح
bool العام IsValidRuntimeDir (مسار السلسلة)	تحقق مما إذا كان المسار المحدد مسار وقت تشغيل صالحا	صحيح للصالح	مسار دليل وقت التشغيل

الأسئلة المتداولة حول المشكلة الشائعة

الخطأ 1

E_CSC_SYSTEM_INTERNAL: خطأ داخلي! تعذر تحميل الملف أو التجميع "ScopeEngineManaged.dll" أو أحد تبعياته. تعذر العثور على الوحدة النمطية المحددة.

تحقق من الأشياء التالية:

تأكد من أن لديك بيئة x64. يجب أن يكون النظام الأساسي الهدف للبناء وبيئة الاختبار x64، راجع الخطوة 1: إنشاء مشروع اختبار وحدة C# والتكوين أعلاه.
تأكد من نسخ جميع ملفات التبعية ضمن NugetPackage\build\runtime\ إلى دليل عمل المشروع.

الخطوات التالية

لمعرفة U-SQL، راجع بدء استخدام لغة Azure Data Lake Analytics U-SQL.
لتسجيل معلومات التشخيص، راجع الوصول إلى سجلات التشخيص ل Azure Data Lake Analytics.
لمشاهدة استعلام أكثر تعقيدا، راجع تحليل سجلات موقع الويب باستخدام Azure Data Lake Analytics.
لعرض تفاصيل المهمة، راجع استخدام مستعرض الوظيفة وعرض الوظيفة لوظائف Azure Data Lake Analytics.
لاستخدام طريقة عرض تنفيذ الذروة، راجع استخدام طريقة عرض تنفيذ الذروة في Data Lake Tools ل Visual Studio.

مشاركة عبر