Share via

بناء الجملة والتعبيرات في قوالب ARM

  • مقالة

البنية الأساسية لقالب Azure Resource Manager (قالب ARM) هي JavaScript Object Notation (JSON). ومع ذلك، يمكنك استخدام التعبيرات لتوسيع قيم JSON المتوفرة داخل القالب. تبدأ التعبيرات وتنتهي بأقواس: ⁧[⁩ و⁧]⁩، على التوالي. يتم تقييم قيمة التعبير عند نشر القالب. يمكن أن يرجع التعبير سلسلة أو عددًا صحيحًا أو منطقيًا أو صفيفًا أو كائنًا.

لا يمكن أن يتجاوز تعبير القالب 24576 حرفاً.

استخدام الدوال

يوفر Azure Resource Manager وظائف يمكنك استخدامها في قالب. يُظهر المثال التالي تعبيراً يستخدم دالة في القيمة الافتراضية للمعلمة:

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

ضمن التعبير، يستدعي بناء الجملة resourceGroup() إحدى الوظائف التي يوفرها Resource Manager للاستخدام داخل قالب. في هذه الحالة، إنها وظيفة ResourceGroup. تماماً كما هو الحال في JavaScript، يتم تنسيق استدعاءات الوظائف كـ functionName(arg1,arg2,arg3). يسترد بناء الجملة .location خاصية واحدة من الكائن الذي تم إرجاعه بواسطة تلك الوظيفة.

وظائف القالب ومعلماتها غير حساسة لحالة الأحرف. على سبيل المثال، قرر Resource Manager أن variables('var1') وVARIABLES('VAR1') هو نفسه. عند التقييم، ما لم تعدل الدالة الحالة صراحةً (مثل toUpper أو toLower)، فإن الوظيفة تحافظ على الحالة. قد تحتوي أنواع موارد معينة على متطلبات حالة منفصلة عن كيفية تقييم الوظائف.

لتمرير قيمة سلسلة كمعامل إلى دالة، استخدم علامات الاقتباس المفردة.

"name": "[concat('storage', uniqueString(resourceGroup().id))]"

تعمل معظم الوظائف بنفس الطريقة سواء تم توزيعها في مجموعة موارد أو اشتراك أو مجموعة إدارة أو مستأجر. الوظائف التالية لها قيود على أساس النطاق:

  • ResourceGroup - يمكن استخدامها فقط في عمليات النشر لمجموعة الموارد.
  • ResourceId - يمكن استخدامه في أي نطاق، ولكن تتغير المعلمات الصالحة اعتماداً على النطاق.
  • اشتراك - يمكن استخدامه فقط في عمليات النشر إلى مجموعة موارد أو اشتراك.

شخصيات الهروب

للحصول على سلسلة حرفية تبدأ بقوس أيسر [ وتنتهي بقوس أيمن ]، ولكن لا يتم تفسيرها كتعبير، أضف قوساً إضافياً لبدء السلسلة بـ [[. على سبيل المثال، المتغير:

"demoVar1": "[[test value]"

يقرر إلى [test value].

ومع ذلك، إذا لم تنتهي السلسلة الحرفية بقوس، فلا تهرب من القوس الأول. على سبيل المثال، المتغير:

"demoVar2": "[test] value"

يقرر إلى [test] value.

للهروب من علامات الاقتباس المزدوجة في تعبير، مثل إضافة كائن JSON في القالب، استخدم الشرطة المائلة للخلف.

"tags": {
    "CostCenter": "{\"Dept\":\"Finance\",\"Environment\":\"Production\"}"
},

للهروب من علامات الاقتباس الفردية في إخراج تعبير ARM، قم بمضاعفة علامات الاقتباس الفردية. ينتج عن إخراج القالب التالي قيمة {"abc":"'quoted'"}JSON .

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "resources": [],
  "outputs": {
    "foo": {
      "type": "object",
      "value": "[createObject('abc', '''quoted''')]"
    }
  }
}

في تعريف المورد، قيم الإلغاء المزدوج داخل تعبير. من scriptOutput القالب التالي هو de'f.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "forceUpdateTag": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    "deploymentScriptSharedProperties": {
      "forceUpdateTag": "[parameters('forceUpdateTag')]",
      "azPowerShellVersion": "10.1",
      "retentionInterval": "P1D"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "escapingTest",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": "[union(variables('deploymentScriptSharedProperties'), createObject('scriptContent', '$DeploymentScriptOutputs = @{}; $DeploymentScriptOutputs.escaped = \"de''''f\";'))]"
    }
  ],
  "outputs": {
    "scriptOutput": {
      "type": "string",
      "value": "[reference('escapingTest').outputs.escaped]"
    }
  }
}

مع languageVersion 2.0، يلزم الهروب المزدوج لفترة أطول. يمكن كتابة المثال السابق ك JSON التالي للحصول على نفس النتيجة، de'f.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "forceUpdateTag": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    "deploymentScriptSharedProperties": {
      "forceUpdateTag": "[parameters('forceUpdateTag')]",
      "azPowerShellVersion": "10.1",
      "retentionInterval": "P1D"
    }
  },
  "resources": {
    "escapingTest": {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "escapingTest",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": "[union(variables('deploymentScriptSharedProperties'), createObject('scriptContent', '$DeploymentScriptOutputs = @{}; $DeploymentScriptOutputs.escaped = \"de''f\";'))]"
    }
  },
  "outputs": {
    "scriptOutput": {
      "type": "string",
      "value": "[reference('escapingTest').outputs.escaped]"
    }
  }
}

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "demoParam1": {
      "type": "string",
      "defaultValue": "[[test value]"
    }
  },
  "resources": [],
  "outputs": {
    "exampleOutput": {
      "type": "string",
      "value": "[parameters('demoParam1')]"
    }
  }
}

إذا كنت تستخدم القيمة الافتراضية، فسيقوم القالب بإرجاع [test value].

ومع ذلك، إذا قمت بتمرير قيمة معلمة عبر سطر الأوامر، فسيتم تفسير الأحرف حرفياً. نشر النموذج السابق مع:

New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[[test value]"

يُرجِع [[test value]. بدلاً من ذلك، استخدم:

New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[test value]"

ينطبق نفس التنسيق عند تمرير القيم من ملف معلمة. يتم تفسير الشخصيات حرفيا. عند استخدامه مع النموذج السابق، يقوم ملف المعلمة التالي بإرجاع [test value]:

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

القيم الفارغة

لتعيين خاصية إلى قيمة خالية، يمكنك استخدام ⁧null⁩ أو ⁧[json('null')]⁩. تعرض دالة json كائناً فارغاً عندما تقوم بتوفير null كمعامل. في كلتا الحالتين، تعامل قوالب Azure Resource Manager كما لو كانت الخاصية غير موجودة.

"stringValue": null,
"objectValue": "[json('null')]"

لإزالة عنصر بالكامل، يمكنك استخدام دالة filter(). على سبيل المثال:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "deployCaboodle": {
      "type": "bool",
      "defaultValue": false
    }
  },
  "variables": {
    "op": [
      {
        "name": "ODB"
      },
      {
        "name": "ODBRPT"
      },
      {
        "name": "Caboodle"
      }
    ]
  },
  "resources": [],
  "outputs": {
    "backendAddressPools": {
      "type": "array",
      "value": "[if(parameters('deployCaboodle'), variables('op'), filter(variables('op'), lambda('on', not(equals(lambdaVariables('on').name, 'Caboodle')))))]"
    }
  }
}

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