Składnia i wyrażenia w szablonach usługi ARM

  • Artykuł

Podstawowa składnia szablonu usługi Azure Resource Manager (szablon usługi ARM) to JavaScript Object Notation (JSON). Można jednak użyć wyrażeń, aby rozszerzyć wartości JSON dostępne w szablonie. Wyrażenia zaczynają się i kończą nawiasami kwadratowymi: odpowiednio [ i ]. Wartość wyrażenia jest obliczana podczas wdrażania szablonu. Wyrażenie może zwrócić ciąg, liczbę całkowitą, wartość logiczną, tablicę lub obiekt.

Wyrażenie szablonu nie może przekraczać 24 576 znaków.

Korzystanie z funkcji

Usługa Azure Resource Manager udostępnia funkcje, których można używać w szablonie. W poniższym przykładzie pokazano wyrażenie, które używa funkcji w wartości domyślnej parametru:

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

W wyrażeniu składnia resourceGroup() wywołuje jedną z funkcji, które Resource Manager zapewnia do użycia w szablonie. W tym przypadku jest to funkcja resourceGroup . Podobnie jak w języku JavaScript wywołania funkcji są formatowane jako functionName(arg1,arg2,arg3). .location Składnia pobiera jedną właściwość z obiektu zwróconego przez tę funkcję.

Funkcje szablonu i ich parametry są niewrażliwe na wielkość liter. Na przykład Resource Manager rozwiązuje variables('var1') problemy i VARIABLES('VAR1') są takie same. Podczas oceny, chyba że funkcja wyraźnie modyfikuje przypadek (na przykład toUpper lub toLower), funkcja zachowuje wielkość liter. Niektóre typy zasobów mogą mieć wymagania dotyczące wielkości liter, które są oddzielone od sposobu oceniania funkcji.

Aby przekazać wartość ciągu jako parametr do funkcji, użyj apostrofów.

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

Większość funkcji działa tak samo, niezależnie od tego, czy są one wdrażane w grupie zasobów, subskrypcji, grupie zarządzania lub dzierżawie. Następujące funkcje mają ograniczenia na podstawie zakresu:

  • resourceGroup — można jej używać tylko we wdrożeniach w grupie zasobów.
  • resourceId — może być używany w dowolnym zakresie, ale prawidłowe parametry zmieniają się w zależności od zakresu.
  • subskrypcja — można jej używać tylko we wdrożeniach w grupie zasobów lub subskrypcji.

Znaki ucieczki

Aby ciąg literału rozpoczynał się od lewego nawiasu i [ kończy się prawym nawiasem kwadratowym ], ale nie został zinterpretowany jako wyrażenie, dodaj dodatkowy nawias, aby rozpocząć ciąg za pomocą [[. Na przykład zmienna:

"demoVar1": "[[test value]"

Jest rozpoznawana jako [test value].

Jeśli jednak ciąg literału nie kończy się nawiasem kwadratowym, nie należy unikać pierwszego nawiasu. Na przykład zmienna:

"demoVar2": "[test] value"

Jest rozpoznawana jako [test] value.

Aby uniknąć podwójnych cudzysłowów w wyrażeniu, takich jak dodanie obiektu JSON w szablonie, użyj ukośnika odwrotnego.

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

Aby uniknąć pojedynczych cudzysłowów w danych wyjściowych wyrażenia arm, podwajaj pojedyncze cudzysłowy. Dane wyjściowe następującego szablonu zawierają wartość {"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''')]"
    }
  }
}

W definicji zasobu wartości podwójnej ucieczki w wyrażeniu. Poniższy scriptOutput szablon to 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]"
    }
  }
}

W wersji languageVersion 2.0 podwójna ucieczka jest już potrzebna. Powyższy przykład można napisać jako następujący kod JSON, aby uzyskać ten sam wynik: 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]"
    }
  }
}

Podczas przekazywania wartości parametrów użycie znaków ucieczki zależy od tego, gdzie określono wartość parametru. Jeśli ustawisz wartość domyślną w szablonie, potrzebujesz dodatkowego lewego nawiasu.

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

Jeśli używasz wartości domyślnej, szablon zwraca wartość [test value].

Jednak w przypadku przekazania wartości parametru za pośrednictwem wiersza polecenia znaki są interpretowane dosłownie. Wdrażanie poprzedniego szablonu przy użyciu:

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

Zwraca wartość [[test value]. Zamiast tego należy:

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

To samo formatowanie ma zastosowanie podczas przekazywania wartości z pliku parametrów. Znaki są interpretowane dosłownie. W przypadku użycia z poprzednim szablonem następujący plik parametrów zwraca wartość [test value]:

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

Wartości null

Aby ustawić dla właściwości wartość null, można wpisać null lub [json('null')]. Funkcja JSON zwraca pusty obiekt po podaniu null jako parametru. W obu przypadkach Resource Manager szablony traktują go tak, jakby właściwość nie była obecna.

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

Aby całkowicie usunąć element, możesz użyć funkcji filter(). Na przykład:

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

Następne kroki