Een Resource Manager-parameterbestand maken

Artikel
03/20/2024

In plaats van parameters door te geven als inlinewaarden in uw script, kunt u een JSON-bestand gebruiken dat de parameterwaarden bevat. In dit artikel wordt beschreven hoe u een parameterbestand maakt dat u gebruikt met een JSON-sjabloon.

Tip

We raden Bicep aan omdat het dezelfde mogelijkheden biedt als ARM-sjablonen en de syntaxis eenvoudiger te gebruiken is. Zie parameterbestanden voor meer informatie.

Parameterbestand

Een parameterbestand gebruikt de volgende indeling:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

Het is vermeldenswaardig dat het parameterbestand parameterwaarden opslaat als tekst zonder opmaak. Om veiligheidsredenen wordt deze methode niet aanbevolen voor gevoelige waarden, zoals wachtwoorden. Als u een parameter met een gevoelige waarde moet doorgeven, bewaart u de waarde in een sleutelkluis. Neem vervolgens in het parameterbestand een verwijzing naar de sleutelkluis op. Tijdens de implementatie wordt de gevoelige waarde veilig opgehaald. Zie Azure Key Vault gebruiken om een beveiligde parameterwaarde door te geven tijdens de implementatie voor meer informatie.

Het volgende parameterbestand bevat een waarde voor tekst zonder opmaak en een gevoelige waarde die is opgeslagen in een sleutelkluis.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "reference": {
        "keyVault": {
          "id": "<resource-id-key-vault>"
        },
        "secretName": "<secret-name>"
      }
    }
  }
}

Zie Azure Key Vault gebruiken om een beveiligde parameterwaarde door te geven tijdens de implementatie voor meer informatie over het gebruik van waarden uit een sleutelkluis.

Parameterwaarden definiëren

Als u wilt bepalen hoe u de parameternamen en -waarden definieert, opent u uw JSON-sjabloon en bekijkt u de parameters sectie. In het volgende voorbeeld ziet u de parameters van de JSON-sjabloon.

"parameters": {
  "storagePrefix": {
    "type": "string",
    "maxLength": 11
  },
  "storageAccountType": {
    "type": "string",
    "defaultValue": "Standard_LRS",
    "allowedValues": [
    "Standard_LRS",
    "Standard_GRS",
    "Standard_ZRS",
    "Premium_LRS"
    ]
  }
}

In het parameterbestand ziet u als eerste de naam van elke parameter. De parameternamen in het parameterbestand moeten overeenkomen met de parameternamen in uw sjabloon.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

Let op het parametertype. De parametertypen in het parameterbestand moeten dezelfde typen gebruiken als de sjabloon. In dit voorbeeld zijn beide parametertypen tekenreeksen.

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

Controleer de sjabloon op parameters met een standaardwaarde. Als een parameter een standaardwaarde heeft, kunt u een waarde opgeven in het parameterbestand, maar dit is niet vereist. De waarde van het parameterbestand overschrijft de standaardwaarde van de sjabloon.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Template will use default value if not provided.
    }
  }
}

Controleer de toegestane waarden van de sjabloon en eventuele beperkingen, zoals de maximale lengte. Met deze waarden wordt het bereik van waarden opgegeven dat u kunt opgeven voor een parameter. In dit voorbeeld storagePrefix kan uit maximaal 11 tekens bestaan en storageAccountType moet een toegestane waarde worden opgegeven.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

Notitie

Het parameterbestand kan alleen waarden bevatten voor parameters die zijn gedefinieerd in de sjabloon. Als uw parameterbestand extra parameters bevat die niet overeenkomen met de parameters van de sjabloon, ontvangt u een foutmelding.

Parametertype-indelingen

In het volgende voorbeeld ziet u de indelingen van verschillende parametertypen: tekenreeks, geheel getal, booleaanse waarde, matrix en object.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

Sjabloon implementeren met parameterbestand

Vanuit Azure CLI geeft u een lokaal parameterbestand door met behulp van @ en de naam van het parameterbestand. Bijvoorbeeld @storage.parameters.json.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters @storage.parameters.json

Zie Resources implementeren met ARM-sjablonen en Azure CLI voor meer informatie.

Vanuit Azure PowerShell geeft u een lokaal parameterbestand door met behulp van de TemplateParameterFile parameter .

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.json `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json

Zie Resources implementeren met ARM-sjablonen en Azure PowerShell voor meer informatie.

Notitie

Het is niet mogelijk om een parameterbestand te gebruiken met de blade aangepaste sjabloon in de portal.

Tip

Als u het Azure-resourcegroepproject in Visual Studio gebruikt, moet u ervoor zorgen dat de buildactie van het parameterbestand is ingesteld op Inhoud.

Bestandsnaam

De algemene naamconventie voor het parameterbestand is om parameters op te nemen in de sjabloonnaam. Als uw sjabloon bijvoorbeeld de naam azuredeploy.json heeft, heeft het parameterbestand de naam azuredeploy.parameters.json. Met deze naamconventie kunt u de verbinding tussen de sjabloon en de parameters zien.

Als u wilt implementeren in verschillende omgevingen, maakt u meer dan één parameterbestand. Wanneer u de parameterbestanden een naam geeft, identificeert u het gebruik ervan, zoals ontwikkeling en productie. Gebruik bijvoorbeeld azuredeploy.parameters-dev.json en azuredeploy.parameters-prod.json om resources te implementeren.

Parameterprioriteit

U kunt inlineparameters en een lokaal parameterbestand gebruiken in dezelfde implementatiebewerking. U kunt bijvoorbeeld enkele waarden opgeven in het lokale parameterbestand en andere waarden inline toevoegen tijdens de implementatie. Als u waarden opgeeft voor een parameter in zowel het lokale parameterbestand als inline, heeft de inlinewaarde voorrang.

Het is mogelijk om een extern parameterbestand te gebruiken door de URI aan het bestand op te geven. Wanneer u een extern parameterbestand gebruikt, kunt u geen andere waarden inline of vanuit een lokaal bestand doorgeven. Alle inlineparameters worden genegeerd. Geef alle parameterwaarden op in het externe bestand.

Parameternaamconflicten

Als uw sjabloon een parameter bevat met dezelfde naam als een van de parameters in de PowerShell-opdracht, geeft PowerShell de parameter uit uw sjabloon weer met het navoegsel FromTemplate. Een parameter met de naam ResourceGroupName in uw sjabloon is bijvoorbeeld een conflict met de ResourceGroupName parameter in de cmdlet New-AzResourceGroupDeployment . U wordt gevraagd om een waarde op te geven voor ResourceGroupNameFromTemplate. Om deze verwarring te voorkomen, gebruikt u parameternamen die niet worden gebruikt voor implementatieopdrachten.

Volgende stappen

Zie Parameters in ARM-sjablonen voor meer informatie over het definiëren van parameters in een sjabloon.
Zie Azure Key Vault gebruiken om een beveiligde parameterwaarde door te geven tijdens de implementatie voor meer informatie over het gebruik van waarden uit een sleutelkluis.