تكوين معلمات الإدخال لدفتر التشغيل في 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
).
في تعريف المعلمة هذا، تكون معلمات الإدخال معلمات بسيطة من نوع السلسلة.
لاحظ أن 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».
قم باتباع هذه الخطوات لتكوين معلمات الإدخال.
قم بتحديد دفتر التشغيل الرسومي من صفحة Runbooks ثم قم بالنقر فوق»تحرير».
في المحرر الرسومي، قم بالنقر فوق الزر»إدخال وإخراج»ثم»إضافة إدخال»لفتح جزء معلمة إدخال Runbook.
يقوم عنصر التحكم Input وOutput بعرض قائمة معلمات الإدخال التي تم تعريفها لدفتر التشغيل. هنا يمكنك إما إضافة معلمة إدخال جديدة أو تحرير التكوين المتعلق بمعلمة الإدخال موجودة. لإضافة معلمة جديدة لدفتر التشغيل، قم بالنقر فوق»إضافة إدخال»لفتح شفرةمعلمة إدخال Runbook،حيث يمكنك تكوين المعلمات باستخدام خصائص المعرفة فيالتأليف الرسومي في Azure Automation.
إنشاء اثنين من المعلمات مع الخصائص التالية لاستخدامها من قِبل
Get-AzVM
النشاط، ومن ثم قم بالنقر فوق»موافق».المعلمة 1:
- الاسم -- اسم VM
- النوع-- سلسلة
- إلزامي -- لا
المعلمة 2:
- Name -- resourceGroupName
- النوع-- سلسلة
- إلزامي -- لا
- القيمة الافتراضية -- مخصص
- اسم مجموعة موارد القيمة الافتراضية المخصصة التي تحتوي على VMs
قم بعرض المعلمات في عنصر تحكم الإدخال والإخراج.
قم بالنقر فوق»موافق»مرة أخرى، ثم انقر فوق»حفظ».
انقر فوق»نشر» لنشر دفتر التشغيل.
قم بتكوين معلمات الإدخال في كتب تشغيل 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، افتح شفرةبدء تشغيل دفتر التشغيلويمكنك إدخال قيم المعلمات التي أنشأتها.
في التسمية الموجودة أسفل مربع الإدخال، يمكنك رؤية الخصائص التي تم تعيينها لتحديد سمات المعلمات، على سبيل المثال، إلزامي أو اختياري، النوع، القيمة الافتراضية. يحدد بالون المساعدة الموجود بجوار اسم المعلمة أيضًا المعلومات الأساسية اللازمة لاتخاذ قرارات حول قيم إدخال المعلمة.
إشعار
تدعم معلمات السلسلة القيم الفارغة من سلسلة النوع. الدخول في[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; }
لبدء تشغيل هذا الأسلوب، قم بإنشاء قاموس لتخزين معلمات
VMName
resourceGroupName
دفتر التشغيل وقيمها. ثم قم ببدء تشغيل دفتر التشغيل. وفيما يلي مقتطف التعليمة البرمجية 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.
اختبار دفتر التشغيل وتعيين المعلمات
عنداختبار إصدار مسودة دفتر التشغيلباستخدام خيار الاختبار، تفتح صفحة الاختبار. قم باستخدام هذه الصفحة لتكوين قيم المعلمات التي قمت بإنشائها.
ربط جدول بسجل التشغيل وتعيين المعلمات
من الممكنربط جدول بدفتر التشغيل الخاص بك بحيث يبدأ تشغيل دفتر التشغيل في وقت محدد. تعيين معلمات الإدخال عند إنشاء الجدول، ويقوم دفتر التشغيل باستخدام هذه القيم عند بدء تشغيله بواسطة الجدول. ليس من الممكن حفظ الجدول حتى يتم توفير كافة قيم المعلمات الإلزامية.
إنشاء webhook لدفتر التشغيل والتعيين للمعلمات
من الممكن إنشاءwebhookلدفتر التشغيل وتكوين معلمات إدخال دفتر التشغيل. لا يمكنك حفظ webhook حتى يتم توفير جميع قيم المعلمات الإلزامية.
عند تنفيذ runbook باستخدام webhook تُرسل معلمة الإدخال المعرفة مسبقًا[WebhookData](automation-webhooks.md)
مع معلمات الإدخال التي تقوم بتعريفها.
تمرير عنصر 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
إذا كنت تريد تشغيل دفتر التشغيل للتنفيذ مع هوية مدارة معينة من قِبل النظام، اترك التعليمات البرمجية كما هي. إذا كنت تفضل استخدام الهوية المدارة المعينة من قِبل المستخدم، بعد ذلك:
- من الخط 10، قم بحذف
$AzureContext = (Connect-AzAccount -Identity).context
، - استبدله بـ
$AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context
، و - أدرج معرّف العميل.
حفظ ونشر دفتر التشغيل هذا في حساب Azure Automation الخاص بك.
قم باستدعاء دفتر التشغيل من PowerShell
حاليًا يمكنك استدعاء دفتر التشغيل من الجهاز المحلي باستخدام Azure PowerShell.
سجّل الدخول إلى Azure كما هو موضح. بعد ذلك، سيتم مطالبتك بإدخال بيانات اعتماد Azure.
Connect-AzAccount
إشعار
لدفاتر تشغيل PowerShell، يعد
Add-AzAccount
وAdd-AzureRMAccount
اسمين مستعارين لـConnect-AzAccount
. لاحظ أن الأسماء المستعارة هذه غير متوفرة لكتب التشغيل الرسومية. يمكن لدفتر التشغيل الرسومي استخدامConnect-AzAccount
نفسه فقط.الحصول على محتويات المحفوظة لملف JSON وتحويلها إلى سلسلة.
JsonPath
يشير إلى المسار حيث قمت بحفظ ملف JSON فيه.$json = (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
قم بتحويل محتويات السلسلة
$json
إلى عنصر PowerShell.$JsonParams = @{"json"=$json}
قم بإنشاء hashtable للمعلمات الخاصة
Start-AzAutomationRunbook
لـ.$RBParams = @{ AutomationAccountName = 'AATest' ResourceGroupName = 'RGTest' Name = 'Test-Json' Parameters = $JsonParams }
لاحظ أنك تقوم بإعداد قيمة
Parameters
إلى العنصر PowerShell الذي يحتوي على القيم من ملف JSON.ابدأ تشغيل دفتر التشغيل.
$job = Start-AzAutomationRunbook @RBParams
الخطوات التالية
- لإعداد دليل تشغيل PowerShell، انظرتحرير دفاتر التشغيل النصية في Azure Automation.
- لإعداد دفتر تشغيل رسومي، انظركتب التشغيل الرسومية للمؤلف في Azure Automation.
الملاحظات
https://aka.ms/ContentUserFeedback.
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجعإرسال الملاحظات وعرضها المتعلقة بـ