Understand the structure and syntax of ARM templates (Compreender a estrutura e a sintaxe dos modelos do Resource Manager)

Este artigo descreve a estrutura de um modelo do Azure Resource Manager (modelo ARM). Ele apresenta as diferentes seções de um modelo e as propriedades que estão disponíveis nessas seções.

Este artigo destina-se a usuários que têm alguma familiaridade com modelos ARM. Ele fornece informações detalhadas sobre a estrutura do modelo. Para obter um tutorial passo a passo que o orienta pelo processo de criação de um modelo, consulte Tutorial: Criar e implantar seu primeiro modelo ARM. Para saber mais sobre modelos ARM por meio de um conjunto guiado de módulos do Learn, consulte Implantar e gerenciar recursos no Azure usando modelos ARM.

Formato de modelo

Em sua estrutura mais simples, um modelo tem os seguintes elementos:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "",
  "contentVersion": "",
  "apiProfile": "",
  "definitions": { },
  "parameters": { },
  "variables": { },
  "functions": [ ],
  "resources": [ ], /* or "resources": { } with languageVersion 2.0 */
  "outputs": { }
}

Cada elemento tem propriedades que você pode definir. Este artigo descreve as seções do modelo com mais detalhes.

Definições

definitions Na seção do modelo, especifique os esquemas usados para validar valores de matriz e objeto. Definitions só pode ser usado com languageVersion 2.0.

"definitions": {
  "<definition-name": {
    "type": "<data-type-of-definition>",
    "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>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the-type-definition>"
    }
  }
}

Para obter exemplos de como usar definições de tipo, consulte Definições de tipo em modelos ARM.

No Bicep, consulte Tipos de dados definidos pelo usuário.

Parâmetros

parameters Na seção do modelo, você especifica quais valores pode ser inserido ao implantar os recursos. Você está limitado a 256 parâmetros em um modelo. Você pode reduzir o número de parâmetros usando objetos que contêm várias propriedades.

As propriedades disponíveis para um parâmetro são:

"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>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}

Para obter exemplos de como usar parâmetros, consulte Parâmetros em modelos ARM.

No Bicep, consulte parâmetros.

Variáveis

Na seção , você constrói valores que podem ser usados em todo o variables modelo. Você não precisa definir variáveis, mas elas geralmente simplificam seu modelo reduzindo expressões complexas. O formato de cada variável corresponde a um dos tipos de dados. Você está limitado a 256 variáveis em um modelo.

O exemplo a seguir mostra as opções disponíveis para definir uma variável:

"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>
    }
  ]
}

Para obter informações sobre como usar copy para criar vários valores para uma variável, consulte Iteração de variáveis.

Para obter exemplos de como usar variáveis, consulte Variáveis no modelo ARM.

No Bicep, consulte variáveis.

Funções

Dentro do seu modelo, você pode criar suas próprias funções. Essas funções estão disponíveis para uso em seu modelo. Normalmente, você define expressões complicadas que não deseja repetir em todo o modelo. Você cria as funções definidas pelo usuário a partir de expressões e funções suportadas em modelos.

Ao definir uma função de usuário, existem algumas restrições:

• A função não pode acessar variáveis.
• A função só pode usar parâmetros que são definidos na função. Quando você usa a função de parâmetros dentro de uma função definida pelo usuário, você está restrito aos parâmetros para essa função.
• A função não pode chamar outras funções definidas pelo usuário.
• A função não pode usar a função de referência.
• Os parâmetros para a função não podem ter valores padrão.

"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>"
        }
      }
    }
  }
],

Para obter exemplos de como usar funções personalizadas, consulte Funções definidas pelo usuário no modelo ARM.

No Bicep, as funções definidas pelo usuário não são suportadas. Bicep suporta várias funções e operadores.

Recursos

resources Na seção , você define os recursos que são implantados ou atualizados. Você está limitado a 800 recursos em um modelo.

Você define recursos com a seguinte estrutura:

"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>"
    ]
  }
]

Para dar suporte ao nome simbólico do Bicep em modelos JSON ARM, adicione languageVersion com a versão 2.0 ou mais recente e altere a definição de recurso de uma matriz para um objeto.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Para obter mais informações, consulte Recursos.

No Bicep, consulte recursos.

Saídas

Na seção , você especifica os outputs valores que são retornados da implantação. Normalmente, você retorna valores de recursos que foram implantados. Você está limitado a 64 saídas em um modelo.

O exemplo a seguir mostra a estrutura de uma definição de saída:

"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>
    }
  }
}

Para obter exemplos de como usar saídas, consulte Saídas no modelo ARM.

No Bicep, consulte saídas.

Comentários e metadados

Você tem algumas opções para adicionar comentários e metadados ao seu modelo.

Comentários

Para comentários embutidos, você pode usar um // ou /* ... */. No Visual Studio Code, salve os arquivos de parâmetro com comentários como o tipo de arquivo JSON com comentários (JSONC), caso contrário, você receberá uma mensagem de erro dizendo "Comentários não permitidos em JSON".

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-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'))]"
  ],

No Visual Studio Code, a extensão Azure Resource Manager Tools pode detetar automaticamente um modelo ARM e alterar o modo de idioma. Se você vir Modelo do Azure Resource Manager no canto inferior direito do Visual Studio Code, poderá usar os comentários embutidos. Os comentários embutidos não são mais marcados como inválidos.

No Bicep, ver comentários.

Metadados

Você pode adicionar um metadata objeto em praticamente qualquer lugar em seu modelo. O Gerenciador de Recursos ignora o objeto, mas o editor JSON pode avisá-lo de que a propriedade não é válida. No objeto, defina as propriedades necessárias.

{
  "$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"
  },

Para parameters, adicione um metadata objeto com uma description propriedade.

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

Ao implantar o modelo através do portal, o texto fornecido na descrição é usado automaticamente como uma dica para esse parâmetro.

Para resources, adicione um comments elemento ou um metadata objeto. O exemplo a seguir mostra um comments elemento e um metadata objeto.

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2022-09-01",
    "name": "[format('{0}{1}', '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": {}
  }
]

Para outputs, adicione um metadata objeto ao valor de saída.

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

Não é possível adicionar um metadata objeto a funções definidas pelo usuário.

Strings de várias linhas

Você pode dividir uma cadeia de caracteres em várias linhas. Por exemplo, consulte a location propriedade e um dos comentários no exemplo JSON a seguir.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-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'))]"
  ],

No Bicep, consulte cadeias de caracteres de várias linhas.

languageVersão 2.0

Para usar languageVersion 2.0, adicione "languageVersion": "2.0" ao seu modelo:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Os aprimoramentos e alterações que vêm com languageVersion 2.0:

• Use o nome simbólico no modelo JSON ARM. Para obter mais informações, consulte Usar nome simbólico.
• Use o nome simbólico em loops de cópia de recursos. Consulte Usar nome simbólico.
• Use o nome simbólico em dependsOn matrizes. Consulte DependsOn e Depend on resources in a loop.
• Use o nome simbólico em vez do nome do recurso na reference função. Veja a referência.
• Uma função references() que retorna uma matriz de objetos que representam os estados de tempo de execução de uma coleção de recursos. Ver referências.
• Use a propriedade de recurso 'existente' para declarar recursos existentes para o ARM ler em vez de implantar um recurso. Consulte Declarar recursos existentes.
• Crie tipos definidos pelo usuário. Consulte Definição de tipo.
• Restrições adicionais de validação de tipo agregado a serem usadas em parâmetros e saídas.
• O valor padrão para a expressionEvaluationOptions propriedade é inner. O valor outer está bloqueado. Consulte Escopo de avaliação de expressão em modelos aninhados.
• A deployment função retorna um subconjunto limitado de propriedades. Consulte a implantação.
• Se o recurso Deployments for usado em uma implantação de nome simbólico, use apiVersion 2020-09-01 ou posterior.
• Na definição de recurso, valores de escape duplo dentro de uma expressão não são mais necessários. Consulte Personagens de fuga.

O uso de qualquer um dos seguintes recursos do Bicep habilita automaticamente a geração de código da versão 2.0 do idioma:

• Tipos definidos pelo usuário
• funções definidas pelo utilizador
• Importações em tempo de compilação
• características experimentais

Próximos passos

• Para ver modelos completos para vários tipos de soluções, veja os Modelos de Início Rápido do Azure.
• Para obter detalhes sobre as funções que você pode usar de dentro de um modelo, consulte Funções de modelo ARM.
• Para combinar vários modelos durante a implantação, consulte Usando modelos vinculados e aninhados ao implantar recursos do Azure.
• Para obter recomendações sobre como criar modelos, consulte Práticas recomendadas de modelo ARM.
• Para obter respostas a perguntas comuns, consulte Perguntas frequentes sobre modelos ARM.