استمرار بيانات المهام إلى تخزين Azure باستخدام واجهة برمجة تطبيقات خدمة Batch

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

لخيارات حساب التخزين في الدفعة، راجع حسابات الدفعات وحسابات تخزين Azure.

تدعم واجهة برمجة تطبيقات خدمة الدفعات بيانات الإخراج المستمرة إلى تخزين Azure للمهام ومهام مدير الوظائف التي تعمل على مجموعات مع تكوين الآلة الافتراضية. عند إضافة مهمة، يمكنك تحديد حاوية في تخزين Azure كوجهة لمخرجات المهمة. ثم تكتب خدمة الدفعة أي بيانات إخراج إلى تلك الحاوية عند اكتمال المهمة.

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

مهم

استمرار بيانات المهام إلى تخزين Azure باستخدام واجهة برمجة تطبيقات خدمة Batch لا يعمل مع مجموعات المجمعات التي تم إنشاؤها قبل 1 فبراير 2018.

متى أستخدم واجهة برمجة تطبيقات خدمة الدفعة لاستمرار إخراج المهام؟

يوفر Azure Batch أكثر من طريقة واحدة لاستمرار إخراج المهام. استخدام واجهة برمجة تطبيقات الخدمة الدفعية هو نهج مريح يناسب هذه السيناريوهات:

  • تريد كتابة كود لاستمرار مخرجات المهمة من داخل تطبيق العميل الخاص بك، دون تعديل التطبيق الذي تشغل مهمتك.
  • تريد الحفاظ على مخرجات مهام Batch ومهام مدير الوظائف في مجموعات تم إنشاؤها باستخدام تكوين الآلة الافتراضية.
  • تريد استمرار الإخراج إلى حاوية تخزين Azure باسم عشوائي.
  • تريد أن تستمر في الإخراج إلى حاوية تخزين Azure مسماة وفقا لمعيار اتفاقيات الملفات الدفعية.

إذا كان سيناريوك مختلفا عن ما ذكر أعلاه، فقد تحتاج إلى التفكير في نهج مختلف. على سبيل المثال، واجهة برمجة تطبيقات خدمة الدفعات لا تدعم حاليا تدفق المخرجات إلى تخزين Azure أثناء تشغيل المهمة. لبث الإخراج، فكر في استخدام مكتبة اتفاقيات ملفات الدفعة المتاحة ل .NET. بالنسبة للغات الأخرى، ستحتاج إلى تنفيذ حلك الخاص. لمزيد من المعلومات حول الخيارات الأخرى، راجع استمرار إخراج المهام والمهام إلى تخزين Azure.

إنشاء حاوية في تخزين Azure

لاستمرار مخرجات المهام في تخزين Azure، ستحتاج إلى إنشاء حاوية تكون وجهة لملفات الإخراج الخاصة بك. أنشئ الحاوية قبل تنفيذ مهمتك، ويفضل أن يكون ذلك قبل تقديم مهمتك، باستخدام مكتبة عملاء تخزين Azure أو SDK المناسبة. لمزيد من المعلومات حول واجهات برمجة تطبيقات تخزين Azure، راجع وثائق تخزين Azure.

على سبيل المثال، إذا كنت تكتب تطبيقك بلغة C#، استخدم مكتبة عملاء تخزين Azure ل .NET. يوضح المثال التالي طريقة إنشاء حاوية:

BlobContainerClient container = storageAccount.GetBlobContainerClient(containerName);
await container.CreateIfNotExistsAsync();

حدد ملفات الإخراج لإخراج المهمة

لتحديد ملفات الإخراج لمهمة، أنشئ مجموعة من كائنات OutputFile وخصصها لخاصية BatchTaskCreateOptions.OutputFiles عند إنشاء المهمة. يمكنك استخدام توقيع الوصول المشترك (SAS) أو هوية مدارة لتوثيق الوصول إلى الحاوية.

استخدام توقيع الوصول المشترك

بعد إنشاء الحاوية، احصل على توقيع وصول مشترك (SAS) مع إمكانية الكتابة إلى الحاوية. يوفر SAS وصولا مفوضا إلى الحاوية. يمنح نظام SAS الوصول بمجموعة محددة من الأذونات وخلال فترة زمنية محددة. تحتاج خدمة الدفعات إلى SAS مع صلاحيات كتابة لكتابة مخرجات المهمة إلى الحاوية. لمزيد من المعلومات حول SAS، راجع استخدام توقيعات الوصول المشترك (SAS) في تخزين Azure.

عندما تحصل على SAS باستخدام واجهات تخزين Azure APIs، تعيد واجهة برمجة التطبيقات سلسلة رموز SAS. تتضمن هذه السلسلة الرمزية جميع معلمات SAS، بما في ذلك الأذونات والفترة التي يكون فيها SAS صالحا. لاستخدام SAS للوصول إلى حاوية في تخزين Azure، تحتاج إلى إضافة سلسلة رموز SAS إلى رابط URI الخاص بالمورد. يوفر URI الخاص بالمورد، مع رمز SAS المرفق، وصولا مصدقا إلى تخزين Azure.

يوضح المثال التالي كيفية الحصول على سلسلة رموز SAS للكتابة فقط للحاوية، ثم تضم SAS إلى رابط الحاوية:

BlobSasBuilder sasBuilder = new BlobSasBuilder(BlobContainerSasPermissions.Write, DateTimeOffset.UtcNow.AddDays(1))
{
    BlobContainerName = container.Name,
    Resource = "c"
};

Uri containerSasUrl = container.GenerateSasUri(sasBuilder);

مثال كود C# التالي ينشئ مهمة تكتب أرقاما عشوائية على ملف يسمى output.txt. ينشئ المثال ملف إخراج ليتم output.txt كتابته على الحاوية. كما ينشئ المثال ملفات إخراج لأي ملفات سجل تطابق نمط std*.txt الملف (مثلstdout.txt و stderr.txt). يتطلب رابط الحاوية SAS الذي تم إنشاؤه سابقا للحاوية. تستخدم خدمة الدفعة SAS للتحقق من الوصول إلى الحاوية.

BatchTaskCreateOptions task = new BatchTaskCreateOptions(taskId,
    "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles =
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination()
            {
                Container = new OutputFileBlobContainerDestination(containerSasUri) { Path = taskId }
            },
            uploadOptions: new OutputFileUploadConfig(OutputFileUploadCondition.TaskCompletion)),
        new OutputFile(
            filePattern: @"output.txt",
            destination: new OutputFileDestination()
            {
                Container = new OutputFileBlobContainerDestination(containerSasUri) { Path = taskId + @"\output.txt" }
            },
            uploadOptions: new OutputFileUploadConfig(OutputFileUploadCondition.TaskCompletion)),
    }
};

‏‫ملاحظة‬

إذا كنت تستخدم هذا المثال مع لينكس، تأكد من تغيير الخطوط الارتدادية إلى الخطوط العريضة.

استخدام الهوية المدارة

بدلا من إنشاء وتمرير SAS مع وصول كتابي إلى الحاوية إلى الدفعة، يمكن استخدام هوية مدارة للمصادقة باستخدام تخزين Azure. يجب تعيين الهوية إلى تجمع الدفعات، وأن يكون لها Storage Blob Data Contributor أيضا تعيين الدور الذي يكتب عليه الحاوية. يمكن بعد ذلك أن تطلب من خدمة الدفعة استخدام الهوية المدارة بدلا من SAS لتوثيق الوصول إلى الحاوية.

BatchTaskCreateOptions task = new BatchTaskCreateOptions(taskId,
    "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles =
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination()
            {
                Container = new OutputFileBlobContainerDestination(containerUri)
                {
                    Path = taskId,
                    IdentityReference = new BatchNodeIdentityReference()
                    {
                        ResourceId = new ResourceIdentifier(identityResourceId)
                    }
                }
            },
            uploadOptions: new OutputFileUploadConfig(OutputFileUploadCondition.TaskCompletion)),
    }
};

حدد نمط ملف للمطابقة

عند تحديد ملف إخراج، يمكنك استخدام خاصية OutputFile.FilePattern لتحديد نمط ملف للمطابقة. قد يتطابق نمط الملف مع صفر ملفات، أو ملف واحد، أو مجموعة من الملفات التي يتم إنشاؤها بواسطة المهمة.

تدعم خاصية FilePattern البطاقات البرية القياسية لأنظمة الملفات مثل * (للمطابقات غير التكرارية) و ** (للمطابقات التكرارية). على سبيل المثال، عينة الكود أعلاه تحدد نمط الملف ليتطابق std*.txt بشكل غير تكراري:

filePattern: @"..\std*.txt"

لرفع ملف واحد، حدد نمط ملف بدون رموز غير متوقعة. على سبيل المثال، عينة الكود أعلاه تحدد نمط الملف ليتطابق output.txt:

filePattern: @"output.txt"

حدد شرط الرفع

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

عينة الكود أعلاه تحدد خاصية UploadCondition إلى TaskCompletion. يحدد هذا الإعداد أن يتم رفع الملف بعد اكتمال المهام، بغض النظر عن قيمة رمز الخروج.

uploadCondition: OutputFileUploadCondition.TaskCompletion

للاطلاع على الإعدادات الأخرى، راجع ملف OutputFileUploadCondition enum.

توضيح الملفات التي تحمل نفس الاسم

قد تنتج المهام في المهمة ملفات تحمل نفس الاسم. على سبيل المثال، stdout.txt يتم إنشاء و stderr.txt لكل مهمة تنفذ في الوظيفة. نظرا لأن كل مهمة تعمل في سياقها الخاص، فإن هذه الملفات لا تتعارض مع نظام ملفات العقدة. ومع ذلك، عند رفع ملفات من عدة مهام إلى حاوية مشتركة، ستحتاج إلى توضيح الملفات التي تحمل نفس الاسم.

OutputFileBlobContainerDestination.تحدد خاصية المسار الكتلة الوجهة أو الدليل الافتراضي لملفات الإخراج. يمكنك استخدام خاصية Path لتسمية الكتلة أو الدليل الافتراضي بطريقة تجعل ملفات الإخراج التي تحمل نفس الاسم تسمى بشكل فريد في تخزين Azure. استخدام معرف المهمة في المسار هو طريقة جيدة لضمان أسماء فريدة وسهولة تحديد الملفات.

إذا كانت خاصية FilePattern مضبوطة على تعبير ورايف، فيتم رفع جميع الملفات التي تطابق النمط إلى الدليل الافتراضي المحدد بخاصية Path . على سبيل المثال، إذا كانت الحاوية هي mycontainer، ومعرف المهمة هو mytask، ونمط الملف هو ..\std*.txt، فإن ال URIs المطلقة لملفات الإخراج في تخزين Azure ستكون مشابهة ل:

https://myaccount.blob.core.windows.net/mycontainer/mytask/stderr.txt
https://myaccount.blob.core.windows.net/mycontainer/mytask/stdout.txt

إذا تم تعيين خاصية FilePattern لتطابق اسم ملف واحد، أي أنها لا تحتوي على أي أحرف غير مصدقة، فإن قيمة خاصية Path تحدد اسم الكتلة المؤهل بالكامل. إذا كنت تتوقع تعارضات في التسمية مع ملف واحد من عدة مهام، فقم بإدراج اسم الدليل الافتراضي كجزء من اسم الملف لتوضيح تلك الملفات. على سبيل المثال، اضبط خاصية المسار لتشمل معرف المهمة، وحرف المحدد (عادة خط مائل للأمام)، واسم الملف:

path: taskId + @"/output.txt"

ستكون نقاط الURI المطلقة لملفات الإخراج لمجموعة من المهام مشابهة ل:

https://myaccount.blob.core.windows.net/mycontainer/task1/output.txt
https://myaccount.blob.core.windows.net/mycontainer/task2/output.txt

لمزيد من المعلومات حول الأدلة الافتراضية في تخزين Azure، راجع قائمة الكتل في الحاوية.

العديد من ملفات الإخراج

عندما تحدد مهمة العديد من ملفات الإخراج، قد تواجه حدودا تفرضها واجهة برمجة تطبيقات Azure Batch API. من المستحسن أن تبقي مهامك صغيرة وأن تحافظ على عدد ملفات الإخراج منخفضة.

إذا واجهت حدودا، فكر في تقليل عدد ملفات الإخراج باستخدام أنماط الملفات أو استخدام حاويات ملفات مثل tar أو zip لتوحيد ملفات الإخراج. بدلا من ذلك، استخدم التركيب أو طرق أخرى لاستمرار بيانات الإخراج (انظر استمرار مخرجات المهام والمهام).

تشخيص أخطاء رفع الملفات

إذا فشل رفع ملفات الإخراج إلى تخزين Azure، تنتقل المهمة إلى حالة Completed ويتم تعيين خاصية BatchTaskExecutionInfo.FailureInfo. افحص خاصية FailureInformation لتحديد الخطأ الذي حدث. على سبيل المثال، هنا خطأ يحدث عند رفع الملف إذا لم يتم العثور على الحاوية:

Category: UserError
Code: FileUploadContainerNotFound
Message: One of the specified Azure container(s) was not found while attempting to upload an output file

عند كل رفع ملف، يكتب Batch ملفي سجل إلى عقدة الحوسبة، fileuploadout.txt و fileuploaderr.txt. يمكنك فحص ملفات السجلات هذه لمعرفة المزيد حول فشل معين. في الحالات التي لم تحاول فيها رفع الملف، مثل أن المهمة نفسها لم تكن بالإمكان تشغيلها، فلن توجد ملفات السجل هذه.

تشخيص أداء رفع الملفات

fileuploadout.txt الملفات تسجل تقدم الرفع. يمكنك مراجعة هذا الملف لمعرفة المزيد عن المدة التي تستغرقها رفع الملفات. ضع في اعتبارك أن هناك العديد من العوامل المساهمة في أداء الرفع، بما في ذلك حجم العقدة، والأنشطة الأخرى على العقدة وقت الرفع، وما إذا كانت الحاوية المستهدفة في نفس منطقة تجمع الدفعات، وعدد العقد التي ترفع إلى حساب التخزين في نفس الوقت، وهكذا.

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

عندما تقوم باستمرارية مخرجات المهام باستخدام واجهة برمجة تطبيقات خدمة الدفعة، يمكنك تسمية حاوية الوجهة والكتل كما تشاء. يمكنك أيضا اختيار تسميتها وفقا لمعيار قواعد ملفات الدفعات. يحدد معيار اتفاقيات الملفات أسماء الحاوية الوجهة والكتلة في تخزين Azure لملف إخراج معين بناء على أسماء المهمة والمهمة. إذا كنت تستخدم معيار ملفات الملف لتسمية ملفات الإخراج، فإن ملفات الإخراج متاحة للعرض في بوابة Azure.

إذا كنت تطور بلغة C#، يمكنك استخدام الطرق المدمجة في مكتبة اتفاقيات ملفات الدفعات ل .NET. هذه المكتبة تنشئ الحاويات ومسارات الكتل المسماة بشكل صحيح لك. على سبيل المثال، يمكنك استدعاء واجهة برمجة التطبيقات للحصول على الاسم الصحيح للحاوية بناء على اسم الوظيفة:

// Convention used by Azure.Batch.Conventions.Files: "job-{jobId}".
string containerName = $"job-{jobId.ToLowerInvariant()}";

يمكنك استخدام طريقة CloudJobExtensions.GetOutputStorageContainerUrl لإرجاع رابط توقيع الوصول المشترك (SAS) يستخدم للكتابة إلى الحاوية. يمكنك بعد ذلك تمرير هذا SAS إلى OutputFileBlobContainerDestinationconstructor .

إذا كنت تطور بلغة غير C#، فستحتاج إلى تنفيذ معيار قواعد الملفات بنفسك.

نموذج التعليمات البرمجية

مشروع عينات PersistOutputs هو أحد عينات كود Azure Batch على GitHub. يوضح هذا الحل من Visual Studio كيفية استخدام مكتبة عملاء Batch ل .NET لحفظ مخرجات المهام إلى تخزين متين. لتشغيل العينة، اتبع الخطوات التالية:

  1. افتح المشروع في Visual Studio 2019.
  2. أضف بيانات اعتماد حساب الدفعة والتخزين إلى AccountSettings.settings في مشروع Microsoft.Azure.Batch.Samples.Common.
  3. ابن الحل (لكن لا تعمل). قم باستعادة أي حزم NuGet إذا طلب منك ذلك.
  4. استخدم بوابة Azure لرفع حزمة تطبيقل PersistOutputsTask. تضمين التجميعات PersistOutputsTask.exe التابعة لها في حزمة .zip، وتعيين معرف التطبيق إلى "PersistOutputsTask"، وإصدار حزمة التطبيق إلى "1.0".
  5. ابدأ (قم بتشغيل) مشروع PersistOutputs .
  6. عند المطالبة باختيار تقنية الاستمرارية لتشغيل العينة، أدخل 2 لتشغيل العينة باستخدام واجهة خدمة الدفعات لاستمرار إخراج المهمة.
  7. إذا رغبت، قم بتشغيل العينة مرة أخرى، مع إدخال 3 لاستمرارية الإخراج باستخدام واجهة برمجة تطبيقات خدمة الدفعات، وكذلك لتسمية الحاوية الوجهة ومسار الكتلة وفقا لمعيار اتفاقيات الملفات.

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

  • تاريخ آخر تحديث في