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

Artigo
11/29/2022
15 minutos para ler

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

Este artigo destina-se a utilizadores que tenham alguma familiaridade com os modelos ARM. Fornece informações detalhadas sobre a estrutura do modelo. Para um tutorial passo a passo que o guia através do processo de criação de um modelo, consulte Tutorial: Crie e implemente o seu primeiro modelo ARM. Para aprender sobre os modelos ARM através de um conjunto guiado de módulos Learn, consulte Implementar e gerir recursos em Azure utilizando modelos ARM.

Dica

Bicep é uma nova linguagem que oferece as mesmas capacidades que os modelos ARM, mas com uma sintaxe que é mais fácil de usar. Se está a considerar a infraestrutura como opções de código, recomendamos que procure o Bicep.

Para saber mais sobre os elementos de um ficheiro Bicep, consulte Compreender a estrutura e sintaxe dos ficheiros Bicep.

Formato de modelo

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

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

Nome do elemento	Necessário	Descrição
$schema	Yes	Localização do ficheiro de esquema de notação de objetos JavaScript (JSON) que descreve a versão do idioma do modelo. O número de versão que utiliza depende do âmbito da implementação e do seu editor de JSON. Se estiver a utilizar o Código do Estúdio Visual com a extensão de ferramentas Azure Resource Manager, utilize a versão mais recente para implementações de grupos de recursos: `https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#` Outros editores (incluindo o Visual Studio) podem não ser capazes de processar este esquema. Para os editores, utilize: `https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#` Para implementações de subscrição, utilize: `https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#` Para implementações de grupos de gestão, utilize: `https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#` Para implantações de inquilinos, utilize: `https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#`
contentVersão	Yes	Versão do modelo (tal como 1.0.0.0). Pode fornecer qualquer valor para este elemento. Utilize este valor para documentar alterações significativas no seu modelo. Ao utilizar recursos utilizando o modelo, este valor pode ser usado para garantir que o modelo certo está a ser utilizado.
apiProfile	No	Uma versão API que serve como uma coleção de versões API para tipos de recursos. Utilize este valor para evitar ter de especificar versões API para cada recurso no modelo. Quando especifica uma versão de perfil API e não especifica uma versão API para o tipo de recurso, Resource Manager utiliza a versão API para esse tipo de recurso que é definido no perfil. A propriedade de perfil API é especialmente útil ao implementar um modelo para diferentes ambientes, tais como Azure Stack e Global Azure. Utilize a versão de perfil API para se certificar de que o seu modelo utiliza automaticamente versões suportadas em ambos os ambientes. Para obter uma lista das versões de perfil da API atuais e as versões API de recursos definidas no perfil, consulte o Perfil da API. Para obter mais informações, consulte versões Track utilizando perfis API.
parameters	No	Valores que são fornecidos quando a implementação é executada para personalizar a implementação de recursos.
variáveis	No	Valores que são usados como fragmentos de JSON no modelo para simplificar expressões de linguagem do modelo.
funções	No	Funções definidas pelo utilizador que estão disponíveis dentro do modelo.
recursos	Yes	Tipos de recursos que são implantados ou atualizados num grupo de recursos ou subscrição.
saídas	No	Valores que são devolvidos após a implantação.

Cada elemento tem propriedades que pode definir. Este artigo descreve as secções do modelo com maior detalhe.

Parâmetros

parameters Na secção do modelo, especifique quais os valores que pode inserir ao utilizar os recursos. Está limitado a 256 parâmetros num modelo. Pode reduzir o número de parâmetros utilizando objetos que contêm múltiplas 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-parameters>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}

Nome do elemento	Necessário	Descrição
nome de parâmetro	Yes	Nome do parâmetro. Deve ser um identificador JavaScript válido.
tipo	Yes	Tipo do valor do parâmetro. Os tipos e valores permitidos são cordas, securestring, int, bool, objeto, secureObject, e array. Consulte os tipos de dados nos modelos ARM.
padrãoValue	No	Valor predefinido para o parâmetro, se não for fornecido qualquer valor para o parâmetro.
permitidosValues	No	Matriz de valores permitidos para o parâmetro para garantir que o valor certo é fornecido.
minValue	No	O valor mínimo para os parâmetros do tipo int, este valor é inclusivo.
maxValue	No	O valor máximo para parâmetros do tipo int, este valor é inclusivo.
minLength	No	O comprimento mínimo para parâmetros de corda, corda de segurança e tipo de matriz, este valor é inclusivo.
maxLength	No	O comprimento máximo para parâmetros de corda, corda segura e tipo de matriz, este valor é inclusivo.
descrição	No	Descrição do parâmetro que é apresentado aos utilizadores através do portal. Para obter mais informações, consulte comentários em modelos.

Por exemplo, como utilizar parâmetros, consulte parâmetros nos modelos ARM.

Em Bicep, consulte os parâmetros.

Variáveis

variables Na secção, constrói valores que podem ser utilizados em todo o seu modelo. Não é preciso definir variáveis, mas muitas vezes simplificam o 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 a definição de 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 a utilização copy para criar vários valores para uma variável, consulte iteração variável.

Por exemplo, como utilizar variáveis, consulte Variáveis no modelo ARM.

Em Bicep, ver variáveis.

Funções

Dentro do seu modelo, pode criar as suas próprias funções. Estas funções estão disponíveis para utilização no seu modelo. Tipicamente, você define expressões complicadas que você não quer repetir ao longo do seu modelo. Cria as funções definidas pelo utilizador a partir de expressões e funções que são suportadas em modelos.

Ao definir uma função de utilizador, existem algumas restrições:

A função não pode aceder a variáveis.
A função só pode utilizar parâmetros definidos na função. Quando utiliza a função de parâmetros dentro de uma função definida pelo utilizador, está restrito aos parâmetros para essa função.
A função não pode chamar outras funções definidas pelo utilizador.
A função não pode utilizar a função de referência.
Os parâmetros para a função não podem ter valores predefinidos.

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

Nome do elemento	Necessário	Descrição
espaço de nomes	Yes	Espaço de nome para as funções personalizadas. Utilize para evitar o nome de conflitos com funções de modelo.
nome da função	Yes	Nome da função personalizada. Ao ligar para a função, combine o nome da função com o espaço de nome. Por exemplo, para chamar uma função nomeada `uniqueName` no namespace contoso, use `"[contoso.uniqueName()]"`.
nome de parâmetro	No	Nome do parâmetro a utilizar na função personalizada.
parâmetro-valor	No	Tipo do valor do parâmetro. Os tipos e valores permitidos são cordas, securestring, int, bool, objeto, secureObject, e array.
tipo de saída	Yes	Tipo do valor de saída. Os valores de saída suportam os mesmos tipos que os parâmetros de entrada da função.
valor de saída	Yes	Expressão da linguagem do modelo que é avaliada e devolvida da função.

Por exemplo, como utilizar funções personalizadas, consulte funções definidas pelo Utilizador no modelo ARM.

Em Bicep, as funções definidas pelo utilizador não são suportadas. A Bicep suporta uma variedade de funções e operadores.

Recursos

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

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

Nome do elemento	Necessário	Descrição
condição	No	Valor booleano que indica se o recurso será aprovisionado durante esta implementação. Quando `true`, o recurso é criado durante a implantação. Quando `false`, o recurso é ignorado para esta implantação. Ver condição.
tipo	Yes	Tipo de recurso. Este valor é uma combinação do espaço de nome do fornecedor de recursos e do tipo de recurso (por exemplo `Microsoft.Storage/storageAccounts`). Para determinar os valores disponíveis, consulte a referência do modelo. Para um recurso infantil, o formato do tipo depende se está aninhado no recurso principal ou definido fora do recurso principal. Consulte o nome do conjunto e o tipo para obter recursos para crianças.
apiVersion	Yes	Versão da API REST para utilizar para a criação do recurso. Ao criar um novo modelo, desloque este valor para a versão mais recente do recurso que está a implementar. Enquanto o modelo funcionar conforme necessário, continue a usar a mesma versão API. Ao continuar a utilizar a mesma versão API, minimiza o risco de uma nova versão API alterar o funcionamento do seu modelo. Considere atualizar a versão API apenas quando pretender utilizar uma nova funcionalidade que é introduzida numa versão posterior. Para determinar os valores disponíveis, consulte a referência do modelo.
name	Yes	Nome do recurso. O nome deve seguir as restrições de componentes URI definidas em RFC3986. Os serviços da Azure que expõem o nome de recursos a partes externas validam o nome para garantir que não é uma tentativa de falsificação de outra identidade. Para um recurso infantil, o formato do nome depende se está aninhado no recurso do progenitor ou definido fora do recurso principal. Consulte o nome do conjunto e o tipo para obter recursos para crianças.
comentários	No	As suas notas para documentar os recursos no seu modelo. Para obter mais informações, consulte comentários em modelos.
localização	Varia	Geo-localizações suportadas do recurso fornecido. Pode selecionar qualquer um dos locais disponíveis, mas normalmente faz sentido escolher um que esteja próximo dos seus utilizadores. Normalmente, também faz sentido colocar recursos que interagem uns com os outros na mesma região. A maioria dos tipos de recursos requer uma localização, mas alguns tipos (como uma atribuição de funções) não requerem uma localização. Consulte a localização do recurso definido.
dependsOn	No	Recursos que devem ser implantados antes deste recurso ser implantado. Resource Manager avalia as dependências entre recursos e os implanta na ordem correta. Quando os recursos não dependem uns dos outros, são implantados em paralelo. O valor pode ser uma lista separada por vírgula de um nome de recurso ou identificadores únicos de recursos. Apenas enumerar recursos que são implantados neste modelo. Os recursos que não estão definidos neste modelo já devem existir. Evite adicionar dependências desnecessárias pois podem retardar a sua implantação e criar dependências circulares. Para obter orientações sobre a definição das dependências, consulte definir a ordem para a implantação de recursos em modelos ARM.
etiquetas	No	Etiquetas que estão associadas ao recurso. Aplique tags para organizar logicamente recursos em toda a sua subscrição.
identidade	No	Alguns recursos apoiam identidades geridas para os recursos da Azure. Esses recursos têm um objeto de identidade ao nível da declaração de recursos. Pode definir se a identidade é atribuída ao utilizador ou atribuída ao sistema. Para identidades atribuídas ao utilizador, forneça uma lista de IDs de recursos para as identidades. Desajei a chave para o ID do recurso e o valor para um objeto vazio. Para obter mais informações, consulte as identidades geridas para a Azure num VM Azure utilizando modelos.
sku	No	Alguns recursos permitem que valores que definem o SKU implementem. Por exemplo, pode especificar o tipo de redundância para uma conta de armazenamento.
tipo	No	Alguns recursos permitem um valor que define o tipo de recurso que implementa. Por exemplo, pode especificar o tipo de exemplo DB de Azure Cosmos para criar.
scope	No	A propriedade de âmbito só está disponível para tipos de recursos de extensão. Utilize-o ao especificar um âmbito diferente do âmbito de implantação. Consulte a definição de possibilidade de extensão de recursos nos modelos ARM.
Cópia	No	Se for necessário mais do que uma instância, o número de recursos a criar. O modo predefinido é paralelo. Especifique o modo de série quando não quiser que todos ou os recursos implementem ao mesmo tempo. Para mais informações, consulte Criar várias instâncias de recursos em Azure Resource Manager.
plano	No	Alguns recursos permitem valores que definem o plano a implementar. Por exemplo, pode especificar a imagem do mercado para uma máquina virtual.
propriedades	No	Definições de configuração específicas de recursos. Os valores para as propriedades são os mesmos que os valores que fornece no organismo de pedido para a operação REST API (método PUT) para criar o recurso. Também pode especificar um conjunto de cópias para criar várias instâncias de uma propriedade. Para determinar os valores disponíveis, consulte a referência do modelo.
resources	No	Recursos infantis que dependem do recurso que está a ser definido. Apenas forneça tipos de recursos que sejam permitidos pelo esquema do recurso principal. A dependência do recurso dos pais não está implícita. Tens de definir explicitamente essa dependência. Consulte o nome do conjunto e o tipo para obter recursos para crianças.

Em Bicep, ver recursos.

Saídas

outputs Na secção, especifique os valores que são devolvidos da implantação. Normalmente, devolve-se valores dos 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>
    }
  }
}

Nome do elemento	Necessário	Descrição
nome de saída	Yes	Nome do valor de saída. Deve ser um identificador JavaScript válido.
condição	No	Valor booleano que indica se este valor de saída é devolvido. Quando `true`, o valor é incluído na saída para a implantação. Quando `false`, o valor de saída é ignorado para esta implantação. Quando não especificado, o valor predefinido é `true`.
tipo	Yes	Tipo do valor de saída. Os valores de saída suportam os mesmos tipos que os parâmetros de entrada do modelo. Se especificar o tipo de saída, o valor não é apresentado no histórico de implementação e não pode ser recuperado a partir de outro modelo. Para utilizar um valor secreto em mais de um modelo, guarde o segredo numa Key Vault e refira o segredo no ficheiro de parâmetros. Para obter mais informações, consulte Use Azure Key Vault para passar o valor do parâmetro seguro durante a implementação.
valor	No	Expressão da linguagem do modelo que é avaliada e devolvida como valor de saída. Especifique o valor ou a cópia.
Cópia	No	Costumava devolver mais do que um valor para uma saída. Especificar valor ou cópia. Para obter mais informações, consulte a iteração de saída nos modelos ARM.

Por exemplo, como utilizar saídas, consulte saídas no modelo ARM.

Em Bicep, ver saídas.

Comentários e metadados

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

Comentários

Para comentários inline, pode utilizar ou // ./* ... */ No Código do Estúdio Visual, guarde os ficheiros de parâmetros com comentários como o tipo de ficheiro JSON com comentários (JSONC), caso contrário receberá uma mensagem de erro a dizer "Comentários não permitidos no JSON".

Nota

Quando utilizar o CLI Azure para implementar modelos com comentários, utilize a versão 2.3.0 ou posterior e especifique o --handle-extended-json-format interruptor.

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

No Código do Estúdio Visual, a extensão Azure Resource Manager Tools pode detetar automaticamente um modelo ARM e alterar o modo de linguagem. Se vir o Modelo Azure Resource Manager no canto inferior direito do Código do Estúdio Visual, pode utilizar os comentários inline. Os comentários inline já não são marcados como inválidos.

Modo modelo de modelo de Resource Manager código de estúdio visual

Em Bicep, ver comentários.

Metadados

Pode adicionar um metadata objeto em qualquer lugar do seu modelo. Resource Manager ignora o objeto, mas o seu editor JSON pode avisá-lo que a propriedade não é válida. No objeto, defina as propriedades que precisa.

{
  "$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, adicionar um metadata objeto com uma description propriedade.

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

Ao implementar o modelo através do portal, o texto que fornece na descrição é automaticamente utilizado como uma dica para esse parâmetro.

Mostrar ponta de parâmetro

Para resources, adicionar um comments elemento ou um metadata objeto. O exemplo a seguir mostra tanto um comments elemento como um metadata objeto.

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

Para outputs, adicionar 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 utilizador.

Cordas multi-linha

Pode partir uma corda em várias linhas. Por exemplo, consulte a location propriedade e um dos comentários no exemplo JSON a seguir.