Informatie over de structuur en de syntaxis van ARM-sjablonen

In dit artikel wordt de structuur van een Azure Resource Manager sjabloon (ARM-sjabloon) beschreven. Deze bevat de verschillende secties van een sjabloon en de eigenschappen die beschikbaar zijn in deze secties.

Dit artikel is bedoeld voor gebruikers die enige kennis hebben van ARM-sjablonen. Het biedt gedetailleerde informatie over de structuur van de sjabloon. Zie Zelfstudie: Uw eerste ARM-sjabloon maken en implementeren voor een stapsgewijs zelfstudie die u door het proces van het maken van een sjabloon leidt. Raadpleeg Resources implementeren en beheren in Azure met behulp van ARM-sjablonen voor meer informatie over ARM-sjablonen via een begeleide set modules.

Sjabloonindeling

In de eenvoudigste structuur heeft een sjabloon de volgende elementen:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}
Elementnaam Vereist Beschrijving
$schema Yes Locatie van het JavaScript Object Notation (JSON)-schemabestand dat de versie van de sjabloontaal beschrijft. Het versienummer dat u gebruikt, is afhankelijk van het bereik van de implementatie en uw JSON-editor.

Als u code gebruikt Visual Studio de extensie Azure Resource Manager hulpprogramma's, gebruikt u de nieuwste versie voor resourcegroepimplementaties:
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

Andere editors (inclusief Visual Studio) kunnen dit schema mogelijk niet verwerken. Gebruik voor deze editors:
https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

Gebruik voor abonnementsimplementaties:
https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#

Voor implementaties van beheergroep gebruikt u:
https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#

Gebruik voor tenantimplementaties:
https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#
contentVersion Yes Versie van de sjabloon (zoals 1.0.0.0). U kunt een willekeurige waarde voor dit element opgeven. Gebruik deze waarde als u belangrijke wijzigingen in uw sjabloon wilt documenteren. Wanneer u resources implementeert met de sjabloon, kan deze waarde worden gebruikt om ervoor te zorgen dat de juiste sjabloon wordt gebruikt.
apiProfile No Een API-versie die fungeert als een verzameling API-versies voor resourcetypen. Gebruik deze waarde om te voorkomen dat u API-versies voor elke resource in de sjabloon moet opgeven. Wanneer u een API-profielversie opgeeft en geen API-versie opgeeft voor het resourcetype, gebruikt Resource Manager de API-versie voor dat resourcetype dat in het profiel is gedefinieerd.

De eigenschap API-profiel is vooral nuttig bij het implementeren van een sjabloon in verschillende omgevingen, Azure Stack en globale Azure. Gebruik de API-profielversie om ervoor te zorgen dat uw sjabloon automatisch versies gebruikt die in beide omgevingen worden ondersteund. Zie API-profiel voor een lijst met de huidige API-profielversies en de API-versies van de resources die in het profiel zijn gedefinieerd.

Zie Versies bijhouden met API-profielen voor meer informatie.
Parameters No Waarden die worden opgegeven wanneer de implementatie wordt uitgevoerd om resource-implementatie aan te passen.
Variabelen No Waarden die worden gebruikt als JSON-fragmenten in de sjabloon om sjabloontaalexpressie te vereenvoudigen.
Functies No Door de gebruiker gedefinieerde functies die beschikbaar zijn in de sjabloon.
Middelen Yes Resourcetypen die worden geïmplementeerd of bijgewerkt in een resourcegroep of abonnement.
Uitgangen No Waarden die worden geretourneerd na de implementatie.

Elk element heeft eigenschappen die u kunt instellen. In dit artikel worden de secties van de sjabloon uitgebreider beschreven.

Parameters

In de parameters sectie van de sjabloon geeft u op welke waarden u kunt invoeren bij het implementeren van de resources. U kunt maximaal 256 parameters opgeven in een sjabloon. U kunt het aantal parameters verminderen met behulp van objecten die meerdere eigenschappen bevatten.

De eigenschappen die beschikbaar zijn voor een parameter zijn:

"parameters": {
  "<parameter-name>" : {
    "type" : "<type-of-parameter-value>",
    "defaultValue": "<default-value-of-parameter>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array-parameters>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}
Elementnaam Vereist Beschrijving
parameternaam Yes Naam van de parameter. Moet een geldige JavaScript-id zijn.
type Yes Type parameterwaarde. De toegestane typen en waarden zijn tekenreeks, securestring, int, bool, object, secureObject en matrix. Zie Gegevenstypen in ARM-sjablonen.
Standaardwaarde No Standaardwaarde voor de parameter, als er geen waarde is opgegeven voor de parameter.
allowedValues No Matrix met toegestane waarden voor de parameter om ervoor te zorgen dat de juiste waarde wordt opgegeven.
minValue No De minimumwaarde voor int-typeparameters. Deze waarde is inclusief.
maxValue No De maximumwaarde voor int-typeparameters. Deze waarde is inclusief.
minLength No De minimale lengte voor tekenreeks-, veilige tekenreeks- en matrixtypeparameters. Deze waarde is inclusief.
Maxlength No De maximale lengte voor tekenreeks-, veilige tekenreeks- en matrixtypeparameters. Deze waarde is inclusief.
beschrijving No Beschrijving van de parameter die wordt weergegeven voor gebruikers via de portal. Zie Opmerkingen in sjablonen voor meer informatie.

Zie Parameters in ARM-sjablonen voor voorbeelden van het gebruik van parameters.

Variabelen

In de variables sectie maakt u waarden die in de sjabloon kunnen worden gebruikt. U hoeft geen variabelen te definiëren, maar ze vereenvoudigen vaak uw sjabloon door complexe expressies te verminderen. De indeling van elke variabele komt overeen met een van de gegevenstypen.

In het volgende voorbeeld ziet u de beschikbare opties voor het definiëren van een variabele:

"variables": {
  "<variable-name>": "<variable-value>",
  "<variable-name>": {
    <variable-complex-type-value>
  },
  "<variable-object-name>": {
    "copy": [
      {
        "name": "<name-of-array-property>",
        "count": <number-of-iterations>,
        "input": <object-or-value-to-repeat>
      }
    ]
  },
  "copy": [
    {
      "name": "<variable-array-name>",
      "count": <number-of-iterations>,
      "input": <object-or-value-to-repeat>
    }
  ]
}

Zie Variabele iteratie voor meer informatie over het maken van verschillende waarden copy voor een variabele.

Zie Variabelen in ARM-sjabloon voor voorbeelden van het gebruik van variabelen.

Functions

In uw sjabloon kunt u uw eigen functies maken. Deze functies zijn beschikbaar voor gebruik in uw sjabloon. Normaal gesproken definieert u gecompliceerde expressies die u niet in de sjabloon wilt herhalen. U maakt de door de gebruiker gedefinieerde functies op basis van expressies en functies die worden ondersteund in sjablonen.

Bij het definiëren van een gebruikersfunctie gelden enkele beperkingen:

  • De functie heeft geen toegang tot variabelen.
  • De functie kan alleen parameters gebruiken die in de functie zijn gedefinieerd. Wanneer u de functie parameters in een door de gebruiker gedefinieerde functie gebruikt, bent u beperkt tot de parameters voor die functie.
  • De functie kan geen andere door de gebruiker gedefinieerde functies aanroepen.
  • De functie kan de verwijzingsfunctie niet gebruiken.
  • Parameters voor de functie kunnen geen standaardwaarden hebben.
"functions": [
  {
    "namespace": "<namespace-for-functions>",
    "members": {
      "<function-name>": {
        "parameters": [
          {
            "name": "<parameter-name>",
            "type": "<type-of-parameter-value>"
          }
        ],
        "output": {
          "type": "<type-of-output-value>",
          "value": "<function-return-value>"
        }
      }
    }
  }
],
Elementnaam Vereist Beschrijving
naamruimte Yes Naamruimte voor de aangepaste functies. Gebruik om naamconflicten met sjabloonfuncties te voorkomen.
function-name Yes Naam van de aangepaste functie. Wanneer u de functie aanroept, combineert u de functienaam met de naamruimte . Als u bijvoorbeeld een functie met de naam uniqueName in de naamruimte contoso wilt aanroepen, gebruikt u "[contoso.uniqueName()]" .
parameternaam No Naam van de parameter die moet worden gebruikt in de aangepaste functie.
parameter-value No Type parameterwaarde. De toegestane typen en waarden zijn tekenreeks, securestring, int, bool, object, secureObject en matrix.
output-type Yes Type van de uitvoerwaarde. Uitvoerwaarden ondersteunen dezelfde typen als functie-invoerparameters.
output-value Yes Sjabloontaalexpressie die wordt geëvalueerd en geretourneerd door de functie.

Zie Door de gebruiker gedefinieerde functies in ARM-sjabloonvoor voorbeelden van het gebruik van aangepaste functies.

Resources

In de resources sectie definieert u de resources die worden geïmplementeerd of bijgewerkt.

U definieert resources met de volgende structuur:

"resources": [
  {
      "condition": "<true-to-deploy-this-resource>",
      "type": "<resource-provider-namespace/resource-type-name>",
      "apiVersion": "<api-version-of-resource>",
      "name": "<name-of-the-resource>",
      "comments": "<your-reference-notes>",
      "location": "<location-of-resource>",
      "dependsOn": [
          "<array-of-related-resource-names>"
      ],
      "tags": {
          "<tag-name1>": "<tag-value1>",
          "<tag-name2>": "<tag-value2>"
      },
      "identity": {
        "type": "<system-assigned-or-user-assigned-identity>",
        "userAssignedIdentities": {
          "<resource-id-of-identity>": {}
        }
      },
      "sku": {
          "name": "<sku-name>",
          "tier": "<sku-tier>",
          "size": "<sku-size>",
          "family": "<sku-family>",
          "capacity": <sku-capacity>
      },
      "kind": "<type-of-resource>",
      "scope": "<target-scope-for-extension-resources>",
      "copy": {
          "name": "<name-of-copy-loop>",
          "count": <number-of-iterations>,
          "mode": "<serial-or-parallel>",
          "batchSize": <number-to-deploy-serially>
      },
      "plan": {
          "name": "<plan-name>",
          "promotionCode": "<plan-promotion-code>",
          "publisher": "<plan-publisher>",
          "product": "<plan-product>",
          "version": "<plan-version>"
      },
      "properties": {
          "<settings-for-the-resource>",
          "copy": [
              {
                  "name": ,
                  "count": ,
                  "input": {}
              }
          ]
      },
      "resources": [
          "<array-of-child-resources>"
      ]
  }
]
Elementnaam Vereist Beschrijving
Voorwaarde No Booleaanse waarde die aangeeft of de resource tijdens deze implementatie wordt ingericht. Wanneer true , wordt de resource gemaakt tijdens de implementatie. Wanneer false wordt de resource overgeslagen voor deze implementatie. Zie voorwaarde.
type Yes Type resource. Deze waarde is een combinatie van de naamruimte van de resourceprovider en het resourcetype (zoals Microsoft.Storage/storageAccounts ). Zie sjabloonverwijzing om de beschikbare waarden te bepalen. Voor een onderliggende resource is de indeling van het type afhankelijk van of deze is genest binnen de bovenliggende resource of buiten de bovenliggende resource is gedefinieerd. Zie Setnaam en -type voor onderliggende resources.
apiVersion Yes De versie van de REST API te gebruiken voor het maken van de resource. Wanneer u een nieuwe sjabloon maakt, stelt u deze waarde in op de nieuwste versie van de resource die u implementeert. Gebruik dezelfde API-versie zolang de sjabloon naar behoefte werkt. Door dezelfde API-versie te blijven gebruiken, minimaliseert u het risico dat een nieuwe API-versie de manier verandert waarop uw sjabloon werkt. Overweeg de API-versie alleen bij te werken als u een nieuwe functie wilt gebruiken die in een latere versie wordt geïntroduceerd. Zie sjabloonverwijzing om de beschikbare waarden te bepalen.
naam Yes De naam van de resource. De naam moet de URI-onderdeelbeperkingen volgen die zijn gedefinieerd in RFC3986. Azure-services die de resourcenaam beschikbaar maken voor externe partijen valideren de naam om er zeker van te zijn dat er niet wordt geprobeerd een andere identiteit te vervalsen. Voor een onderliggende resource is de indeling van de naam afhankelijk van of deze is genest in de bovenliggende resource of buiten de bovenliggende resource is gedefinieerd. Zie Setnaam en -type voor onderliggende resources.
opmerkingen No Uw notities voor het documenteren van de resources in uw sjabloon. Zie Opmerkingen in sjablonen voor meer informatie.
location Varieert Ondersteunde geografische locaties van de opgegeven resource. U kunt een van de beschikbare locaties selecteren, maar het is doorgaans zinvol om er een te kiezen die zich dicht bij uw gebruikers bevinden. Meestal is het ook zinvol om resources die met elkaar communiceren in dezelfde regio te plaatsen. Voor de meeste resourcetypen is een locatie vereist, maar voor sommige typen (zoals een roltoewijzing) is geen locatie vereist. Zie Resourcelocatie instellen.
dependsOn No Resources die moeten worden geïmplementeerd voordat deze resource wordt geïmplementeerd. Resource Manager evalueert de afhankelijkheden tussen resources en implementeert deze in de juiste volgorde. Wanneer resources niet van elkaar afhankelijk zijn, worden ze parallel geïmplementeerd. De waarde kan een door komma's gescheiden lijst met resourcenamen of unieke resource-id's zijn. Vermeld alleen resources die in deze sjabloon zijn geïmplementeerd. Resources die niet in deze sjabloon zijn gedefinieerd, moeten al bestaan. Vermijd het toevoegen van onnodige afhankelijkheden, omdat deze uw implementatie kunnen vertragen en kringafhankelijkheden kunnen maken. Zie De volgorde voor het implementeren van resources in ARM-sjablonen definiëren voor hulp bij het instellen van afhankelijkheden.
tags No Tags die zijn gekoppeld aan de resource. Tags toepassen om resources logisch te organiseren in uw abonnement.
identity No Sommige resources ondersteunen beheerde identiteiten voor Azure-resources. Deze resources hebben een identiteitsobject op het hoofdniveau van de resourcedeclaratie. U kunt instellen of de identiteit door de gebruiker of door het systeem is toegewezen. Geef voor door de gebruiker toegewezen identiteiten een lijst met resource-id's op voor de identiteiten. Stel de sleutel in op de resource-id en de waarde op een leeg object. Zie Beheerde identiteiten configureren voor Azure-resources op een Azure-VM met behulp van sjablonen voor meer informatie.
sku No Sommige resources staan waarden toe die de implementatie van de SKU definiëren. U kunt bijvoorbeeld het type redundantie voor een opslagaccount opgeven.
Soort No Sommige resources staan een waarde toe die het type resource definieert dat u implementeert. U kunt bijvoorbeeld het type maken Cosmos DB opgeven.
scope No De eigenschap scope is alleen beschikbaar voor resourcetypen voor extensies. Gebruik het bij het opgeven van een bereik dat verschilt van het implementatiebereik. Zie Instellingsbereik voor extensiebronnen in ARM-sjablonen.
kopiëren No Als er meer dan één exemplaar nodig is, het aantal resources dat moet worden maken. De standaardmodus is parallel. Geef de seriële modus op wanneer u niet wilt dat alle resources of de resources tegelijkertijd worden geïmplementeerd. Zie Create several instances of resources in Azure Resource Manager( Meerdere exemplaren van resources maken in Azure Resource Manager.
plannen No Sommige resources staan waarden toe waarmee het plan voor implementatie wordt bepaald. U kunt bijvoorbeeld de Marketplace-afbeelding voor een virtuele machine opgeven.
properties No Resourcespecifieke configuratie-instellingen. De waarden voor de eigenschappen zijn hetzelfde als de waarden die u op geeft in de aanvraag body voor de REST API bewerking (PUT-methode) om de resource te maken. U kunt ook een kopieer matrix opgeven om verschillende exemplaren van een eigenschap te maken. Zie sjabloonverwijzing om beschikbare waarden te bepalen.
resources No Onderliggende resources die afhankelijk zijn van de resource die wordt gedefinieerd. Geef alleen resourcetypen op die zijn toegestaan door het schema van de bovenliggende resource. Afhankelijkheid van de bovenliggende resource wordt niet geïmpliceerd. U moet die afhankelijkheid expliciet definiëren. Zie Setnaam en -type voor onderliggende resources.

Uitvoerwaarden

In de outputs sectie geeft u waarden op die worden geretourneerd door de implementatie. Normaal gesproken retourneert u waarden van resources die zijn geïmplementeerd.

In het volgende voorbeeld ziet u de structuur van een uitvoerdefinitie:

"outputs": {
  "<output-name>": {
    "condition": "<boolean-value-whether-to-output-value>",
    "type": "<type-of-output-value>",
    "value": "<output-value-expression>",
    "copy": {
      "count": <number-of-iterations>,
      "input": <values-for-the-variable>
    }
  }
}
Elementnaam Vereist Beschrijving
output-name Yes Naam van de uitvoerwaarde. Moet een geldige JavaScript-id zijn.
Voorwaarde No Booleaanse waarde die aangeeft of deze uitvoerwaarde wordt geretourneerd. Wanneer true , wordt de waarde opgenomen in de uitvoer voor de implementatie. Wanneer false wordt de uitvoerwaarde overgeslagen voor deze implementatie. Wanneer deze niet is opgegeven, is de standaardwaarde true .
type Yes Type van de uitvoerwaarde. Uitvoerwaarden ondersteunen dezelfde typen als sjablooninvoerparameters. Als u securestring opgeeft voor het uitvoertype, wordt de waarde niet weergegeven in de implementatiegeschiedenis en kan deze niet worden opgehaald uit een andere sjabloon. Als u een geheime waarde in meer dan één sjabloon wilt gebruiken, moet u het geheim opslaan in een Key Vault en verwijzen naar het geheim in het parameterbestand. Zie Use Azure Key Vault to pass secure parameter value during deployment (Beveiligde parameterwaarde doorgeven tijdens de implementatie) voor meer informatie.
waarde No Sjabloontaalexpressie die wordt geëvalueerd en geretourneerd als uitvoerwaarde. Geef een waarde op of kopieer.
kopiëren No Wordt gebruikt om meer dan één waarde voor een uitvoer te retourneren. Geef waarde op of kopieer. Zie Uitvoer-iteratie in ARM-sjablonen voor meer informatie.

Zie Outputs in ARM template(Uitvoer in ARM-sjabloon) voor voorbeelden van het gebruik van uitvoer.

Opmerkingen en metagegevens

U hebt een aantal opties voor het toevoegen van opmerkingen en metagegevens aan uw sjabloon.

Opmerkingen

Voor inline-opmerkingen kunt u // of /* ... */ gebruiken.

Notitie

Wanneer u Azure CLI gebruikt om sjablonen met opmerkingen te implementeren, gebruikt u versie 2.3.0 of hoger en geeft u de --handle-extended-json-format switch op.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

In Visual Studio Code kan de extensie Azure Resource Manager Tools automatisch een ARM-sjabloon detecteren en de taalmodus wijzigen. Als u de sjabloon Azure Resource Manager in de rechteronderhoek van Visual Studio Code ziet, kunt u de inline-opmerkingen gebruiken. De inline opmerkingen worden niet meer gemarkeerd als ongeldig.

Visual Studio Code Azure Resource Manager sjabloonmodus

Metagegevens

U kunt een metadata object bijna overal in uw sjabloon toevoegen. Resource Manager object wordt genegeerd, maar uw JSON-editor kan u waarschuwen dat de eigenschap ongeldig is. Definieer in het -object de eigenschappen die u nodig hebt.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "comments": "This template was developed for demonstration purposes.",
    "author": "Example Name"
  },

Voeg parameters voor een metadata -object toe met een eigenschap description .

"parameters": {
  "adminUsername": {
    "type": "string",
    "metadata": {
      "description": "User name for the Virtual Machine."
    }
  },

Wanneer u de sjabloon via de portal implementeert, wordt de tekst die u in de beschrijving opgeeft automatisch gebruikt als tip voor die parameter.

Parametertip tonen

Voeg resources voor een comments -element of metadata -object toe. In het volgende voorbeeld ziet u zowel comments een -element als een metadata -object.

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2018-07-01",
    "name": "[concat('storage', uniqueString(resourceGroup().id))]",
    "comments": "Storage account used to store VM disks",
    "location": "[parameters('location')]",
    "metadata": {
      "comments": "These tags are needed for policy compliance."
    },
    "tags": {
      "Dept": "[parameters('deptName')]",
      "Environment": "[parameters('environment')]"
    },
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "properties": {}
  }
]

Voeg outputs voor een metadata -object toe aan de uitvoerwaarde.

"outputs": {
  "hostname": {
    "type": "string",
    "value": "[reference(variables('publicIPAddressName')).dnsSettings.fqdn]",
    "metadata": {
      "comments": "Return the fully qualified domain name"
    }
  },

U kunt geen metadata -object toevoegen aan door de gebruiker gedefinieerde functies.

Tekenreeksen met meerdere lijnen

U kunt een tekenreeks in meerdere regels ops breken. Zie bijvoorbeeld de eigenschap location en een van de opmerkingen in het volgende JSON-voorbeeld.

Notitie

Als u sjablonen met meerdere regelreeksen wilt implementeren, gebruikt u Azure PowerShell of Azure CLI. Gebruik voor CLI versie 2.3.0 of hoger en geef de --handle-extended-json-format switch op.

Meerdere regelreeksen worden niet ondersteund wanneer u de sjabloon implementeert via de Azure Portal, een DevOps-pijplijn of de REST API.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Volgende stappen

  • Zie de Azure-snelstartsjablonen voor volledige sjablonen voor verschillende soorten oplossingen.
  • Zie ARM-sjabloonfuncties voor meer informatie over de functies die u vanuit een sjabloon kunt gebruiken.
  • Zie Gekoppelde en geneste sjablonen gebruiken bij het implementeren van Azure-resourcesals u verschillende sjablonen wilt combineren tijdens de implementatie.
  • Zie aanbevolen procedures voor ARM-sjablonen voor aanbevelingen voor het maken van sjablonen.
  • Zie Veelgestelde vragen over ARM-sjablonen voor antwoorden op veelgestelde vragen.