تكوين معلمات الإدخال لدفتر التشغيل في Automation

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

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

تعيين القيم لمعلمات الإدخال لدفتر التشغيل عند بدء تشغيله. يمكنك بدء تشغيل دفتر التشغيل من مدخل Microsoft Azure أو خدمة ويب أو PowerShell. يمكنك أيضًا بدء واحد كدفتر تشغيل صغير يسمى مضمّن في دفتر تشغيل آخر.

نوع الإدخال

يدعم Azure Automation قيم معلمات الإدخال المختلفة عبر أنواع دفتر التشغيل المختلفة. يتم سرد أنواع الإدخال المعتمدة لكل نوع من أنواع كتب التشغيل في الجدول التالي.

نوع دفتر التشغيل مدخلات المعلمات المدعومة
بوويرشيل -سلسله
- Security.SecureString
- INT32
-منطقيه
-Datetime
-الصفيف
- Collections.Hashtable
- Management.Automation.SwitchParameter
سير عمل PowerShell -سلسله
- Security.SecureString
- INT32
-منطقيه
-Datetime
-الصفيف
- Collections.Hashtable
- Management.Automation.SwitchParameter
PowerShell الرسومي -سلسله
- INT32
- INT64
-منطقيه
-العشريه
-Datetime
-الكائن
Python -سلسله

تكوين معلمات الإدخال في دفاتر التشغيل المتعلقة بـPowerShell

PowerShell وسير عمل دفتر تشغيل PowerShell في تنفيذ Azure التلقائي لدعم معلمات الإدخال التي يتم تعريفها من خلال الخصائص التالية.

الخاصية الوصف
النوع مطلوب. من المتوقع نوع البيانات لقيمة المعلمة. أي نوع Microsoft .NET صالح.
الاسم مطلوب. اسم المعلمة. يجب أن يكون هذا الاسم فريدًا ضمن دفتر التشغيل، ويجب أن يبدأ بحرف، ومن الممكن أن يحتوي على أحرف أو أرقام أو تسطير أسفل الأحرف فقط.
إلزامي اختياري. تحدد القيمة المنطقية ما إذا كانت المعلمة تتطلب قيمة. في حال قمت بتعيين هذا إلى True، فيجب توفير قيمة عند بدء تشغيل دفتر التشغيل. إذا قمت بتعيين هذا إلى خطأ، فإن القيمة تكون اختيارية. إذا لم تحدد قيمة للخاصيةMandatory، فإن PowerShell يعتبر معلمة الإدخال اختيارية بشكل افتراضي.
القيمة الافتراضية اختياري. قيمة تُستخدم للمعلمة إذا لم يتم تمرير قيمة إدخال عند بدء تشغيل دفتر التشغيل. من الممكن أن يعين دفتر التشغيل قيمة افتراضية لأي معلمة.

يدعم Windows PowerShell سمات معلمات الإدخال أكثر من تلك المذكورة أعلاه، مثل التحقق من الصحة والأسماء المستعارة ومجموعات المعلمات. ومع ذلك، يدعم Azure Automation حاليًا خصائص معلمة الإدخال التي تم سردها فقط.

على سبيل المثال، دعونا نلقي نظرة على تعريف المعلمة في دفتر التشغيل لسير عمل PowerShell. يحتوي هذا التعريف على النموذج العام الآتي، حيث يتم فصل المعلمات المتعددة بفواصل.

Param
(
  [Parameter (Mandatory= $true/$false)]
  [Type] $Name1 = <Default value>,

  [Parameter (Mandatory= $true/$false)]
  [Type] $Name2 = <Default value>
)

الآن دعونا نكوّن معلمات الإدخال لدفتر التشغيل المتعلق بسير عمل PowerShell الذي يُخرج تفاصيل حول الأجهزة الظاهرية، إما VM مفرد أو VMs جميعها داخل مجموعة الموارد. يحتوي هذا الكتاب على معلمتين، كما هو موضح في الصورة التالية: اسم الجهاز الظاهري (VMName) واسم مجموعة الموارد (resourceGroupName).

Automation PowerShell Workflow

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

لاحظ أن PowerShell ودليل تشغيل PowerShell Workflow لدعم كافة الأنواع البسيطة والأنواع المعقدة، مثلObjectأوPSCredentialلمعلمات الإدخال. إذا كان دفتر التشغيل الخاص بك يحتوي على معلمة إدخال كائن، فيجب عليك استخدام PowerShell hashtable مع أزواج اسم-قيمة لتمرير القيمة. على سبيل المثال، لديك المعلمة الآتية في دفتر تشغيل.

[Parameter (Mandatory = $true)]
[object] $FullName

في هذه الحالة، من الممكن تمرير القيمة التالية إلى المعلمة.

@{"FirstName"="Joe";"MiddleName"="Bob";"LastName"="Smith"}

بالنسبة لسجلات تشغيل PowerShell 7.1، قم بتوفير معلمات إدخال الصفيف بالتنسيق أدناه:

الاسم القيمة
TESTPARAMETER لا، وهذا، وحتى، والعمل

إشعار

عندما لا تقوم بتمرير قيمة إلى معلمة السلسلة الاختيارية ذات القيمة الافتراضية الخالية، فإن قيمة المعلمة هي سلسلة فارغة بدلاً من خال.

تكوين معلمات الإدخال في سجلات التشغيل الرسومية

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

يستخدم دفتر التشغيل الرسومي أنشطة دفتر التشغيل الرئيسية هذه:

  • المصادقة باستخدام Azure باستخدام الهوية المدارة المكونة لحساب التنفيذ التلقائي.
  • التعريف الخاص بـ Cmdletالحصول على AzVMللحصول على خصائص VM.
  • استخدام نشاطمدخلات الكتابةلإخراج أسماء VM.

Get-AzVMيُعرف النشاط إدخالين، اسم الجهاز الظاهري واسم مجموعة الموارد. نظرًا لأن هذه الأسماء من الممكن أن تكون مختلفة في كل مرة يبدأ فيها تشغيل دفتر التشغيل، فيجب إضافة معلمات الإدخال لدفتر التشغيل لقبول هذه الإدخالات. الإشارة إلى»التأليف الرسومي في Azure Automation».

قم باتباع هذه الخطوات لتكوين معلمات الإدخال.

  1. قم بتحديد دفتر التشغيل الرسومي من صفحة Runbooks ثم قم بالنقر فوق»تحرير».

  2. في المحرر الرسومي، قم بالنقر فوق الزر»إدخال وإخراج»ثم»إضافة إدخال»لفتح جزء معلمة إدخال Runbook.

    Automation graphical runbook

  3. يقوم عنصر التحكم Input وOutput بعرض قائمة معلمات الإدخال التي تم تعريفها لدفتر التشغيل. هنا يمكنك إما إضافة معلمة إدخال جديدة أو تحرير التكوين المتعلق بمعلمة الإدخال موجودة. لإضافة معلمة جديدة لدفتر التشغيل، قم بالنقر فوق»إضافة إدخال»لفتح شفرةمعلمة إدخال Runbook،حيث يمكنك تكوين المعلمات باستخدام خصائص المعرفة فيالتأليف الرسومي في Azure Automation.

    Add new input

  4. إنشاء اثنين من المعلمات مع الخصائص التالية لاستخدامها من قِبلGet-AzVMالنشاط، ومن ثم قم بالنقر فوق»موافق».

    • المعلمة 1:

      • الاسم -- اسم VM
      • النوع-- سلسلة
      • إلزامي -- لا
    • المعلمة 2:

      • Name -- resourceGroupName
      • النوع-- سلسلة
      • إلزامي -- لا
      • القيمة الافتراضية -- مخصص
      • اسم مجموعة موارد القيمة الافتراضية المخصصة التي تحتوي على VMs
  5. قم بعرض المعلمات في عنصر تحكم الإدخال والإخراج.

  6. قم بالنقر فوق»موافق»مرة أخرى، ثم انقر فوق»حفظ».

  7. انقر فوق»نشر» لنشر دفتر التشغيل.

قم بتكوين معلمات الإدخال في كتب تشغيل Python

على عكس PowerShell وPowerShell Workflow و دفتر التشغيل الرسومي، لا تأخذ دفاتر تشغيل Python معلمات مسماة. محرر دفتر التشغيل يوزع كافة معلمات الإدخال كصفيفة من قيم الوسيطة. من الممكن الوصول إلى الصفيف من خلال استيرادsysالوحدة النمطية للبرنامج النصي Python ثم قم باستخدامsys.argvالصفيف. من المهم ملاحظة أن العنصر الأول من الصفيف،sys.argv[0]هو اسم البرنامج النصي. ولذلك فإن أول معلمة إدخال فعلية هي sys.argv[1].

للحصول على مثال بشأن كيفية استخدام معلمات الإدخال في دفتر تشغيل Python، انظردفتر تشغيل Python الأولي في Azure Automation.

إشعار

الوسيطات ذات المسافات غير معتمدة حاليا. كحل بديل، يمكنك استخدام \\t بالإضافة إلى \\n.

قم بتعيين قيم لمعلمات الإدخال في دفاتر التشغيل

يقوم هذا القسم بوصف عدة طرق لتمرير القيم إلى معلمات الإدخال في دفاتر التشغيل. من الممكن تعيين قيم المعلمات عند:

بدء تشغيل دفتر التشغيل وتعيين المعلمات

من الممكن بدء تشغيل دفتر التشغيل بطرق عديدة: من خلال مدخل Microsoft Azure، أو باستخدام إخطار على الويب، أو مع Cmdlets PowerShell، أو مع واجهة برمجة تطبيقات REST، أو مع SDK.

قم ببدء تشغيل دفتر تشغيل المنشور باستخدام مدخل Microsoft Azure وتعيين المعلمات

عندبدء تشغيل دفتر التشغيلفي مدخل Microsoft Azure، افتح شفرةبدء تشغيل دفتر التشغيلويمكنك إدخال قيم المعلمات التي أنشأتها.

Start using the portal

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

إشعار

تدعم معلمات السلسلة القيم الفارغة من سلسلة النوع. الدخول في[EmptyString]مربع معلمة الإدخال لتمرير سلسلة فارغة إلى المعلمة. معلمات السلسلة لا تدعم خال أيضًا. في حال لم تقم بتمرير أي قيمة إلى معلمة سلسلة PowerShell يفسرها على أنها خال.

ابدأ تشغيل دفتر التشغيل المنشور باستخدام cmdlets PowerShell وتعيين المعلمات

  • cmdlets Azure Resource Manager:يمكنك بدء تشغيل Runbook التلقائي الذي تم إنشاؤه في مجموعة موارد باستخدام Start-AzAutomationRunbook.

       $params = @{"VMName"="WSVMClassic";"resourceGroupeName"="WSVMClassicSG"}
    
       Start-AzAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" –ResourceGroupName $resourceGroupName -Parameters $params
    
  • cmdlets Azure Resource Manager:يمكنك بدء تشغيل Runbook التلقائي الذي تم إنشاؤه في مجموعة موارد افتراضية باستخدامStart-AzAutomationRunbook.

       $params = @{"VMName"="WSVMClassic"; "ServiceName"="WSVMClassicSG"}
    
       Start-AzureAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" -Parameters $params
    

إشعار

عند بدء تشغيل دفتر التشغيل باستخدام cmdlets PowerShell، يتم إنشاء معلمةMicrosoftApplicationManagementStartedByافتراضية، بالقيمةPowerShell. يمكنك عرض هذه المعلمة في جزء تفاصيل الوظيفة.

ابدأ تشغيل دفتر التشغيل باستخدام SDK وتعيين المعلمات

  • Azure Resource Manager: من الممكن بدء تشغيل دفتر التشغيل باستخدام SDK للغة برمجة. فيما يلي مقتطف من التعليمات البرمجية C# لبدء تشغيل دفتر التشغيل في حساب Azure Automation الخاص بك. من الممكن عرض جميع التعليمات البرمجية فيمستودع GitHubلدينا.

    public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
    {
      var response = AutomationClient.Jobs.Create(resourceGroupName, automationAccount, new JobCreateParameters
      {
        Properties = new JobCreateProperties
        {
          Runbook = new RunbookAssociationProperty
          {
            Name = runbookName
          },
          Parameters = parameters
        }
      });
      return response.Job;
    }
    
  • أسلوب نموذج التوزيع الكلاسيكي Azure: يمكنك بدء تشغيل دفتر التشغيل باستخدام SDK للغة الكمبيوتر. فيما يلي مقتطف من التعليمات البرمجية C# لبدء تشغيل دفتر التشغيل في حساب Azure Automation الخاص بك. من الممكن عرض جميع التعليمات البرمجية فيمستودع GitHubلدينا.

    public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
    {
      var response = AutomationClient.Jobs.Create(automationAccount, new JobCreateParameters
      {
        Properties = new JobCreateProperties
        {
          Runbook = new RunbookAssociationProperty
          {
            Name = runbookName
          },
          Parameters = parameters
        }
      });
      return response.Job;
    }
    

    لبدء تشغيل هذا الأسلوب، قم بإنشاء قاموس لتخزين معلمات VMNameresourceGroupName دفتر التشغيل وقيمها. ثم قم ببدء تشغيل دفتر التشغيل. وفيما يلي مقتطف التعليمة البرمجية C# لاستدعاء الأسلوب الذي تم تعريفه أعلاه.

    IDictionary<string, string> RunbookParameters = new Dictionary<string, string>();
    
    // Add parameters to the dictionary.
    RunbookParameters.Add("VMName", "WSVMClassic");
    RunbookParameters.Add("resourceGroupName", "WSSC1");
    
    //Call the StartRunbook method with parameters
    StartRunbook("Get-AzureVMGraphical", RunbookParameters);
    

ابدأ تشغيل دفتر التشغيل باستخدام واجهة برمجة تطبيقات REST وتعيين المعلمات

يمكنك إنشاء وبدء تشغيل وظيفة دفتر التشغيل مع Azure Automation REST API باستخدام PUTالأسلوب مع URI الطلب التالي: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

في طلب URI، قم باستبدال المعلمات التالية:

  • subscriptionId: معرّف اشتراك Azure الخاص بك.
  • resourceGroupNameاسم مجموعة الموارد لحساب Azure Automation.
  • automationAccountNameاسم حساب Automation الذي يُضاف ضمن خدمة مجموعة النظراء المحددة.
  • jobName: المعرف الفريد للوظيفة. يمكن إنشاء المعرفات الفريدة (GUIDs) في PowerShell باستخدام[GUID]::NewGuid().ToString()*.

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

  • الاسم الخاص بدفتر التشغيل: مطلوب. اسم دفتر التشغيل لبدء الوظيفة.
  • المعلمات المتعلقة بدفتر التشغيل: اختياري. قاموس قائمة المعلمات بتنسيق (الاسم، القيمة)، حيث يمكن أن يكون الاسم من النوع String والقيمة ممكن أن تكون أي قيمة JSON صالحة.

في حالة الرغبة في بدء تشغيل دفتر التشغيلGet-AzureVMTextual الذي تم إنشاؤه مسبقًا معVMNameوresourceGroupNameالمعلمات، استخدم تنسيق JSON التالي لنص الطلب.

    {
      "properties":{
        "runbook":{
        "name":"Get-AzureVMTextual"},
      "parameters":{
         "VMName":"WindowsVM",
         "resourceGroupName":"ContosoSales"}
        }
    }

يتم إرجاع التعليمة البرمجية لحالة HTTP 201 إذا تم إنشاء الوظيفة بنجاح. لمزيد من المعلومات حول عناوين الاستجابة ونص الاستجابة، انظرإنشاء مهمة كتاب التشغيل باستخدام REST API.

اختبار دفتر التشغيل وتعيين المعلمات

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

Test and assign parameters

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

Schedule and assign parameters

إنشاء webhook لدفتر التشغيل والتعيين للمعلمات

من الممكن إنشاءwebhookلدفتر التشغيل وتكوين معلمات إدخال دفتر التشغيل. لا يمكنك حفظ webhook حتى يتم توفير جميع قيم المعلمات الإلزامية.

Create webhook and assign parameters

عند تنفيذ runbook باستخدام webhook تُرسل معلمة الإدخال المعرفة مسبقًا[WebhookData](automation-webhooks.md)مع معلمات الإدخال التي تقوم بتعريفها.

WebhookData parameter

تمرير عنصر JSON إلى دفتر التشغيل

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

يستخدم هذا المقطع مثال حيث يقوم البرنامج النصي PowerShell باستدعاءStart-AzAutomationRunbookلبدء تشغيل PowerShell، وتمرير محتويات ملف JSON إلى دفتر التشغيل. يبدأ دفتر التشغيل PowerShell VM Azure من خلال استرداد المعلمات الخاصة بـVM من كائن JSON.

قم بإنشاء ملف JSON

قم بكتابة التعليمات البرمجية التالية في ملف نصي، واحفظها كماtest.js فيمكان ما على الكمبيوتر المحلي.

{
   "VmName" : "TestVM",
   "ResourceGroup" : "AzureAutomationTest"
}

قم بإنشاء دفتر التشغيل

إنشاء دفتر التشغيل PowerShell الجديد يُدعىاختبار-Json في تنفيذ Azure التلقائي.

ليتم قبول بيانات JSON يجب أن يأخذ دفتر التشغيل عنصر كمعلمة إدخال. يمكن لدفتر التشغيل بعد ذلك استخدام الخصائص المعرّفة في ملف JSON.

Param(
     [parameter(Mandatory=$true)]
     [object]$json
)

# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

# Convert object to actual JSON
$json = $json | ConvertFrom-Json

# Use the values from the JSON object as the parameters for your command
Start-AzVM -Name $json.VMName -ResourceGroupName $json.ResourceGroup -DefaultProfile $AzureContext

إذا كنت تريد تشغيل دفتر التشغيل للتنفيذ مع هوية مدارة معينة من قِبل النظام، اترك التعليمات البرمجية كما هي. إذا كنت تفضل استخدام الهوية المدارة المعينة من قِبل المستخدم، بعد ذلك:

  1. من الخط 10، قم بحذف$AzureContext = (Connect-AzAccount -Identity).context،
  2. استبدله بـ $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context، و
  3. أدرج معرّف العميل.

حفظ ونشر دفتر التشغيل هذا في حساب Azure Automation الخاص بك.

قم باستدعاء دفتر التشغيل من PowerShell

حاليًا يمكنك استدعاء دفتر التشغيل من الجهاز المحلي باستخدام Azure PowerShell.

  1. سجّل الدخول إلى Azure كما هو موضح. بعد ذلك، سيتم مطالبتك بإدخال بيانات اعتماد Azure.

    Connect-AzAccount
    

    إشعار

    لدفاتر تشغيل PowerShell، يعد Add-AzAccount و Add-AzureRMAccount اسمين مستعارين لـ Connect-AzAccount. لاحظ أن الأسماء المستعارة هذه غير متوفرة لكتب التشغيل الرسومية. يمكن لدفتر التشغيل الرسومي استخدامConnect-AzAccountنفسه فقط.

  2. الحصول على محتويات المحفوظة لملف JSON وتحويلها إلى سلسلة. JsonPathيشير إلى المسار حيث قمت بحفظ ملف JSON فيه.

    $json =  (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
    
  3. قم بتحويل محتويات السلسلة$jsonإلى عنصر PowerShell.

    $JsonParams = @{"json"=$json}
    
  4. قم بإنشاء hashtable للمعلمات الخاصةStart-AzAutomationRunbookلـ.

    $RBParams = @{
         AutomationAccountName = 'AATest'
         ResourceGroupName = 'RGTest'
         Name = 'Test-Json'
         Parameters = $JsonParams
    }
    

    لاحظ أنك تقوم بإعداد قيمةParametersإلى العنصر PowerShell الذي يحتوي على القيم من ملف JSON.

  5. ابدأ تشغيل دفتر التشغيل.

    $job = Start-AzAutomationRunbook @RBParams
    

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