مشاركة عبر

قم بالاحتفاظ ببيانات المهام في Azure Storage باستخدام واجهة برمجة التطبيقات لخدمة Batch

  • مقالة

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

للحصول على خيارات حساب التخزين في Batch، تأكد من مراجعة حسابات Batch وحسابات تخزين Azure.

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

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

هام

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

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

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

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

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

إنشاء حاوية في Azure Storage

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

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

CloudBlobContainer container = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
await container.CreateIfNotExists();

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

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

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

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

عندما تحصل على SAS باستخدام واجهات برمجة تطبيقات Azure Storage، تُرجع واجهة برمجة التطبيقات سلسلة رمز SAS مميز. تتضمن سلسلة الرمز المميز هذه جميع معلمات SAS، بما في ذلك الأذونات والفاصل الزمني الذي يكون SAS خلاله صالحًا. لاستخدام SAS للوصول إلى حاوية في Azure Storage، تحتاج إلى إلحاق سلسلة رمز SAS المميز بمعرّف الموارد المنتظم (URI). يوفر معرّف الموارد المنتظم (URI)، جنبًا إلى جنب مع رمز SAS المميز المُلحق، وصولاً حائزًا على المصادقة إلى Azure Storage.

يوضح المثال التالي كيفية الحصول على سلسلة رمز SAS المميز للكتابة فقط من أجل الحاوية، ثم إلحاق SAS بمُعرّف موارد منتظم للحاوية:

string containerSasToken = container.GetSharedAccessSignature(new SharedAccessBlobPolicy()
{
    SharedAccessExpiryTime = DateTimeOffset.UtcNow.AddDays(1),
    Permissions = SharedAccessBlobPermissions.Write
});

string containerSasUrl = container.Uri.AbsoluteUri + containerSasToken;

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

new CloudTask(taskId, "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles = new List<OutputFile>
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination(
         new OutputFileBlobContainerDestination(
                    containerUrl: containerSasUrl,
                    path: taskId)),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion)),
        new OutputFile(
            filePattern: @"output.txt",
            destination: 
         new OutputFileDestination(new OutputFileBlobContainerDestination(
                    containerUrl: containerSasUrl,
                    path: taskId + @"\output.txt")),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion)),
}

إشعار

إذا كنت تستخدم هذا المثال مع Linux، فتأكد من تغيير الشرطات المائلة إلى الخلف إلى شرطات مائلة إلى الأمام.

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

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

CloudBlobContainer container = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
await container.CreateIfNotExists();

new CloudTask(taskId, "cmd /v:ON /c \"echo off && set && (FOR /L %i IN (1,1,100000) DO (ECHO !RANDOM!)) > output.txt\"")
{
    OutputFiles = new List<OutputFile>
    {
        new OutputFile(
            filePattern: @"..\std*.txt",
            destination: new OutputFileDestination(
         new OutputFileBlobContainerDestination(
                    containerUrl: container.Uri,
                    path: taskId,
                    identityReference: new ComputeNodeIdentityReference() { ResourceId = "/subscriptions/SUB/resourceGroups/RG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name"} })),
            uploadOptions: new OutputFileUploadOptions(
            uploadCondition: OutputFileUploadCondition.TaskCompletion))
    }
}

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

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

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

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

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

filePattern: @"output.txt"

تحديد شرط تحميل

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

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

uploadCondition: OutputFileUploadCondition.TaskCompletion

للحصول على إعدادات أخرى، راجع قائمة تعداد OutputFileUploadCondition.

فرز الملفات التي تحمل الاسم نفسه

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

تحدد الخاصية OutputFileBlobContainerDestination.Path كائنًا ثنائيًّا كبير الحجم للوجهة أو دليلاً ظاهريًّا لملفات الإخراج. يمكنك استخدام خاصية المسار لتسمية كائن ثنائي كبير الحجم أو دليل ظاهري بالطريقة التي يتم من خلالها تسمية ملفات الإخراج التي تحمل الاسم نفسه بشكل فريد في Azure Storage. يعد استخدام معرف المهمة في المسار طريقة جيدة لتوفير الأسماء الفريدة وتحديد الملفات بسهولة.

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

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

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

path: taskId + @"/output.txt"

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

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

لمزيد من المعلومات حول الأدلة الظاهرية في Azure Storage، راجع إدراج كائنات ثنائية كبيرة الحجم في حاوية.

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

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

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

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

في حال فشل تحميل ملفات الإخراج إلى تخزين Azure، تنتقل المهمة إلى الحالة مكتمل ويتم تعيين الخاصية TaskExecutionInformation.FailureInformation. افحص خاصية 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 تقدم التحميل. يمكنك فحص هذا الملف لمعرفة المزيد حول المدة التي تستغرقها عمليات تحميل الملفات. ضع في اعتبارك أن هناك العديد من العوامل المساهمة في تحميل الأداء، بما في ذلك حجم العقدة، والنشاط الآخر على العقدة في وقت التحميل، وما إذا كانت الحاوية المستهدفة في منطقة مجموعة Batch نفسها أم لا، وكم عدد العقد التي تقوم بالتحميل إلى حساب التخزين في الوقت نفسه، وما إلى ذلك.

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

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

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

string containerName = job.OutputStorageContainerName();

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

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

Code sample

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

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

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