المعلمات داخل قوالب ARM

مقالة
09/03/2023

توضح هذه المقالة كيفية تعريف واستخدام المعلمات داخل قالبAzure Resource Manager (قالب ARM). عن طريق توفير قيم مختلفة للمعلمات، يمكنك إعادة استخدام قالب لبيئات مختلفة.

تقوم Azure Resource Manager بحل قيم المعلمات قبل بدء عمليات النشر. أينما يتم استخدام المعلمة داخل القالب، يستبدلها Azure Resource Manager بالقيمة التي تم حلها.

يجب تحديد كل معلمة ضمن واحدة منأنواع البيانات.

بالإضافة إلى minValue وmaxValue وminLength وmaxLength و allowedValues، يقدم languageVersion 2.0 بعض قيود التحقق من صحة النوع التجميعي لاستخدامها في التعريفات والمعلمات وتعريفات المخرجات. وتشمل هذه القيود ما يلي:

additionalProperties
مميز
items
القيم الخاليه
البادئةItems
الخصائص

ملاحظة

لا يتعرف الإصدار الحالي من ملحق Azure Resource Manager Tools ل Visual Studio Code على التحسينات التي تم إجراؤها في languageVersion 2.0.

تلميح

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

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

للحصول على أفضل ممارسات المعلمات، راجع المعلمات.

الحد الأدنى من الإعلان بالربط

كحد أدنى، تحتاج كل معلمة إلى اسم ونوع.

عند استخدام قالب عبر مدخل Microsoft Azure، يتم تحويل أسماء المعلمات ذات الحالة الجملية إلى أسماء مفصولة بمساحة. على سبيل المثال،تظهر demoString في المثال الآتيكسلسلة عرض توضيحي. للحصول على مزيد من المعلومات حول خيار الاستخدام هذا، انظراستخدام زر الاستخدام لاستخدام القوالب من مستودع GitHubواستخدام الموارد باستخدام قوالب ARM ومدخل Microsoft Azure.

"parameters": {
  "demoString": {
    "type": "string"
  },
  "demoInt": {
    "type": "int"
  },
  "demoBool": {
    "type": "bool"
  },
  "demoObject": {
    "type": "object"
  },
  "demoArray": {
    "type": "array"
  }
}

معلمات تتميز بالأمان

يمكنك وضع علامة على معلمات السلسلة أو الكائن على أنها آمنة. لا يتم حفظ قيمة معلمة آمنة في محفوظات النشر ولا يتم تسجيلها.

"parameters": {
  "demoPassword": {
    "type": "secureString"
  },
  "demoSecretObject": {
    "type": "secureObject"
  }
}

القيم المسموح بها

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

"parameters": {
  "demoEnum": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

القيمة الافتراضية

يمكنك تحديد قيمة افتراضية لمعلمة. تُستخدم القيمة الافتراضية عندما لا تتوفر قيمة أثناء الاستخدام.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso"
  }
}

لتحديد قيمة افتراضية مع خصائص أخرى للمعلمة، قم باستخدام تركيب الجملة التالي.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso",
    "allowedValues": [
      "Contoso",
      "Fabrikam"
    ]
  }
}

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

التعبيرات غير المسموح بها مع خصائص المعلمات الأخرى.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

من الممكن استخدام قيمة معلمة أخرى لبناء قيمة افتراضية. يُنشئ القالب التالي اسم خطة مضيف من اسم الموقع.

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]"
  }
}

قيود المدى

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

يوضح المثال التالي اثنتين من المعلمات. معلمة واحدة تكون لاسم حساب موقع تخزين يجب أن تحتوي على 3-24 حرفًا. المعلمة الأخرى عبارة عن صفيف يجب أن يكون من 1-5 عناصر.

"parameters": {
  "storageAccountName": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNames": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

قيود العدد الصحيح

يمكنك تعيين قيم الحد الأدنى والأقصى لمعلمات عدد صحيح. يمكنك تعيين قيد أو كليهما.

"parameters": {
  "month": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

قيود الكائن

يسمح بقيود الكائن فقط على الكائنات، ولا يمكن استخدامها إلا مع languageVersion 2.0.

الخصائص

قيمة properties هي خريطة لاسم الخاصية =>تعريف النوع.

سيقبل {"foo": "string", "bar": 1}المثال التالي ، ولكن يرفض {"foo": "string", "bar": -1}، {"foo": "", "bar": 1}أو أو أي كائن بدون خاصية foo أو bar .

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
}

جميع الخصائص مطلوبة ما لم يكن تعريف نوع الخاصية يحتوي على "nullable": القيد الحقيقي . لجعل كلتا الخاصيتين في المثال السابق اختيارية، ستبدو كما يلي:

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

قيمة additionalProperties هي تعريف نوع أو قيمة منطقية. إذا لم يتم تعريف أي additionalProperties قيد، فإن القيمة الافتراضية هي true.

إذا كانت القيمة تعريف نوع، فإن القيمة تصف المخطط الذي يتم تطبيقه على جميع الخصائص غير المذكورة في القيد properties . سيقبل {"fizz": "buzz", "foo": "bar"} المثال التالي ولكن يرفض {"property": 1}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

إذا كانت القيمة هي false، فقد لا يتم توفير أي خصائص تتجاوز تلك المحددة في القيد properties . سيقبل {"foo": "string", "bar": 1}المثال التالي ، ولكنه يرفض {"foo": "string", "bar": 1, "fizz": "buzz"}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

إذا كانت القيمة هي true، فإن أي خاصية لم يتم تعريفها في القيد properties تقبل أي قيمة. سيقبل {"foo": "string", "bar": 1, "fizz": "buzz"}المثال التالي .

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

مميز

تحدد القيمة discriminator المخطط الذي يجب تطبيقه استنادا إلى خاصية تمييزية. سيقبل المثال التالي إما {"type": "ints", "foo": 1, "bar": 2} أو {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}، ولكن رفض {"type": "ints", "fizz": "buzz"}.

"parameters": {
  "taggedUnionParameter": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

قيود الصفيف

يسمح بقيود الصفيف فقط على الصفائف، ويمكن استخدامها فقط مع languageVersion 2.0.

البادئةItems

قيمة prefixItems هي صفيف من تعريفات النوع. كل تعريف نوع في القيمة هو المخطط الذي سيتم استخدامه للتحقق من صحة عنصر صفيف في نفس الفهرس. سيقبل [1, true] المثال التالي ولكن يرفض [1, "string"] أو [1]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

العناصر

قيمة items هي تعريف نوع أو قيمة منطقية. إذا لم يتم تعريف أي items قيد، فإن القيمة الافتراضية هي true.

إذا كانت القيمة تعريف نوع، فإن القيمة تصف المخطط الذي يتم تطبيقه على جميع عناصر الصفيف الذي يكون فهرسه أكبر من أكبر فهرس للقيد prefixItems . المثال التالي سيقبل [1, true, 1] أو [1, true, 1, 1] ولكن يرفض [1, true, "foo"]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" },
    "defaultValue": [1, true, "foo"]
  }
}

يمكنك استخدام items دون استخدام prefixItems. المثال التالي سيقبل [1, 2] أو [1] ولكن يرفض ["foo"]:

"parameters": {
  "intArrayParameter": {
    "type": "array",
    "items": {"type": "int"}
  }
}

إذا كانت القيمة هي false، يجب أن يكون الصفيف الذي تم التحقق من صحته بنفس طول القيد prefixItems بالضبط. سيقبل [1, true]المثال التالي ، ولكن يرفض [1, true, 1]و و [1, true, false, "foo", "bar"].

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ],
    "items": false
  }
}

إذا كانت القيمة صحيحة، فإن عناصر الصفيف الذي يكون فهرسه أكبر من أكبر فهرس للقيد prefixItems تقبل أي قيمة. تقبل [1, true]الأمثلة التالية و [1, true, 1] و [1, true, false, "foo", "bar"].

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

قيد قابل للقيمة الخالية

يمكن استخدام القيد القابل للإلغاء فقط مع languageVersion 2.0. يشير إلى أن القيمة قد تكون null أو محذفة. راجع الخصائص للحصول على مثال.

الوصف

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

"parameters": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

الاستخدام المتعلق بالمعلمة

للإشارة إلى قيمة المعلمة، استخدم دالة المعلمات. يستخدم المثال التالي قيمة المعلمة لاسم "المخزن الرئيسي".

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vaultName": {
      "type": "string",
      "defaultValue": "[format('keyVault{0}', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-06-01-preview",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

العناصر كمعلمات

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

يوضح المثال التالي أن المعلمة تمثل عنصرًا. تُظهر القيمة الافتراضية الخصائص المتوقعة للعنصر. تُستخدم هذه الخصائص عند تعريف المورد للاستخدام.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vNetSettings": {
      "type": "object",
      "defaultValue": {
        "name": "VNet1",
        "location": "eastus",
        "addressPrefixes": [
          {
            "name": "firstPrefix",
            "addressPrefix": "10.0.0.0/22"
          }
        ],
        "subnets": [
          {
            "name": "firstSubnet",
            "addressPrefix": "10.0.0.0/24"
          },
          {
            "name": "secondSubnet",
            "addressPrefix": "10.0.1.0/24"
          }
        ]
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2021-02-01",
      "name": "[parameters('vNetSettings').name]",
      "location": "[parameters('vNetSettings').location]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vNetSettings').addressPrefixes[0].addressPrefix]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('vNetSettings').subnets[0].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[0].addressPrefix]"
            }
          },
          {
            "name": "[parameters('vNetSettings').subnets[1].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[1].addressPrefix]"
            }
          }
        ]
      }
    }
  ]
}

نماذج القوالب

تعرض الأمثلة التالية سيناريوهات لاستخدام المعلمات.

قالب	الوصف
معلمات ذات دوال للقيم الافتراضية	تعرض كيفية استخدام وظائف القالب عند تعريف القيم الافتراضية للمعلمات. لا يستخدم القالب أية موارد. يُنشئ قيم المعلمات ويُعيد تلك القيم.
عناصر المعلمة	يعرض استخدام العنصر لمعلمة. لا يستخدم القالب أية موارد. يُنشئ قيم المعلمات ويُعيد تلك القيم.

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

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

Share via