مشاركة عبر

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

  • مقالة

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

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

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

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

إشعار

لا يتعرف الإصدار الحالي من ملحق 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]"
            }
          }
        ]
      }
    }
  ]
}

قوالب المثال

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

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

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