Udostępnij za pośrednictwem

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

  • Artykuł

Podstawowa składnia szablonu usługi Azure Resource Manager (szablon 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 usługa Resource Manager udostępnia 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). Składnia .location pobiera jedną właściwość z obiektu zwróconego przez tę funkcję.

Funkcje szablonu i ich parametry są bez uwzględniania wielkości liter. Na przykład usługa Resource Manager rozwiązuje variables('var1') problem i VARIABLES('VAR1') jest taki sam. Po ocenie, chyba że funkcja wyraźnie modyfikuje przypadek (np 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 cudzysłowów pojedynczych.

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

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

  • resourceGroup — może być używana 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że być używana tylko we wdrożeniach w grupie zasobów lub subskrypcji.

Znaki ucieczki

Aby ciąg literału zaczynał się od lewego nawiasu i [ kończy się nawiasem prawym ], 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ójnego cudzysłowu w wyrażeniu, takim 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, podwaja 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. Element scriptOutput z poniższego szablonu 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 przypadku wersji languageVersion 2.0 podwójna ucieczka jest dłużej 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].

Jeśli jednak przekażesz wartość 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 szablony usługi Resource Manager traktują je 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