Sintaks dan ekspresi dalam templat ARM

  • Artikel

Sintaks dasar templat Azure Resource Manager (templat ARM) adalah JavaScript Object Notation (JSON). Namun, Anda dapat menggunakan ekspresi untuk memperluas nilai JSON yang tersedia dalam templat. Ekspresi dimulai dan diakhiri dengan tanda kurung siku: [ dan ]. Nilai ekspresi dievaluasi saat templat disebarkan. Ekspresi dapat menampilkan string, bilangan bulat, boolean, array, atau objek.

Panjang ekspresi templat tidak boleh melebihi 24.576 karakter.

Gunakan fungsi

Azure Resource Manager menyediakan fungsi yang bisa Anda gunakan dalam templat. Contoh berikut menunjukkan ekspresi yang menggunakan fungsi dalam nilai default parameter:

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

Dalam ekspresi tersebut, sintaks resourceGroup() memanggil salah satu fungsi yang disediakan Azure Resource Manager untuk digunakan dalam templat. Dalam hal ini, fungsi yang dipanggil adalah resourceGroup. Sama seperti di JavaScript, panggilan fungsi diformat sebagai functionName(arg1,arg2,arg3). Sintaks .location mengambil satu properti dari objek yang ditampilkan oleh fungsi tersebut.

Fungsi templat dan parameternya tidak peka huruf besar/kecil. Misalnya, Azure Resource Manager menyatakan variables('var1') dan VARIABLES('VAR1') sebagai hal yang sama. Saat dievaluasi, kecuali fungsi secara jelas memodifikasi kasus (seperti toUpper atau toLower), fungsi akan mempertahankan kasusnya. Jenis sumber daya tertentu mungkin memiliki persyaratan kasus yang terpisah dari bagaimana fungsi dievaluasi.

Untuk menjadikan suatu nilai string sebagai parameter ke suatu fungsi, gunakan tanda kutip tunggal.

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

Sebagian besar fungsi berfungsi sama baik disebarkan ke grup sumber daya, langganan, grup manajemen, atau penyewa. Fungsi berikut memiliki batasan berdasarkan cakupan:

  • resourceGroup - hanya dapat digunakan dalam penyebaran ke grup sumber daya.
  • resourceId - dapat digunakan pada cakupan apa pun, tetapi parameter yang valid berubah tergantung cakupannya.
  • subscription - hanya dapat digunakan dalam penyebaran ke grup sumber daya atau langganan.

Karakter escape

Agar string literal dimulai dengan tanda kurung siku kiri [ dan diakhiri dengan kurung siku kanan ], tetapi tidak menginterpretasikannya sebagai ekspresi, berikan braket tambahan untuk memulai string dengan [[. Misalnya, variabel:

"demoVar1": "[[test value]"

Menjadi [test value].

Namun, jika string literal tidak berakhir dengan tanda kurung, jangan hilangkan tanda kurung yang mengawalinya. Misalnya, variabel:

"demoVar2": "[test] value"

Menjadi [test] value.

Untuk menghindari tanda kutip ganda dalam ekspresi, seperti menambahkan objek JSON dalam templat, gunakan garis miring.

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

Untuk menghindari tanda kutip tunggal dalam output ekspresi ARM, gandakan tanda kutip tunggal. Output templat berikut menghasilkan nilai {"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''')]"
    }
  }
}

Dalam definisi sumber daya, nilai escape ganda dalam ekspresi. Dari scriptOutput templat berikut adalah 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]"
    }
  }
}

Dengan languageVersion 2.0, pelarian ganda diperlukan lebih lama. Contoh sebelumnya dapat ditulis sebagai JSON berikut untuk mendapatkan hasil yang sama, 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]"
    }
  }
}

Saat meneruskan nilai parameter, penggunaan karakter escape bergantung pada di mana nilai parameter ditentukan. Jika Anda menetapkan nilai default dalam templat, Anda memerlukan kurung siku kiri tambahan.

{
  "$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')]"
    }
  }
}

Jika Anda menggunakan nilai default, templat akan menampilkan [test value].

Namun, jika Anda meneruskan nilai parameter melalui baris perintah, karakter ditafsirkan secara literal. Menyebarkan templat sebelumnya dengan:

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

Menampilkan [[test value]. Sebagai gantinya, gunakan:

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

Pemformatan yang sama berlaku saat meneruskan nilai dari file parameter. Karakter ditafsirkan secara literal. Saat digunakan dengan templat sebelumnya, file parameter berikut menampilkan [test value]:

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

Nilai null

Untuk menetapkan properti menjadi null, Anda bisa menggunakan null atau [json('null')]. Fungsi json menampilkan objek kosong saat Anda memberikan null sebagai parameter. Dalam kedua kasus, templat Azure Resource Manager memperlakukannya seolah-olah propertinya tidak ada.

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

Untuk menghapus elemen sepenuhnya, Anda dapat menggunakan fungsi filter(). Contohnya:

{
  "$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')))))]"
    }
  }
}

Langkah berikutnya