إضافة وتشغيل التعليمات البرمجية للبرنامج النصي PowerShell في مهام سير العمل القياسية ل Azure Logic Apps (معاينة)

ينطبق على: Azure Logic Apps (قياسي)

لتنفيذ مهام تكامل مخصصة مضمنة مع سير العمل القياسي في Azure Logic Apps، يمكنك إضافة التعليمات البرمجية PowerShell وتشغيلها مباشرة من داخل سير العمل الخاص بك. لهذه المهمة، استخدم إجراء التعليمات البرمجية المضمنة المسمى Execute PowerShell Code. يقوم هذا الإجراء بإرجاع النتائج من التعليمات البرمجية PowerShell بحيث يمكنك استخدام هذا الإخراج في الإجراءات اللاحقة لسير العمل.

توفر هذه الإمكانية المزايا التالية:

• اكتب البرامج النصية الخاصة بك داخل مصمم سير العمل حتى تتمكن من حل تحديات التكامل المعقدة. لا توجد خطط خدمة أخرى ضرورية.

  تعمل هذه الميزة على تبسيط تطوير سير العمل بالإضافة إلى تقليل التعقيد والتكلفة مع إدارة المزيد من الخدمات.

• إنشاء ملف تعليمة برمجية مخصص، والذي يوفر مساحة برمجة نصية مخصصة داخل سير العمل الخاص بك.

• التكامل مع وظائف Azure Functions PowerShell Functions، والتي توفر وظائف قوية وتوريثا لتنفيذ المهام المتقدمة.

• نشر البرامج النصية جنبا إلى جنب مع مهام سير العمل الخاصة بك.

يوضح هذا الدليل كيفية إضافة الإجراء في سير العمل وإضافة التعليمات البرمجية PowerShell التي تريد تشغيلها.

المتطلبات الأساسية

• حساب واشتراك Azure. إذا لم يكن لديك اشتراك، فيجب التسجيل للحصول على حساب Azure مجاني.

• سير عمل تطبيق المنطق القياسي حيث تريد إضافة برنامج PowerShell النصي الخاص بك. يجب أن يبدأ سير العمل بالفعل بمشغل. لمزيد من المعلومات، راجع إنشاء مثال لسير عمل تطبيق المنطق القياسي.

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

الاعتبارات

• يحفظ مدخل Microsoft Azure البرنامج النصي الخاص بك كملف برنامج نصي PowerShell (.ps1) في نفس المجلد كملف workflow.json ، والذي يخزن تعريف JSON لسير العمل الخاص بك، وينشر الملف إلى مورد تطبيق المنطق الخاص بك جنبا إلى جنب مع تعريف سير العمل.

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

• البرنامج النصي محلي لسير العمل. لاستخدام نفس البرنامج النصي في مهام سير العمل الأخرى، اعرض ملف البرنامج النصي في وحدة تحكم KuduPlus، ثم انسخ البرنامج النصي لإعادة استخدامه في مهام سير العمل الأخرى.

القيود

إضافة إجراء Execute PowerShell Code

1. في مدخل Microsoft Azure، افتح مورد تطبيق المنطق القياسي وسير العمل في المصمم.

2. في المصمم، اتبع هذه الخطوات العامة لإضافة إجراء عمليات التعليمات البرمجية المضمنة المسمى Execute PowerShell Code إلى سير العمل الخاص بك.

3. بعد فتح جزء معلومات الإجراء، في علامة التبويب Parameters ، في المربع Code File ، قم بتحديث نموذج التعليمات البرمجية التي تم ملءها مسبقا بالتعليمات البرمجية الخاصة بك.

   • للوصول إلى البيانات الواردة من سير العمل، راجع تشغيل سير عمل Access ومخرجات الإجراء في البرنامج النصي لاحقا في هذا الدليل.

   • لإرجاع نتائج البرنامج النصي أو البيانات الأخرى إلى سير العمل، راجع إرجاع البيانات إلى سير العمل.

   يوضح المثال التالي علامة التبويب Parameters للإجراء مع نموذج التعليمات البرمجية للبرنامج النصي:

   

   يوضح المثال التالي نموذج التعليمات البرمجية للبرنامج النصي:

   # Use the following cmdlets to retrieve outputs from prior steps.
   # $triggerOutput = Get-TriggerOutput
   # $ActionOutput = Get-ActionOutput -ActionName <action-name>
   
   $customResponse =  [PSCustomObject]@{
      Message = "Hello world!"
   }
   
   # Use Write-Debug/Write-Host/Write-Output/ to log messages to Application Insights.
   # Write-Host/Write-Output/Write-Debug and 'return' won't return an output to the workflow.
   # Write-Host "Sending to Application Insight logs"
   
   # Use Push-WorkflowOutput to push outputs into subsequent actions.
   Push-WorkflowOutput -Output $customResponse
   

   يوضح المثال التالي نموذج برنامج نصي مخصص:

   $action = Get-TriggerOutput
   $results = "Hello from PowerShell!"
   Push-WorkflowOutput -Output $results
   

4. عند الانتهاء، احفظ سير العمل.

بعد تشغيل سير العمل الخاص بك، يمكنك مراجعة إخراج سير العمل في Application Insights، إذا تم تمكينه. لمزيد من المعلومات، راجع عرض الإخراج في Application Insights.

تشغيل سير عمل الوصول ومخرجات الإجراء في البرنامج النصي الخاص بك

يتم إرجاع قيم الإخراج من المشغل والإجراءات السابقة باستخدام كائن مخصص، والذي يحتوي على معلمات متعددة. للوصول إلى هذه المخرجات والتأكد من إرجاع القيمة التي تريدها، استخدم أوامر cmdlets Get-TriggerOutput و Get-ActionOutput و Push-WorkflowOutput بالإضافة إلى أي معلمات مناسبة موضحة في الجدول التالي، على سبيل المثال:

$trigger = Get-TriggerOutput
$statusCode = $trigger.status.ToString();
$action = Get-ActionOutput -ActionName Compose
$actionOutput = $action.outputs['actionOutput'].ToString();
$populatedString = "Send the $statusCode for the trigger status and $actionOutputName."

Push-WorkflowOutput -Output $populatedString

مخرجات استجابة المشغل والإجراءات

يسرد الجدول التالي المخرجات التي يتم إنشاؤها عند استدعاء Get-ActionOutput أو Get-TriggerOutput. القيمة المرجعة هي كائن معقد يسمى PowershellWorkflowOperationResult، والذي يحتوي على المخرجات التالية.

إرجاع المخرجات إلى سير العمل

لإرجاع أي مخرجات إلى سير العمل الخاص بك، يجب استخدام الأمر cmdlet Push-WorkflowOutput.

أوامر PowerShell المخصصة

يتضمن إجراء Execute PowerShell Code اتباع أوامر PowerShell المخصصة (cmdlets) للتفاعل مع سير العمل والعمليات الأخرى في سير العمل الخاص بك:

Get-TriggerOutput

يحصل على الإخراج من مشغل سير العمل.

بناء الجملة

Get-TriggerOutput

المعلمات

لا شيء.

Get-ActionOutput

الحصول على الإخراج من إجراء آخر في سير العمل وإرجاع كائن يسمى PowershellWorkflowOperationResult.

بناء الجملة

Get-ActionOutput [ -ActionName <String> ]

المعلمات

دفع سير العملOutput

يدفع الإخراج من إجراء Execute PowerShell Code إلى سير العمل الخاص بك، والذي يمكن أن يمرر أي نوع كائن مرة أخرى. إذا كانت القيمة المرجعة فارغة، فستحصل على خطأ كائن فارغ من cmdlet.

بناء الجملة

Push-WorkflowOutput [-Output <Object>] [-Clobber]

المعلمات

مصادقة الوصول وتخويله بهوية مدارة باستخدام PowerShell

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

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

لاستخدام الهوية المدارة من داخل إجراء Execute PowerShell Code ، يجب اتباع الخطوات التالية:

1. اتبع هذه الخطوات لإعداد الهوية المدارة على تطبيق المنطق الخاص بك ومنح الوصول إلى الهوية المدارة على مورد Azure الهدف.

   في مورد Azure الهدف، راجع الاعتبارات التالية:

   • في علامة التبويب الدور ، عادة ما يكون دور المساهم كافيا.

   • في صفحة إضافة تعيين دور، في علامة التبويب الأعضاء ، للخاصية تعيين الوصول إلى ، تأكد من تحديد الهوية المدارة.

   • بعد تحديد Select members، في جزء Select managed identities ، حدد الهوية المدارة التي تريد استخدامها.

2. في إجراء Execute PowerShell Code، قم بتضمين التعليمات البرمجية التالية كبيان أول:

   Connect-AzAccount -Identity
   

3. الآن، يمكنك العمل مع مورد Azure باستخدام cmdlets والوحدات النمطية.

عرض ملف البرنامج النصي

1. في مدخل Microsoft Azure، افتح مورد تطبيق المنطق القياسي الذي يحتوي على سير العمل الذي تريده.

2. في قائمة logic app resource، ضمن Development Tools، حدد Advanced Tools.

3. في صفحة Advanced Tools ، حدد Go، الذي يفتح وحدة تحكم KuduPlus .

4. افتح قائمة وحدة تحكم تتبع الأخطاء، وحدد CMD.

5. انتقل إلى الموقع الجذر لتطبيق المنطق الخاص بك: الموقع/wwwroot

6. انتقل إلى مجلد سير العمل، الذي يحتوي على ملف .ps1، على طول هذا المسار: site/wwwroot/{workflow-name}

7. إلى جانب اسم الملف، حدد تحرير لفتح الملف وعرضه.

عرض السجلات في Application Insights

1. في مدخل Microsoft Azure، في قائمة مورد تطبيق المنطق، ضمن الإعدادات، حدد Application Insights، ثم حدد تطبيق المنطق الخاص بك.

2. في قائمة Application Insights ، ضمن Monitoring، حدد Logs.

3. إنشاء استعلام للعثور على أي تتبعات أو أخطاء من تنفيذ سير العمل، على سبيل المثال:

   union traces, errors
   | project TIMESTAMP, message
   

الوحدات النمطية

وحدات PowerShell النمطية هي وحدات مكتفية ذاتيا وقابلة لإعادة الاستخدام تتضمن مكونات مختلفة، على سبيل المثال:

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

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

الوحدات النمطية العامة

للعثور على الوحدات النمطية المتاحة للجمهور، قم بزيارة معرض PowerShell. يمكن أن يدعم مورد تطبيق المنطق القياسي ما يصل إلى 10 وحدات نمطية عامة. لاستخدام أي وحدة نمطية عامة، يجب تمكين هذه الإمكانية باتباع الخطوات التالية:

1. في مدخل Microsoft Azure، في قوائم موارد تطبيق المنطق، ضمن أدوات التطوير، حدد أدوات متقدمة.

2. في صفحة Advanced Tools ، حدد Go.

3. في شريط أدوات Kudu Plus ، من قائمة وحدة تحكم تتبع الأخطاء، حدد CMD.

4. استعرض للوصول إلى مستوى جذر تطبيق المنطق في C:\home\site\wwwroot باستخدام بنية الدليل أو سطر الأوامر.

5. افتح ملف host.json لسير العمل، ثم قم بتعيين خاصية التبعية المدارة إلى true، والتي تم تعيينها بالفعل بشكل افتراضي.

   "managedDependency": {
       "enabled": true
   }
   

6. افتح الملف المسمى requirements.psd1. قم بتضمين الاسم والإصدار للوحدة النمطية التي تريدها باستخدام بناء الجملة التالي: MajorNumber.* أو إصدار الوحدة النمطية الدقيق، على سبيل المثال:

   @{
       Az = '1.*'
       SqlServer = '21.1.18147'
   } 
   

اعتبارات الوحدات النمطية العامة

إذا كنت تستخدم إدارة التبعية، تنطبق الاعتبارات التالية:

• لتنزيل الوحدات النمطية، تتطلب الوحدات العامة الوصول إلى معرض PowerShell.

• لا تدعم التبعيات المدارة حاليا الوحدات النمطية التي تتطلب منك قبول ترخيص، إما عن طريق قبول الترخيص بشكل تفاعلي أو عن طريق توفير الخيار -AcceptLicense عند تشغيل Install-Module.

وحدات خاصة

يمكنك إنشاء وحدات PowerShell الخاصة بك. لإنشاء وحدة PowerShell النمطية الأولى، راجع كتابة وحدة نمطية لبرنامج PowerShell النصي.

1. في مدخل Microsoft Azure، في قائمة موارد تطبيق المنطق، ضمن أدوات التطوير، حدد أدوات متقدمة.

2. في صفحة Advanced Tools ، حدد Go.

3. في شريط أدوات Kudu Plus ، من قائمة وحدة تحكم تتبع الأخطاء، حدد CMD.

4. استعرض للوصول إلى مستوى جذر تطبيق المنطق في C:\home\site\wwwroot باستخدام بنية الدليل أو سطر الأوامر.

5. إنشاء مجلد يسمى Modules.

6. في مجلد Modules، أنشئ مجلدا فرعيا بنفس اسم الوحدة النمطية الخاصة بك.

7. في مجلد الوحدة النمطية الخاصة بك، أضف ملف الوحدة النمطية PowerShell الخاص بك مع ملحق اسم ملف psm1 . يمكنك أيضا تضمين ملف بيان PowerShell اختياري مع ملحق اسم ملف psd1 .

عند الانتهاء، تظهر بنية ملف تطبيق المنطق الكامل مشابهة للمثال التالي:

MyLogicApp
-- execute_powershell_script.ps1
-- mytestworkflow.json
Modules
-- MyPrivateModule
--- MyPrivateModule.psd1
--- MyPrivateModule.psm1
-- MyPrivateModule2
--- MyPrivateModule2.psd1
--- MyPrivateModule2.psm1
requirements.psd1
host.json

أخطاء التحويل البرمجي

في هذا الإصدار، يتضمن المحرر المستند إلى الويب دعما محدودا ل IntelliSense، والذي لا يزال قيد التحسين. يتم الكشف عن أي أخطاء تحويل برمجي عند حفظ سير العمل الخاص بك، ويحول وقت تشغيل Azure Logic Apps برنامجك النصي برمجيا. تظهر هذه الأخطاء في سجلات أخطاء تطبيق المنطق الخاص بك من خلال Application Insights.

أخطاء وقت التشغيل

لا يرجع إجراء سير العمل أي إخراج.

تأكد من استخدام الأمر cmdlet Push-WorkflowOutput .

فشل إجراء تنفيذ رمز PowerShell: "لم يتم التعرف على المصطلح '{some-text}'..."

إذا قمت بالإشارة بشكل غير صحيح إلى وحدة نمطية عامة في ملف requirements.psd1 أو عندما لا تكون الوحدة الخاصة موجودة في المسار التالي: C:\home\site\wwwroot\Modules{module-name}، فستحصل على الخطأ التالي:

لم يتم التعرف على المصطلح '{some-text}' كاسم cmdlet أو دالة أو ملف برنامج نصي أو برنامج قابل للتنفيذ. تحقق من التدقيق الإملائي للاسم أو إذا تم تضمين مسار، فتحقق من صحة المسار وحاول مرة أخرى.

فشل إجراء تنفيذ PowerShell Code: "لا يمكن ربط الوسيطة إلى المعلمة "الإخراج" لأنها فارغة."

يحدث هذا الخطأ عند محاولة دفع كائن فارغ إلى سير العمل. تأكد من أن الكائن الذي ترسله باستخدام Push-WorkflowOutput ليس خاليا.

المحتوى ذو الصلة

• إضافة أجزاء التعليمات البرمجية ل JavaScript وتشغيلها
• إضافة البرامج النصية C# وتشغيلها