مشاركة عبر

إنشاء ملف معلمة إدارة الموارد

  • مقالة

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

تلميح

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

ملف المعلمة

يستخدم ملف المعلمة التنسيق التالي:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

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

يشمل ملف المعلمة التالي قيمة لنص عادي وقيمة حساسة مخزنة في مخزن المفاتيح.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "reference": {
        "keyVault": {
          "id": "<resource-id-key-vault>"
        },
        "secretName": "<secret-name>"
      }
    }
  }
}

للحصول على مزيد من المعلومات حول استخدام القيم الموجودة في مخزن المفاتيح، راجع استخدام Azure Key Vault لتمرير قيمة المعلمة الآمنة أثناء عملية التوزيع.

تعريف قيم المعلمات

لتحديد كيفية تعريف أسماء المعلمات وقيمها، افتح قالب JSON وراجع القسم parameters. ويوضح المثال التالي معلمات قالب JSON.

"parameters": {
  "storagePrefix": {
    "type": "string",
    "maxLength": 11
  },
  "storageAccountType": {
    "type": "string",
    "defaultValue": "Standard_LRS",
    "allowedValues": [
    "Standard_LRS",
    "Standard_GRS",
    "Standard_ZRS",
    "Premium_LRS"
    ]
  }
}

في ملف المعلمة، أول التفاصيل التي يجب ملاحظتها هي اسم كل معلمة. ولا بد أن تتطابق أسماء المعلمات في ملف المعلمة مع أسماء المعلمات الموجودة في القالب.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

لاحظ نوع المعلمة. يجب أن تستخدم أنواع المعلمات في ملف المعلمة نفس أنواع المعلمات التي في القالب. وفي المثال التالي، نوعا المعلمة كلاهما من السلاسل.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": ""
    },
    "storageAccountType": {
      "value": ""
    }
  }
}

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Template will use default value if not provided.
    }
  }
}

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

إشعار

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

تنسيقات نوع المعلمة

يوضح المثال التالي تنسيقات أنواع مختلفة من المعلمات: سلسلة، وعدد صحيح، ومنطقي، ومصفوفة، وكائن.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

توزيع القالب باستخدام ملف المعلمة

يمكنك من خلال واجهة سطر الأوامر Azure CLI تمرير ملف معلمة محلية باستخدام @ واسم ملف المعلمة. على سبيل المثال، @storage.parameters.json

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters @storage.parameters.json

لمعرفة مزيد من المعلومات، راجع توزيع الموارد باستخدام قوالب ARM واجهة سطر الأوامر Azure CLI.

يمكنك من خلال Azure PowerShell تمرير ملف معلمة محلية باستخدام المعلمة TemplateParameterFile.

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.json `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json

للحصول على مزيد من المعلومات، راجع توزيع الموارد باستخدام قوالب ARM وAzure PowerShell.

إشعار

لا يمكن استخدام ملف معلمة مع شفرة القالب المخصصة في المدخل.

تلميح

إذا كنت تستخدم مشروع «Azure Resource Group» في Visual Studio، فتأكد من أن ملف المعلمة يعين Build Action فيه على الوضع Content.

اسم الملف

يتمثل إصلاح التسمية العامة لملف المعلمة في إدراج المعلمات في اسم القالب. على سبيل المثال، إذا كان اسم القالب هو azuredeploy.json، سيكون اسم ملف المعلمة هو azuredeploy.parameters.json. تساعدك تقنية إصلاح التسمية هذه على معرفة صيغة الاتصال بين القالب والمعلمات.

لتوزيع الموارد إلى بيئات مختلفة، يمكنك إنشاء أكثر من ملف معلمة. عند تسمية ملفات المعلمات، حدد استخدامها مثل التطوير والإنتاج. على سبيل المثال، استخدم azuredeploy.parameters-dev.json وazuredeploy.parameters-prod.json لتوزيع الموارد.

أسبقية المعلمة

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

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

تعارضات اسم المعلمة

وإذا اشتمل القالب على معلمة بنفس اسم إحدى المعلمات المذكورة في أمر PowerShell، يقدم PowerShell المعلمة من القالب مع اللاحقة FromTemplate. على سبيل المثال، تعارض المعلمة المسماة ResourceGroupName في القالب مع المعلمة ResourceGroupName الموجودة في New-AzResourceGroupDeployment cmdlet. يجب توفير قيمة للمعلمة ResourceGroupNameFromTemplate. لتجنب هذا الالتباس، استخدم أسماء المعلمات التي لا تُستخدم لأوامر التوزيع.

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