مشاركة عبر

استخدام البرامج النصية للتوزيع في قوالب ARM

  • مقالة

تعرف على كيفية استخدام البرامج النصية للتوزيع في قوالب Azure Resource Manager (ARM). deploymentScripts باستخدام المورد، يمكن للمستخدمين تنفيذ البرامج النصية في عمليات توزيع ARM ومراجعة نتائج التنفيذ.

تلميح

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

يمكن استخدام هذه البرامج النصية لتنفيذ الخطوات المخصصة مثل:

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

ميزات البرنامج النصي للتوزيع:

  • سهل البرمجة والاستخدام وتتبع الأخطاء. يمكنك تطوير البرامج النصية للتوزيع في بيئات التطوير المفضلة لديك. يمكن تضمين البرامج النصية في قوالب أو في ملفات البرنامج النصية الخارجية.
  • يمكنك تحديد لغة البرنامج النصي والنظام الأساسي. يتم حالياً دعم البرامج النصية لتوزيع Azure PowerShell وAzure CLI على بيئة Linux.
  • يُسمح بتمرير وسيطات سطر الأوامر إلى البرنامج النصي.
  • يمكن تحديد مخرجات البرنامج النصي وتمريرها مرة أخرى إلى التوزيع.

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

هام

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

إشعار

منطق إعادة المحاولة لتسجيل الدخول إلى Azure مضمّن الآن في برنامج التضمين النصي. إذا منحت أذونات في نفس القالب مثل البرامج النصية للتوزيع، فستعمل خدمة البرنامج النصي للتوزيع على إعادة محاولة تسجيل الدخول لمدة 10 دقائق بفاصل زمني مدته 10 ثوانٍ حتى يتم نسخ تعيين دور الهوية المُدارة.

موارد التدريب

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

تكوين الحد الأدنى من الأذونات

بالنسبة إلى إصدار واجهة برمجة التطبيقات للبرنامج النصي للتوزيع بتاريخ 2020-10-01 أو ما بعده، هناك أساسان في تنفيذ البرنامج النصي للتوزيع:

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

    {
  "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
  "description": "Configure least privilege for the deployment principal in deployment script",
  "type": "customRole",
  "IsCustom": true,
  "permissions": [
    {
      "actions": [
        "Microsoft.Storage/storageAccounts/*",
        "Microsoft.ContainerInstance/containerGroups/*",
        "Microsoft.Resources/deployments/*",
        "Microsoft.Resources/deploymentScripts/*"
      ],
    }
  ],
  "assignableScopes": [
    "[subscription().id]"
  ]
}

    إذا لم يتم تسجيل موفري موارد مساحة تخزين Azure ومثيل حاوية Azure، فعليك أيضاً إضافة Microsoft.Storage/register/action وMicrosoft.ContainerInstance/register/action.

  • أساس البرنامج النصي للتوزيع: هذا الأساس مطلوب فقط إذا كان البرنامج النصي للتوزيع يحتاج إلى المصادقة على Azure واستدعاء Azure CLI/PowerShell. هناك طريقتان لتحديد أساس البرنامج النصي للتوزيع:

    • حدد هوية مُدارة يعيّنها المستخدم في خاصية identity (راجع عينات القوالب). عند التحديد، تستدعي خدمة البرنامج النصي Connect-AzAccount -Identity قبل استدعاء البرنامج النصي للتوزيع. يجب أن يكون للهوية المُدارة حق الوصول المطلوب لإكمال العملية في البرنامج النصي. يتم حالياً دعم الهوية المُدارة التي يعيّنها المستخدم فقط للخاصية identity. لتسجيل الدخول بهوية مختلفة، استخدم الأسلوب الثاني في هذه القائمة.
    • مرّر بيانات اعتماد كيان الخدمة كمتغيّرات بيئة آمنة ثم يمكن استدعاء Connect-AzAccount أو az login في البرنامج النصي للتوزيع.

    في حالة استخدام هوية مُدارة، يحتاج أساس التوزيع إلى دور عامل تشغيل الهوية المُدارة (دور مضمّن) الذي تم تعيينه لمورد الهوية المُدارة.

عينات القوالب

يعد JSON التالي مثالاً على ذلك. للحصول على مزيدٍ من المعلومات، راجع أحدث نسخة من مخطط القالب.

{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "runPowerShellInline",
  "location": "[resourceGroup().location]",
  "tags": {
    "tagName1": "tagValue1",
    "tagName2": "tagValue2"
  },
  "kind": "AzurePowerShell", // or "AzureCLI"
  "identity": {
    "type": "userAssigned",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID": {}
    }
  },
  "properties": {
    "forceUpdateTag": "1",
    "containerSettings": {
      "containerGroupName": "mycustomaci"
    },
    "storageAccountSettings": {
      "storageAccountName": "myStorageAccount",
      "storageAccountKey": "myKey"
    },
    "azPowerShellVersion": "9.7",  // or "azCliVersion": "2.47.0",
    "arguments": "-name \\\"John Dole\\\"",
    "environmentVariables": [
      {
        "name": "UserName",
        "value": "jdole"
      },
      {
        "name": "Password",
        "secureValue": "jDolePassword"
      }
    ],
    "scriptContent": "
      param([string] $name)
      $output = 'Hello {0}. The username is {1}, the password is {2}.' -f $name,${Env:UserName},${Env:Password}
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    ", // or "primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",
    "supportingScriptUris":[],
    "timeout": "PT30M",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}

إشعار

يُذكر المثال لأغراض التوضيح. لا يمكن أن توجد الخصائص scriptContent وprimaryScriptUri في قالب.

إشعار

يوضح scriptContent برنامج نصي يحتوي على أسطر متعددة. لا يمكن لمدخل Microsoft Azure ومسار Azure DevOps توزيع برنامج نصي للتوزيع يحتوي على أسطر متعددة. يمكنك إما ربط أوامر PowerShell (باستخدام الفاصلة المنقوطة أو \r\nأو\n) في سطر واحد أو استخدام خاصية primaryScriptUri مع ملف برنامج نصي خارجي. تتوفر العديد من أدوات إلغاء/ عدم إلغاء سلسلة JSON المجانية. على سبيل المثال، https://www.freeformatter.com/json-escape.html

تفاصيل قيمة الخاصية:

  • identity: بالنسبة إلى إصدار واجهة برمجة التطبيقات للبرنامج النصي للتوزيع بتاريخ 2020-10-01 أو ما بعده، تعد الهوية المُدارة التي يعينها المستخدم اختيارية ما لم تكن بحاجة إلى تنفيذ أي إجراءات خاصة بـ Azure في البرنامج النصي. بالنسبة إلى معاينة إصدار واجهة برمجة التطبيقات بتاريخ 2019-10-01، يلزم وجود هوية مُدارة حيث تستخدمها خدمة البرنامج النصي للتوزيع لتنفيذ البرامج النصية. عند تحديد خاصية الهوية، تستدعي خدمة البرنامج النصي Connect-AzAccount -Identity قبل استدعاء البرنامج النصي للمستخدم. يتم حالياً اعتماد الهوية المُدارة التي يعيّنها المستخدم فقط. لتسجيل الدخول بهوية مختلفة، يمكنك استدعاء Connect-AzAccount في البرنامج النصي.

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

  • kind: يحدد نوع البرنامج النصي. يتم حالياً اعتماد البرامج النصية لـ Azure PowerShell وAzure CLI. القيم هي AzurePowerShell وAzureCLI.

  • forceUpdateTag: يؤدي تغيير هذه القيمة بين عمليات توزيع القالب إلى فرض البرنامج النصي للتوزيع لإعادة التنفيذ. إذا كنت تستخدم الوظيفتين newGuid() أو utcNow()، فلا يمكن استخدام كلتا الوظيفتين إلا في القيمة الافتراضية للمعلمة. لمعرفة المزيد، راجع تشغيل البرنامج النصي أكثر من مرة.

  • containerSettings: حدد إعدادات لتخصيص مثيل حاوية Azure. يتطلب البرنامج النصي للتوزيع مثيل حاوية Azure جديد. لا يمكنك تحديد مثيل حاوية Azure حالي. ومع ذلك، يمكنك تخصيص اسم مجموعة الحاوية باستخدام containerGroupName. إذا لم يتم تحديد اسم المجموعة، سيتم إنشاؤه تلقائياً.

  • storageAccountSettings: حدد الإعدادات لاستخدام حساب تخزين حالي. إذا storageAccountName لم يتم تحديد، يتم إنشاء حساب تخزين تلقائيا. راجع استخدام حساب تخزين حالي.

  • azPowerShellVersion/azCliVersion: حدد إصدار الوحدة النمطية المراد استخدامه. راجع قائمة تحتوي على إصدارات Azure PowerShell المدعومة. يحدد الإصدار صورة الحاوية التي يجب استخدامها:

    • يستخدم إصدار Az الأكبر من أو يساوي 9 Ubuntu 22.04.
    • يستخدم الإصدار Az الأكبر من أو يساوي 6 ولكن أقل من 9 Ubuntu 20.04.
    • يستخدم الإصدار Az أقل من 6 Ubuntu 18.04.

    هام

    من المستحسن الترقية إلى أحدث إصدار من Ubuntu، حيث يقترب Ubuntu 18.04 من نهايته ولن يتلقى تحديثات الأمان بعد 31 مايو 2023.

    راجع قائمة إصدارات Azure CLI المدعومة.

    هام

    يستخدم البرنامج النصي للتوزيع نسخ CLI المتوفرة من سجل حاويات Microsoft Container Registry (MCR). يستغرق عادة شهر واحد تقريبا للمصادقة على صورة CLI للبرنامج النصي للتوزيع. لا تستخدم إصدارات CLI التي تم إصدارها خلال 30 يوماً. للعثور على تواريخ إصدار النسخ، راجع ملاحظات حول إصدار Azure CLI. في حال استخدام إصدار غير مدعوم، تدرج رسالة الخطأ الإصدارات المدعومة.

  • arguments: يحدد قيم المعلمات. تُفصل القيم بمسافات.

    تُقسِّم البرامج النصية للتوزيع الوسيطات إلى صفيف من السلاسل عن طريق استحضار استدعاء نظام CommandLineToArgvW. هذه الخطوة ضرورية لأنه يتم تمرير الوسيطات باعتبارها خاصية أمر إلى مثيل حاوية Azure، وخاصية الأمر عبارة عن صفيف من السلسلة.

    إذا كانت الوسيطات تحتوي على أحرف إلغاء، فاستخدم JsonEscaper لمضاعفة أحرف الإلغاء. الصق سلسلة الإلغاء في الأداة، ثم حدد Escape. تعمل الأداة على إخراج سلسلة أحرف إلغاء مزدوجة. على سبيل المثال، في عينة القالب السابق، تكون الوسيطة هي -name \"John Dole\". وتكون سلسلة الإلغاء هي -name \\\"John Dole\\\".

    لتمرير معلمة قالب ARM لعنصر النوع باعتباره وسيطة، حوّل العنصر إلى سلسلة باستخدام وظيفةstring()، ثم استخدم وظيفة replace() لاستبدال أي \" بـ \\\". على سبيل المثال:

    replace(string(parameters('tables')), '\"', '\\\"')

    للحصول على مزيدٍ من المعلومات، راجع عينة القالب.

  • environmentVariables: حدد متغيّرات البيئة لتمريرها إلى البرنامج النصي. للحصول على مزيدٍ من المعلومات، راجع تطوير البرنامج النصي للتوزيع.

  • scriptContent: يحدد محتوى البرنامج النصي. لتشغيل برنامج نصي خارجي، استخدم primaryScriptUri بدلاً من ذلك. على سبيل المثال، راجع استخدام البرنامج النصي المضمّن واستخدام البرنامج النصي الخارجي.

  • primaryScriptUri: حدد عنوان URL يمكن الوصول إليه بشكل عام إلى البرنامج النصي للتوزيع الأساسي باستخدام ملحقات الملفات المدعومة. للحصول على مزيدٍ من المعلومات، راجع استخدام برنامج نصي خارجي.

  • supportingScriptUris: حدد صفيف من عناوين URL التي يمكن الوصول إليها بشكل عام إلى ملفات الدعم التي يتم استدعاؤها في إما scriptContent أو primaryScriptUri. للحصول على مزيدٍ من المعلومات، راجع استخدام برنامج نصي خارجي.

  • timeout: يحدد أقصى وقت مسموح به لتنفيذ البرنامج النصي المحدد بتنسيق ISO 8601. القيمة الافتراضية هي P1D.

  • cleanupPreference. حدد تفضيل تنظيف موردي النشر الداعمين، حساب التخزين ومثيل الحاوية، عندما يحصل تنفيذ البرنامج النصي في حالة المحطة الطرفية. الإعداد الافتراضي هو دائما، ما يعني حذف الموارد الداعمة على الرغم من حالة المحطة الطرفية (ناجحة، فاشلة، ملغاة). لمعرفة المزيد، راجع تنظيف موارد برنامج التوزيع النصي.

  • retentionInterval: حدد الفاصل الزمني الذي تحتفظ الخدمة لمورد البرنامج النصي للتوزيع له بعد وصول تنفيذ البرنامج النصي للتوزيع إلى حالة المحطة الطرفية. يتم حذف مورد البرنامج النصي للتوزيع عند انتهاء هذه المدة. تستند المدة إلى نمط ISO 8601. يتراوح الفاصل الزمني للاستبقاء بين 1 و26 ساعة (PT26H). يتم استخدام هذه الخاصية عند تعيين cleanupPreference إلى OnExpiration. لمعرفة المزيد، راجع تنظيف موارد برنامج التوزيع النصي.

المزيد من النماذج

  • عينة 1: إنشاء مخزن رئيسي واستخدام البرنامج النصي للتوزيع لتعيين شهادة للمخزن الرئيسي.
  • عينة 2: إنشاء مجموعة موارد على مستوى الاشتراك، وإنشاء مخزن رئيسي في مجموعة الموارد، ثم استخدام برنامج نصي للتوزيع لتعيين شهادة للمخزن الرئيسي.
  • عينة 3: إنشاء هوية مُدارة عيّنها المستخدم، وتعيين دور المساهم إلى الهوية على مستوى مجموعة الموارد، وإنشاء مخزن رئيسي، ثم استخدام برنامج نصي للتوزيع لتعيين شهادة للمخزن الرئيسي.
  • نموذج 4: إنه نفس سيناريو النموذج 1 في هذه القائمة. يتم إنشاء مجموعة موارد جديدة لتشغيل برنامج نصي للتوزيع. يعبر هذا القالب عن قالب مستوى اشتراك.
  • نموذج 5: إنه نفس سيناريو النموذج 4. يعبر هذا القالب عن قالب مستوى مجموعة موارد.
  • النموذج 6: إنشاء هوية مدارة يعينها المستخدم يدويا وتعيين إذن لاستخدام Microsoft Graph API لإنشاء تطبيقات Microsoft Entra؛ في قالب ARM، استخدم برنامج نصي للتوزيع لإنشاء تطبيق Microsoft Entra ومدير الخدمة، وإخراج معرفات الكائن ومعرف العميل.

استخدام البرامج النصية المضمّنة

يحتوي القالب التالي على مورد واحد تم تعريفه بالنوع Microsoft.Resources/deploymentScripts. الجزء المميز هو البرنامج النصي المضمّن.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "\\\"John Dole\\\""
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runPowerShellInlineWithOutput",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "scriptContent": "
          param([string] $name)
          $output = \"Hello {0}\" -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "arguments": "[concat('-name', ' ', parameters('name'))]",
        "timeout": "PT1H",
        "cleanupPreference": "OnSuccess",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('runPowerShellInlineWithOutput').outputs.text]",
      "type": "string"
    }
  }
}

إشعار

لأن البرامج النصية للتوزيع المضمّنة تُوضع بين علامات اقتباس مزدوجة، فإن السلاسل الموجودة داخل البرامج النصية للتوزيع تحتاج إلى الإلغاء باستخدام الشرطة المائلة للخلف (\) أو وضعها بين علامات اقتباس مفردة. يمكنك أيضاً محاولة استخدام استبدال السلسلة كما هو موضح في عينة JSON السابقة.

يأخذ البرنامج النصي معلمة واحدة، ويخرج قيمة المعلمة. يتم استخدام DeploymentScriptOutputs لتخزين الإخراجات. في قسم الإخراجات، يوضح السطر value كيفية الوصول إلى القيم المخزّنة. يتم استخدام Write-Output لغرض تصحيح الأخطاء. لمعرفة كيفية الوصول إلى ملف الإخراج، راجع مراقبة البرامج النصية للتوزيع واستكشاف أخطائها وإصلاحها. للحصول على أوصاف الخاصية، راجع عينات القوالب.

لتشغيل البرنامج النصي، حدد Try it لفتح Cloud Shell، ثم لصق التعليمات البرمجية التالية في جزء shell.

$resourceGroupName = Read-Host -Prompt "Enter the name of the resource group to be created"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.json"

Write-Host "Press [ENTER] to continue ..."

يبدو الإخراج مثل:

لقطة شاشة لبرنامج توزيع قالب Resource Manager النصي hello world output.

استخدام البرامج النصية الخارجية

بالإضافة إلى البرامج النصية المضمّنة، يمكنك أيضاً استخدام ملفات البرامج النصية الخارجية. يتم دعم البرامج النصية PowerShell الأساسية فقط مع ملحق الملف ps1. بالنسبة لنصوص CLI النصية، يمكن أن تحتوي البرامج النصية الأساسية على أي ملحقات (أو بدون ملحق)، طالما أن البرامج النصية هي برامج bash نصية صالحة. لاستخدام ملفات البرامج النصية الخارجية، استبدل scriptContent بـ primaryScriptUri. على سبيل المثال:

"primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",

للحصول على مزيدٍ من المعلومات، راجع مثال القالب.

ينبغي أن تكون ملفات البرامج النصية الخارجية قابلة للوصول. لتأمين ملفات البرامج النصية المخزّنة في حسابات مساحة تخزين Azure، أنشئ رمز SAS المميز وأدرجه في URI للقالب. تعيين وقت انتهاء الصلاحية لإتاحة الوقت الكافي لإكمال التوزيع. للحصول على مزيدٍ من المعلومات، راجع توزيع قالب ARM خاص باستخدام رمز SAS المميز.

أنت مسؤول عن ضمان تكامل البرامج النصية المُشار إليها بواسطة البرنامج النصي للتوزيع، إما primaryScriptUri أو supportingScriptUris. ارجع إلى البرامج النصية التي تثق بها فقط.

استخدام البرامج النصية الداعمة

يمكنك فصل المنطق المعقد إلى ملف برنامج نصي داعم واحد أو أكثر. تسمح لك الخاصية supportingScriptUris بتوفير صفيف من URI إلى ملفات البرامج النصية الداعمة إذا لزم الأمر:

"scriptContent": "
    ...
    ./Create-Cert.ps1
    ...
"

"supportingScriptUris": [
  "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/create-cert.ps1"
],

يمكن استدعاء ملفات البرامج النصية الداعمة من البرامج النصية المضمّنة وملفات البرامج النصية الأساسية. لا تمتلك ملفات البرامج النصية الداعمة أي قيود على ملحق اسم الملف.

يتم نسخ الملفات الداعمة إلى azscripts/azscriptinput في وقت التشغيل. استخدم المسار النسبي للرجوع إلى الملفات الداعمة من البرامج النصية المضمّنة وملفات البرامج النصية الأساسية.

العمل مع المخرجات من البرامج النصية PowerShell

يوضح القالب التالي كيفية تمرير القيم بين موردي deploymentScripts:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "John Dole"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate1",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-name', ' ', concat('\\\"', parameters('name'), '\\\"'))]",
        "scriptContent": "
          param([string] $name)
          $output = 'Hello {0}' -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    },
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate2",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "dependsOn": [
        "scriptInTemplate1"
      ],
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-textToEcho', ' ', concat('\\\"', reference('scriptInTemplate1').outputs.text, '\\\"'))]",
        "scriptContent": "
          param([string] $textToEcho)
          Write-Output $textToEcho
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $textToEcho
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('scriptInTemplate2').outputs.text]",
      "type": "string"
    }
  }
}

في المورد الأول، يمكنك تعريف متغيّر يسمى $DeploymentScriptOutputs، واستخدامه لتخزين قيم الإخراج. للوصول إلى قيمة الإخراج من مورد آخر داخل القالب، استخدم:

reference('<ResourceName>').outputs.text

العمل مع المخرجات من البرامج النصية ل CLI

على النقيض من البرامج النصية لتوزيع Azure PowerShell، لا يعرض CLI/bash متغيرا شائعا لتخزين مخرجات البرنامج النصي. بدلا من ذلك، فإنه يستخدم متغير بيئة يسمى AZ_SCRIPTS_OUTPUT_PATH للإشارة إلى موقع ملف مخرجات البرنامج النصي. عند تنفيذ برنامج نصي للتوزيع داخل قالب ARM، يقوم Bash shell تلقائيا بتكوين متغير البيئة هذا نيابة عنك. يتم تعيين قيمته المعرفة مسبقا على أنها /mnt/azscripts/azscriptoutput/scriptoutputs.json. المخرجات مطلوبة لتتوافق مع بنية كائن سلسلة JSON صالحة. يجب تنسيق محتويات الملف كزوج قيم المفاتيح. على سبيل المثال، يجب حفظ صفيف من السلاسل ك { "MyResult": [ "foo", "bar"] }. تخزين نتائج الصفيف فقط، مثل [ "foo"، "bar" ]، يعتبر غير صالح.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "identity": {
      "type": "string"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runBashWithOutputs",
      "location": "[resourceGroup().location]",
      "kind": "AzureCLI",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "[parameters('identity')]": {
          }
        }
      },
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "AzCliVersion": "2.40.0",
        "timeout": "PT30M",
        "arguments": "'foo' 'bar'",
        "environmentVariables": [
          {
            "name": "UserName",
            "value": "jdole"
          },
          {
            "name": "Password",
            "secureValue": "jDolePassword"
          }
        ],
        "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo \"arg2 is: $2\"; echo \"Username is: $UserName\"; echo \"password is: $Password\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
        "cleanupPreference": "OnExpiration",
        "retentionInterval": "P1D"

يتم استخدام jq في العينة السابقة. يتوفر مع نسخ الحاوية. راجع تكوين بيئة تطوير.

استخدام حساب التخزين الحالي

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

  • أنواع حسابات التخزين المدعومة هي:

    وحدة حفظ المخزون SKU النوع المدعوم
    Premium_LRS FileStorage
    Premium_ZRS FileStorage
    Standard_GRS Storage, StorageV2
    Standard_GZRS StorageV2
    Standard_LRS Storage, StorageV2
    Standard_RAGRS Storage, StorageV2
    Standard_RAGZRS StorageV2
    Standard_ZRS StorageV2

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

  • قواعد جدار حماية حساب التخزين غير مدعومة حتى الآن. لمزيد من المعلومات، انظر تكوين جدار حماية التخزين والشبكات الظاهرية في Azure

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

لتحديد حساب تخزين حالي، أضف JSON التالي إلى عنصر الخاصية Microsoft.Resources/deploymentScripts:

"storageAccountSettings": {
  "storageAccountName": "myStorageAccount",
  "storageAccountKey": "myKey"
},

  • storageAccountName: حدد اسم حساب التخزين.

  • storageAccountKey: حدد أحد مفاتيح حساب التخزين. يمكنك استخدام الوظيفة listKeys() لاسترداد المفتاح. على سبيل المثال:

    "storageAccountSettings": {
    "storageAccountName": "[variables('storageAccountName')]",
    "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

راجع عينات القوالب للحصول على عينة تعريف Microsoft.Resources/deploymentScripts كاملة.

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

تطوير البرامج النصية للتوزيع

معالجة الأخطاء غير المحددة

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

تضبط خدمة البرنامج النصي حالة توفير الموارد على Failed عندما يواجه البرنامج النصي خطأ بالرغم من إعداد $ErrorActionPreference.

استخدام متغيرات البيئة

يستخدم البرنامج النصي للتوزيع متغيّرات البيئة هذه:

متغير البيئة القيمة الافتراضية النظام المحجوز
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud N
AZ_SCRIPTS_CLEANUP_PREFERENCE OnExpiration N
AZ_SCRIPTS_OUTPUT_PATH <AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY>/<AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME> Y
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput Y
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput Y
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME Azure PowerShell: userscript.ps1; Azure CLI: userscript.sh Y
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config Y
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config Y
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json Y
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json Y
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY /subscriptions/ N

للحصول على مزيدٍ من المعلومات حول استخدام AZ_SCRIPTS_OUTPUT_PATH، راجع العمل باستخدام الإخراجات من برنامج CLI النصي.

تمرير سلاسل آمنة إلى برنامج نصي للتوزيع

يتيح لك إعداد متغيّرات البيئة (EnvironmentVariable) في مثيلات الحاوية توفير تكوين ديناميكي للتطبيق أو البرنامج النصي الذي يتم تشغيله بواسطة الحاوية. يعالج البرنامج النصي للتوزيع متغيرات البيئة غير الآمنة والمؤمنة بنفس طريقة Azure Container Instance. للحصول على مزيدٍ من المعلومات، راجع تعيين متغيّرات البيئة في مثيلات الحاوية. للحصول على مثال، راجع عينات القوالب.

الحجم الأقصى المسموح به لمتغيّرات البيئة هو 64 KB.

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

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

لقطة شاشة لأسماء موارد البرنامج النصي لتوزيع قالب Resource Manager.

يتم تخزين البرنامج النصي للمستخدم ونتائج التنفيذ وملف stdout في مشاركات الملفات على حساب التخزين. هناك مجلد يسمى azscripts. يوجد في المجلد مجلدين إضافيين لملفات الإدخال والإخراج هما: azscriptinput وazscriptoutput.

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

استخدام مدخل Microsoft Azure

بعد نشر مورد البرنامج النصي للتوزيع، يتم إدراج المورد ضمن مجموعة الموارد في مدخل Microsoft Azure. تعرض لقطة الشاشة التالية صفحة نظرة عامة لمورد برنامج نصي للتوزيع:

لقطة شاشة لنظرة عامة على مدخل البرنامج النصي لتوزيع قالب Resource Manager.

تعرض صفحة النظرة العامة بعض المعلومات الهامة للمورد، مثل حالة التوفير، وحساب التخزين، ومثيل الحاوية، والسجلات.

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

استخدام PowerShell

باستخدام Azure PowerShell، يمكنك إدارة البرامج النصية للتوزيع في نطاق الاشتراك أو مجموعة الموارد:

يتشابه الإخراج Get-AzDeploymentScript مع:

Name                : runPowerShellInlineWithOutput
Id                  : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0618rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput
ResourceGroupName   : myds0618rg
Location            : centralus
SubscriptionId      : 01234567-89AB-CDEF-0123-456789ABCDEF
ProvisioningState   : Succeeded
Identity            : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/mydentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 9.7
StartTime           : 5/11/2023 7:46:45 PM
EndTime             : 5/11/2023 7:49:45 PM
ExpirationDate      : 5/12/2023 7:49:45 PM
CleanupPreference   : OnSuccess
StorageAccountId    : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0618rg/providers/Microsoft.Storage/storageAccounts/ftnlvo6rlrvo2azscripts
ContainerInstanceId : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0618rg/providers/Microsoft.ContainerInstance/containerGroups/ftnlvo6rlrvo2azscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole

RetentionInterval   : P1D
Timeout             : PT1H

استخدام Azure CLI

باستخدام Azure CLI، يمكنك إدارة البرامج النصية للتوزيع في نطاق الاشتراك أو مجموعة الموارد:

يتشابه إخراج الأمر قائمة مع ما يلي:

[
  {
    "arguments": "'foo' 'bar'",
    "azCliVersion": "2.40.0",
    "cleanupPreference": "OnExpiration",
    "containerSettings": {
      "containerGroupName": null
    },
    "environmentVariables": null,
    "forceUpdateTag": "20231101T163748Z",
    "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runBashWithOutputs",
    "identity": {
      "tenantId": "01234567-89AB-CDEF-0123-456789ABCDEF",
      "type": "userAssigned",
      "userAssignedIdentities": {
        "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/myidentity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
          "clientId": "01234567-89AB-CDEF-0123-456789ABCDEF",
          "principalId": "01234567-89AB-CDEF-0123-456789ABCDEF"
        }
      }
    },
    "kind": "AzureCLI",
    "location": "centralus",
    "name": "runBashWithOutputs",
    "outputs": {
      "Result": [
        {
          "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/mytest/providers/Microsoft.KeyVault/vaults/mykv1027",
          "resourceGroup": "mytest"
        }
      ]
    },
    "primaryScriptUri": null,
    "provisioningState": "Succeeded",
    "resourceGroup": "mytest",
    "retentionInterval": "1 day, 0:00:00",
    "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "status": {
      "containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/mytest/providers/Microsoft.ContainerInstance/containerGroups/eg6n7wvuyxn7iazscripts",
      "endTime": "2023-11-01T16:39:12.080950+00:00",
      "error": null,
      "expirationTime": "2023-11-02T16:39:12.080950+00:00",
      "startTime": "2023-11-01T16:37:53.139700+00:00",
      "storageAccountId": null
    },
    "storageAccountSettings": {
      "storageAccountKey": null,
      "storageAccountName": "dsfruro267qwb4i"
    },
    "supportingScriptUris": null,
    "systemData": {
      "createdAt": "2023-10-31T19:06:57.060909+00:00",
      "createdBy": "someone@contoso.com",
      "createdByType": "User",
      "lastModifiedAt": "2023-11-01T16:37:51.859570+00:00",
      "lastModifiedBy": "someone@contoso.com",
      "lastModifiedByType": "User"
    },
    "tags": null,
    "timeout": "0:30:00",
    "type": "Microsoft.Resources/deploymentScripts"
  }
]

استخدام واجهة برمجة تطبيقات REST

يمكنك الحصول على معلومات توزيع مورد البرنامج النصي للتوزيع على مستوى مجموعة الموارد ومستوى الاشتراك باستخدام واجهة برمجة تطبيقات REST:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>?api-version=2020-10-01

/subscriptions/<SubscriptionID>/providers/microsoft.resources/deploymentScripts?api-version=2020-10-01

يستخدم المثال التالي ARMClient:

armclient login
armclient get /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

يتشابه الإخراج مع:

{
  "kind": "AzurePowerShell",
  "identity": {
    "type": "userAssigned",
    "tenantId": "01234567-89AB-CDEF-0123-456789ABCDEF",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myidentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
        "principalId": "01234567-89AB-CDEF-0123-456789ABCDEF",
        "clientId": "01234567-89AB-CDEF-0123-456789ABCDEF"
      }
    }
  },
  "location": "centralus",
  "systemData": {
    "createdBy": "someone@contoso.com",
    "createdByType": "User",
    "createdAt": "2023-05-11T02:59:04.7501955Z",
    "lastModifiedBy": "someone@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2023-05-11T02:59:04.7501955Z"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "forceUpdateTag": "20220625T025902Z",
    "azPowerShellVersion": "9.7",
    "scriptContent": "\r\n          param([string] $name)\r\n          $output = \"Hello {0}\" -f $name\r\n          Write-Output $output\r\n          $DeploymentScriptOutputs = @{}\r\n          $DeploymentScriptOutputs['text'] = $output\r\n        ",
    "arguments": "-name \\\"John Dole\\\"",
    "retentionInterval": "P1D",
    "timeout": "PT1H",
    "containerSettings": {},
    "status": {
      "containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0624rg/providers/Microsoft.ContainerInstance/containerGroups/64lxews2qfa5uazscripts",
      "storageAccountId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0624rg/providers/Microsoft.Storage/storageAccounts/64lxews2qfa5uazscripts",
      "startTime": "2023-05-11T02:59:07.5951401Z",
      "endTime": "2023-05-11T03:00:16.7969234Z",
      "expirationTime": "2023-05-12T03:00:16.7969234Z"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "runPowerShellInlineWithOutput"
}

تعمل واجهة برمجة تطبيقات REST التالية على إرجاع السجل:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>/logs?api-version=2020-10-01

تعمل فقط قبل حذف موارد البرنامج النصي للتوزيع.

للاطلاع على مورد deploymentScripts في المدخل، حدد Show hidden types:

لقطة شاشة للبرنامج النصي لتوزيع قالب Resource Manager مع خيار إظهار الأنواع المخفية في المدخل.

تنظيف موارد البرنامج النصي للتوزيع

لا يمكن أبدا deploymentScript للموردين اللذين تم إنشاؤها تلقائيا دعم المورد، ما لم تكن هناك حالات فشل في حذفها. يتم التحكم في دورة حياة الموارد الداعمة بواسطة الخاصية cleanupPreference ، ويتم التحكم في دورة deploymentScript حياة المورد بواسطة الخاصية retentionInterval :

  • cleanupPreference: حدد تفضيل التنظيف لموارد الدعم اثنين عند تنفيذ البرنامج النصي يحصل في حالة المحطة الطرفية. القيم المدعومة هي:

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

    • OnSuccess: احذف موردي الدعم فقط عند نجاح تنفيذ البرنامج النصي. إذا تم استخدام حساب تخزين حالي، تعمل خدمة البرنامج النصي على إزالة مشاركة الملف فقط عند نجاح تنفيذ البرنامج النصي.

      إذا لم ينجح تنفيذ البرنامج النصي، تنتظر خدمة البرنامج النصي حتى retentionInterval تنتهي صلاحيتها قبل تنظيف الموارد الداعمة ثم مورد البرنامج النصي للتوزيع.

    • OnExpiration: احذف موردي الدعم فقط عند retentionInterval انتهاء صلاحية الإعداد. إذا تم استخدام حساب تخزين حالي، فإن خدمة البرنامج النصي تزيل مشاركة الملف، لكنها تحتفظ بحساب التخزين.

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

  • retentionInterval: حدد الفاصل الزمني الذي سيتم فيه الاحتفاظ بمورد deploymentScript وبعد ذلك سيتم انتهاء صلاحيته وحذفه.

إشعار

لا يوصى باستخدام حساب التخزين ومثيل الحاوية التي تم إنشاؤها بواسطة خدمة البرنامج النصي لأغراض أخرى. قد تتم إزالة هذين الموردين حسب دورة حياة البرنامج النصي.

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

تشغيل البرنامج النصي أكثر من مرة

يُعد تنفيذ البرنامج النصي للتوزيع عملية متكررة. إذا لم يتم تغيير أي من خصائص المورد deploymentScripts (بما في ذلك البرنامج النصي المضمّن)، لا يعمل البرنامج النصي على التنفيذ عند إعادة توزيع القالب. تقارن خدمة البرنامج النصي للتوزيع أسماء الموارد في القالب مع الموارد الموجودة في نفس مجموعة الموارد. يوجد خياران إذا كنت تريد تنفيذ نفس البرنامج النصي للتوزيع عدة مرات:

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

    إشعار

    لا يمكن استخدام الوظيفة utcNow إلا في القيمة الافتراضية للمعلمة.

  • حدد قيمة مختلفة في خاصية القالب forceUpdateTag. على سبيل المثال، استخدم utcNow كقيمة.

إشعار

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

تكوين بيئة التطوير

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

بعد اختبار البرنامج النصي بنجاح، يمكنك استخدامه كبرنامج نصي للتوزيع في القوالب.

رموز خطأ البرنامج النصي للتوزيع

رمز الخطأ ‏‏الوصف
DeploymentScriptInvalidOperation يحتوي تعريف مصدر البرنامج النصي للتوزيع في القالب على أسماء خصائص غير صالحة.
DeploymentScriptResourceConflict لا يمكن حذف مورد برنامج نصي للتوزيع في حالة غير دائمة ولم يتجاوز التنفيذ ساعة واحدة. أو لا يمكن إعادة تشغيل نفس البرنامج النصي للتوزيع بنفس معرّف المورد (نفس الاشتراك واسم مجموعة الموارد واسم المورد) ولكن محتوى برنامج نصي مختلف في نفس الوقت.
DeploymentScriptOperationFailed فشلت عملية البرنامج النصي للتوزيع داخليًا. الاتصال بدعم Microsoft.
DeploymentScriptStorageAccountAccessKeyNotSpecified لم يتم تحديد مفتاح الاختصار لحساب التخزين الحالي.
DeploymentScriptContainerGroupContainsInvalidContainers تم تعديل مجموعة الحاويات التي تم إنشاؤها بواسطة خدمة البرنامج النصي للتوزيع خارجيًا، وتمت إضافة الحاويات غير الصالحة.
DeploymentScriptContainerGroupInNonterminalState يستخدم اثنان أو أكثر من موارد البرنامج النصي للتوزيع نفس اسم مثيل حاوية Azure في نفس مجموعة الموارد، ولم ينته أحدهما من تنفيذه بعد.
DeploymentScriptStorageAccountInvalidKind لا يدعم حساب التخزين الحالي لنوع BlobBlobStorage أو BlobStorage مشاركات الملفات، ولا يمكن استخدامه.
DeploymentScriptStorageAccountInvalidKindAndSku لا يدعم حساب التخزين الحالي مشاركات الملفات. للحصول على قائمة بأنواع حسابات التخزين المدعومة، راجع استخدام حساب التخزين الحالي.
DeploymentScriptStorageAccountNotFound حساب التخزين غير موجود أو تم حذفه بواسطة عملية أو أداة خارجية.
DeploymentScriptStorageAccountWithServiceEndpointEnabled يحتوي حساب التخزين المحدد على نقطة تقديم خدمة. لا يتم دعم حساب تخزين يحتوي على نقطة تقديم خدمة.
DeploymentScriptStorageAccountInvalidAccessKey مفتاح اختصار غير صالح محدد لحساب التخزين الحالي.
DeploymentScriptStorageAccountInvalidAccessKeyFormat تنسيق مفتاح حساب تخزين غير صالح. راجع إدارة مفاتيح اختصار حساب التخزين.
DeploymentScriptExceededMaxAllowedTime تجاوز وقت تنفيذ البرنامج النصي للتوزيع قيمة المهلة المحددة في تعريف مورد البرنامج النصي للتوزيع.
DeploymentScriptInvalidOutputs إخراج البرنامج النصي للتوزيع ليس عنصر JSON صالحًا.
DeploymentScriptContainerInstancesServiceLoginFailure لم تتمكن الهوية المُدارة التي عيّنها المستخدم من تسجيل الدخول بعد 10 محاولات بفاصل زمني مدته دقيقة واحدة.
DeploymentScriptContainerGroupNotFound تم حذف مجموعة الحاويات التي تم إنشاؤها بواسطة خدمة البرنامج النصي للتوزيع بواسطة أداة أو عملية خارجية.
DeploymentScriptDownloadFailure فشل تنزيل برنامج نصي داعم. راجع استخدام البرامج النصية الداعمة.
DeploymentScriptError أظهر البرنامج النصي للمستخدم خطأ.
DeploymentScriptBootstrapScriptExecutionFailed أظهر البرنامج النصي bootstrap خطأ. البرنامج النصي Bootstrap هو البرنامج النصي للنظام الذي ينظم تنفيذ البرنامج النصي للتوزيع.
DeploymentScriptExecutionFailed خطأ غير معروف أثناء تنفيذ البرنامج النصي للتوزيع.
DeploymentScriptContainerInstancesServiceUnavailable عند إنشاء مثيل حاوية Azure (ACI)، أظهر ACI خطأ بأن هناك خدمة غير متوفرة.
DeploymentScriptContainerGroupInNonterminalState عند إنشاء مثيل حاوية Azure (ACI)، يستخدم برنامج نصي آخر للتوزيع نفس اسم ACI في نفس النطاق (نفس الاشتراك واسم مجموعة الموارد واسم المورد).
DeploymentScriptContainerGroupNameInvalid لا يفي اسم مثيل حاوية Azure (ACI) المحدد بمتطلبات ACI. راجع استكشاف المشكلات الشائعة في مثيلات حاوية Azure وإصلاحها.

استخدام Microsoft Graph ضمن برنامج نصي للتوزيع

يمكن للبرنامج النصي للتوزيع استخدام Microsoft Graph لإنشاء الكائنات والعمل معها في Microsoft Entra ID.

الأوامر

عند استخدام البرامج النصية لتوزيع Azure CLI، يمكنك استخدام الأوامر داخل az ad مجموعة الأوامر للعمل مع التطبيقات وكيانات الخدمة والمجموعات والمستخدمين. يمكنك أيضا استدعاء واجهات برمجة تطبيقات Microsoft Graph مباشرة باستخدام az rest الأمر .

عند استخدام البرامج النصية لتوزيع Azure PowerShell، يمكنك استخدام Invoke-RestMethod cmdlet لاستدعاء واجهات برمجة تطبيقات Microsoft Graph مباشرة.

الأذونات

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

الوصول إلى الشبكة الظاهرية الخاصة

باستخدام Microsoft.Resources/deploymentScripts الإصدار 2023-08-01، يمكنك تشغيل البرامج النصية للتوزيع في الشبكات الخاصة مع بعض التكوينات الإضافية.

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

  • إنشاء حساب تخزين مع allowSharedKeyAccess تعيين إلى true ، وتحديد البرنامج النصي للتوزيع لاستخدام حساب التخزين الموجود. لتحديد حساب تخزين موجود، راجع استخدام حساب تخزين موجود. مطلوب بعض التكوين الإضافي لحساب التخزين.

    1. افتح حساب التخزين في مدخل Microsoft Azure.

    2. من القائمة اليسرى، حدد Access Control (IAM)، ثم حدد علامة التبويب Role assignments .

    3. Storage File Data Privileged Contributor أضف الدور إلى الهوية المدارة لتعيين المستخدم.

    4. من القائمة اليسرى، ضمن Security + networking، حدد Networking، ثم حدد Firewalls and virtual networks.

    5. حدد Enabled من الشبكات الظاهرية المحددة وعناوين IP.

      لقطة شاشة لتكوين حساب التخزين للوصول إلى الشبكة الخاصة.

    6. ضمن الشبكات الظاهرية، أضف شبكة فرعية. في لقطة الشاشة، تسمى الشبكة الفرعية dspvnVnet.

    7. ضمن استثناءات، حدد السماح لخدمات Azure في قائمة الخدمات الموثوق بها للوصول إلى حساب التخزين هذا.

يوضح قالب ARM التالي كيفية تكوين البيئة لتشغيل برنامج نصي للتوزيع:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string",
      "maxLength": 10
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "userAssignedIdentityName": {
      "type": "string",
      "defaultValue": "[format('{0}Identity', parameters('prefix'))]"
    },
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[format('{0}stg{1}', parameters('prefix'), uniqueString(resourceGroup().id))]"
    },
    "vnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Vnet', parameters('prefix'))]"
    },
    "subnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Subnet', parameters('prefix'))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2023-09-01",
      "name": "[parameters('vnetName')]",
      "location": "[parameters('location')]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "10.0.0.0/16"
          ]
        },
        "enableDdosProtection": false,
        "subnets": [
          {
            "name": "[parameters('subnetName')]",
            "properties": {
              "addressPrefix": "10.0.0.0/24",
              "serviceEndpoints": [
                {
                  "service": "Microsoft.Storage"
                }
              ],
              "delegations": [
                {
                  "name": "Microsoft.ContainerInstance.containerGroups",
                  "properties": {
                    "serviceName": "Microsoft.ContainerInstance/containerGroups"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2023-01-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "networkAcls": {
          "bypass": "AzureServices",
          "virtualNetworkRules": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]",
              "action": "Allow",
              "state": "Succeeded"
            }
          ],
          "defaultAction": "Deny"
        },
        "allowSharedKeyAccess": true
      },
      "dependsOn": [
        "[resourceId('Microsoft.Network/virtualNetworks', parameters('vnetName'))]"
      ]
    },
    {
      "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
      "apiVersion": "2023-07-31-preview",
      "name": "[parameters('userAssignedIdentityName')]",
      "location": "[parameters('location')]"
    },
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2022-04-01",
      "scope": "[format('Microsoft.Storage/storageAccounts/{0}', parameters('storageAccountName'))]",
      "name": "[guid(tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd'), resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName')))]",
      "properties": {
        "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), '2023-07-31-preview').principalId]",
        "roleDefinitionId": "[tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd')]",
        "principalType": "ServicePrincipal"
      },
      "dependsOn": [
        "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
      ]
    }
  ]
}

يمكنك استخدام قالب ARM التالي لاختبار التوزيع:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    },
    "storageAccountName": {
      "type": "string"
    },
    "vnetName": {
      "type": "string"
    },
    "subnetName": {
      "type": "string"
    },
    "userAssignedIdentityName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2023-08-01",
      "name": "[format('{0}DS', parameters('prefix'))]",
      "location": "[parameters('location')]",
      "identity": {
        "type": "userAssigned",
        "userAssignedIdentities": {
          "[format('{0}', resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')))]": {}
        }
      },
      "kind": "AzureCLI",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azCliVersion": "2.47.0",
        "storageAccountSettings": {
          "storageAccountName": "[parameters('storageAccountName')]"
        },
        "containerSettings": {
          "subnetIds": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]"
            }
          ]
        },
        "scriptContent": "echo \"Hello world!\"",
        "retentionInterval": "P1D",
        "cleanupPreference": "OnExpiration"
      }
    }
  ]
}

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

لقد تعرّفت في هذه المقالة على كيفية استخدام البرامج النصية للتوزيع. لتصفح برنامج تعليمي للبرنامج النصي للتوزيع:

البرنامج التعليمي: استخدام برامج نصية للتوزيع في قوالب Azure Resource Manager

وحدة Microsoft Learn النمطية: توسيع قوالب ARM باستخدام البرامج النصية للتوزيع