إضافة وتشغيل سكريبتات PowerShell باستخدام سير العمل القياسي في Azure Logic Apps

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

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

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

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

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

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

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

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

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

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

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

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

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

  إذا لم يكن لديك مورد تطبيق منطقي وسير عمل، فبادر بإنشائه الآن باتباع الخطوات التالية:

  • إنشاء سير عمل تطبيق منطقي قياسي

الاعتبارات

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

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

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

القيود

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

تحديث إصدار PowerShell

يمكنك تغيير إصدار PowerShell في مورد تطبيق المنطق الخاص بك عن طريق تحرير إعدادات التطبيق. ومع ذلك، قبل ترقية تطبيقك، راجع الاعتبارات التالية:

• قد يؤدي تحديث الإصدار إلى تغييرات معطلة في تطبيق المنطق القياسي الخاص بك، الذي يستخدم وقت تشغيل مستضاف كامتداد لوقت تشغيل Azure Functions. قبل الترقية، راجع دليل الترحيل التالي: ترقية تطبيقات Azure Functions لتشغيلها على PowerShell 7.4.

• تأكد من أن تطبيق المنطق الخاص بك يستخدم أحدث إصدار من وقت التشغيل لوقت تشغيل Azure Functions في Azure، وهو الإصدار 4.x. لمزيد من المعلومات، راجع عرض إصدار وقت التشغيل الحالي.

إشعار

بشكل افتراضي، إذا لم تحدد إصدار PowerShell، فإن Azure Logic Apps تستخدم نفس الإصدار الافتراضي مثل Azure Functions. حاليا ، يتوفر PowerShell 7.4 بشكل عام. لمزيد من المعلومات حول الإصدارات المتوفرة، راجع دليل مطور Azure Functions PowerShell.

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

Portal

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

2. في الشريط الجانبي للمورد، ضمن الإعدادات، حدد متغيرات البيئة.

3. في علامة التبويب إعدادات التطبيق ، حدد + إضافة.

4. في جزء إعداد إضافة/تحرير التطبيق ، أضف إعداد التطبيق الجديد التالي:

   المعلمة	Value	‏‏الوصف
   الاسم	LOGIC_APPS_POWERSHELL_VERSION	اسم إعداد التطبيق.
   القيمة	< إصدار PowerShell>	إصدار PowerShell ، حاليا 7.4.

5. عند الانتهاء، حدد تطبيق. عند ظهور تحذير إعادة التشغيل، حدد متابعة.

   تتم إعادة تشغيل تطبيق المنطق الخاص بك بالإصدار المحدث.

1. في Visual Studio Code، افتح مساحة العمل لمشروع تطبيق المنطق الخاص بك.

2. في مشروع تطبيق المنطق الخاص بك، من المجلد الجذر، افتح ملف local.settings.json .

3. في ملف local.settings.json ، أضف إعداد LOGIC_APPS_POWERSHELL_VERSION وقيمته، على سبيل المثال:

   {
       "IsEncrypted": false,
       "Values": {
           "AzureWebJobsStorage": "<*storage-account*>",
           <...>
           "LOGIC_APPS_POWERSHELL_VERSION": "<powershell-version>" // For example, "7.4"
       }
   }
   

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

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

2. في الشريط الجانبي للموارد، تحت سير العمل، اختر سير العمل، ثم اختر سير العمل الفارغ.

3. في الشريط الجانبي لسير العمل، ضمن أدوات، حدد المصمم لفتح سير العمل.

4. أضف إجراء عمليات التعليمات البرمجية المضمنة المسمى Execute PowerShell Code إلى سير العمل باتباع الخطوات العامة لإضافة إجراء.

5. بعد فتح جزء معلومات الإجراء، في علامة التبويب 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
   

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

بعد تشغيل سير العمل الخاص بك، يمكنك مراجعة إخراج سير العمل في 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

إشعار

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

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

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

الاسم	كتابة	‏‏الوصف
الاسم	السلسلة‬	اسم المشغل أو الإجراء
المدخلات	JToken	قيم الإدخال التي تم تمريرها إلى المشغل أو الإجراء
النواتج	JToken	المخرجات من المشغل أو الإجراء المنفذ
وقت البدء	التاريخ والوقت	وقت البدء للمشغل أو الإجراء
وقت الانتهاء	التاريخ والوقت	وقت انتهاء المشغل أو الإجراء
الوقت المجدول	التاريخ والوقت	الوقت المجدول لتشغيل المشغل أو الإجراء أو المشغل
OriginHistoryName	السلسلة‬	اسم محفوظات الأصل للمشغلات التي تستخدم الخاصية splitOn
SourceHistoryName	السلسلة‬	اسم محفوظات المصدر لمشغل تم إعادة إرساله
معرف التتبع	السلسلة‬	معرف تعقب العملية
الرمز	السلسلة‬	رمز الحالة للنتيجة
الحالة	السلسلة‬	حالة التشغيل للمشغل أو الإجراء، على سبيل المثال، "Succeeded" أو "Failed"
خطأ	JToken	رمز خطأ HTTP
الخصائص المتعقبة	JToken	أي خصائص متعقبة قمت بإعدادها

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

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

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

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

Get-TriggerOutput

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

بناء الجملة

Get-TriggerOutput

المعلمات

لا شيء.

Get-ActionOutput

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

بناء الجملة

Get-ActionOutput [ -ActionName <String> ]

المعلمات

المعلمة	كتابة	‏‏الوصف
اسم الإجراء	السلسلة‬	اسم الإجراء في سير العمل مع الإخراج الذي تريد الرجوع إليه.

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

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

إشعار

Write-Debug Write-Hostلا ترجع أوامر cmdlets و و Write-Output القيم إلى سير العمل الخاص بك. لا ترجع العبارة return أيضا القيم إلى سير العمل. ومع ذلك، يمكنك استخدام أوامر cmdlets هذه لكتابة رسائل التتبع التي تظهر في Application Insights. لمزيد من المعلومات، راجع Microsoft.PowerShell.Utility.

بناء الجملة

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

المعلمات

المعلمة	كتابة	‏‏الوصف
الناتج	يتفاوت	الإخراج الذي تريد إرجاعه إلى سير العمل. يمكن أن يكون لهذا الإخراج أي نوع.
Clobber	يتفاوت	معلمة تبديل اختيارية يمكنك استخدامها لتجاوز الإخراج الذي تم دفعه مسبقا.

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

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

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

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

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

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

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

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

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

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

   Connect-AzAccount -Identity
   

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

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

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

2. في شريط الموارد، تحت أدوات التطوير، اختر الأدوات المتقدمة.

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

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

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

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

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

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

1. في بوابة Azure، في الشريط الجانبي لتطبيق المنطق، تحت قسم المراقبة، اختر Application Insights (وليس Insights).

2. اختر الرابط الخاص بمورد Application Insights الخاص بك.

3. في شريط موارد Application Insights الجانبي، تحت قسم المراقبة، اختر السجلات.

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

   union traces, errors
   | project TIMESTAMP, message
   

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

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

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

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

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

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

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

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

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

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

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

   "managedDependency": {
       "enabled": true
   }
   

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

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

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

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

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

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

وحدات خاصة

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

1. في بوابة Azure، في أشرطة موارد تطبيقات المنطق الخاصة بك، تحت أدوات التطوير، اختر الأدوات المتقدمة.

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

3. في شريط أدوات Kudu ، من قائمة وحدة تحكم تتبع الأخطاء، حدد 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.

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

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

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

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

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

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

إشعار

بشكل افتراضي، تظهر وحدات Az* النمطية في ملف requirements.psd1 ، ولكن يتم التعليق عليها عند إنشاء الملف. عند الرجوع إلى cmdlet من الوحدة النمطية، تأكد من إلغاء التعليق على الوحدة النمطية.

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

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

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

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