Especificação de modelo do Azure Resource Manager

Uma especificação de modelo é um tipo de recurso para armazenar um modelo de Azure Resource Manager (modelo ARM) no Azure para implantação posterior. Esse tipo de recurso permite que você compartilhe modelos do ARM com outros usuários em sua organização. Assim como qualquer outro recurso do Azure, você pode usar o Azure RBAC (controle de acesso baseado em função) para compartilhar a especificação do modelo.

Microsoft. Resources/templateSpecs é o tipo de recurso para as especificações de modelo. Ele consiste em um modelo principal e qualquer número de modelos vinculados. O Azure armazena as especificações de modelo com segurança em grupos de recursos. As especificações de modelo dão suporte ao controle de versão.

Para implantar a especificação de modelo, use as ferramentas padrão do Azure como o PowerShell, CLI do Azure, portal do Azure, REST e outros SDKs e clientes com suporte. Use os mesmos comandos usados para o modelo.

Ao projetar sua implantação, considere o ciclo de vida dos recursos. Agrupe os recursos que compartilham um ciclo de vida semelhante em uma única especificação de modelo. Por exemplo, suas implantações incluem várias instâncias do Azure Cosmos DB, com cada instância contendo seus próprios bancos de dados e contêineres. Como os bancos de dados e os contêineres não mudam muito, crie uma especificação de modelo para incluir uma instância do Cosmos DB e seus bancos de dados e contêineres subjacentes. Para criar várias instâncias desses recursos, use instruções condicionais em seus modelos juntamente com loops de cópia.

Recursos de treinamento

Para saber mais sobre as especificações de modelo e obter diretrizes práticas, confira Publicar bibliotecas de código de infraestrutura reutilizável usando especificações de modelo.

Por que usar as especificações de modelo?

As especificação de modelo oferecem os seguintes benefícios:

• Você usa modelos ARM padrão para sua especificação de modelo.
• Você gerencia o acesso por meio do Azure RBAC, em vez de tokens SAS.
• Os usuários podem implantar a especificação de modelo sem ter acesso de gravação ao modelo.
• Você pode integrar a especificação de modelo aos processos de implantação existentes, como o script do PowerShell ou DevOps pipeline.

As especificações de modelo permitem que você crie modelos canônicos e compartilhe-os com equipes em sua organização. As especificações de modelo são seguras porque estão disponíveis para Azure Resource Manager para implantação, mas não podem ser acessadas por usuários sem a permissão correta. Os usuários precisam somente de acesso de leitura à especificação de modelo para implantar seu modelo, para que você possa compartilhar o modelo sem permitir que outras pessoas o modifiquem.

Se, no momento, você tiver seus modelos em um repositório GitHub ou em uma conta de armazenamento, você encontrará vários desafios ao tentar compartilhar e usar os modelos. Para implantar o modelo, você precisa tornar o modelo acessível publicamente ou gerenciar o acesso com tokens SAS. Para contornar essa limitação, você pode criar cópias locais, que eventualmente divergem do modelo original. As especificações de modelo simplificam o compartilhamento de modelos.

Para seguir os requisitos e diretrizes da sua organização, os administradores devem verificar os modelos que você inclui em uma especificação de modelo.

Permissões necessárias

Há duas funções internas do Azure definidas para a especificação de modelo:

• Leitor da Especificação de Modelo
• Colaborador da Especificação de Modelo

Além disso, você precisa das permissões para implantar um arquivo Bicep. Para obter mais informações, consulte Implantar - CLI ou Implantar - PowerShell.

Criar especificação de modelo

O exemplo a seguir mostra um modelo simples para criar uma conta de armazenamento no Azure.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2025-06-01",
      "name": "[concat('store', uniquestring(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "kind": "StorageV2",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      }
    }
  ]
}

Quando você cria a especificação de modelo, os comandos do PowerShell ou da CLI são passados como o arquivo de modelo principal. Se o modelo principal fizer referência a modelos vinculados, os comandos os localizarão e os empacotarão. Para saber mais, confira Criar uma especificação de modelo com modelos vinculados.

Crie uma especificação de modelo usando:

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.json

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

Você também pode criar especificações de modelo usando modelos do ARM. O modelo a seguir cria uma especificação de modelo para implantar uma conta de armazenamento:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "templateSpecName": {
      "type": "string",
      "defaultValue": "CreateStorageAccount"
    },
    "templateSpecVersionName": {
      "type": "string",
      "defaultValue": "0.1"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/templateSpecs",
      "apiVersion": "2022-02-01",
      "name": "[parameters('templateSpecName')]",
      "location": "[parameters('location')]",
      "properties": {
        "description": "A basic templateSpec - creates a storage account.",
        "displayName": "Storage account (Standard_LRS)"
      }
    },
    {
      "type": "Microsoft.Resources/templateSpecs/versions",
      "apiVersion": "2022-02-01",
      "name": "[format('{0}/{1}', parameters('templateSpecName'), parameters('templateSpecVersionName'))]",
      "location": "[parameters('location')]",
      "dependsOn": [
        "[resourceId('Microsoft.Resources/templateSpecs', parameters('templateSpecName'))]"
      ],
      "properties": {
        "mainTemplate": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "parameters": {
            "storageAccountType": {
              "type": "string",
              "defaultValue": "Standard_LRS",
              "allowedValues": [
                "Standard_LRS",
                "Standard_GRS",
                "Standard_ZRS",
                "Premium_LRS"
              ]
            }
          },
          "resources": [
            {
              "type": "Microsoft.Storage/storageAccounts",
              "apiVersion": "2025-06-01",
              "name": "[concat('store', uniquestring(resourceGroup().id))]",
              "location": "[resourceGroup().location]",
              "kind": "StorageV2",
              "sku": {
                "name": "[parameters('storageAccountType')]"
              }
            }
          ]
        }
      }
    }
  ]
}

O tamanho de uma especificação de modelo é limitado a aproximadamente 2 MB. Se um tamanho de especificação de modelo exceder o limite, você receberá o código de erro TemplateSpecTooLarge. A mensagem de erro indica:

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

Você pode exibir todas as especificações de modelo em sua assinatura usando:

Get-AzTemplateSpec

az ts list

Você pode exibir detalhes de uma especificação de modelo, incluindo suas versões com:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

az ts show \
    --name storageSpec \
    --resource-group templateSpecRG \
    --version "1.0a"

Implantar especificação de modelo

Depois de criar a especificação do modelo, os usuários com a função Leitor de especificações de modelo podem implantá-la. Além disso, você também precisa das permissões para implantar um modelo do ARM. Para obter mais informações, consulte Implantar - CLI ou Implantar - PowerShell.

Você pode implantar as especificações de modelo por meio do portal, do PowerShell, CLI do Azure ou como um modelo vinculado em uma implantação de modelo maior. Os usuários em uma organização podem implantar uma especificação de modelo em qualquer escopo no Azure (grupo de recursos, assinatura, grupo de gerenciamento ou locatário).

Em vez de passar um caminho ou URI para um modelo, você implanta uma especificação de modelo fornecendo sua ID de recurso. A ID do recurso tem o seguinte formato:

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

Observe que a ID do recurso inclui um nome de versão para a especificação de modelo.

Por exemplo, você implanta uma especificação de modelo com o comando a seguir.

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

Na prática, você normalmente executa Get-AzTemplateSpec ou az ts show para obter a ID da especificação de modelo que deseja implantar.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0a" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

Você também pode abrir uma URL no seguinte formato para implantar uma especificação de modelo:

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

Parâmetros

A passagem de parâmetros para a especificação de modelo é como passar parâmetros para um modelo do ARM. Adicione os valores de parâmetro embutidos ou em um arquivo de parâmetro.

Para passar um parâmetro embutido, use:

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters storageAccountType='Standard_GRS'

Para criar um arquivo de parâmetros local, use:

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

E, passe esse arquivo de parâmetro com:

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./mainTemplate.parameters.json"

Controle de versão

Ao criar uma especificação de modelo, você fornece um nome de versão para ela. À medida que você itera o código do modelo, você pode atualizar uma versão existente (para hotfixes) ou publicar uma nova versão. A versão é uma cadeia de caracteres de texto. Você pode optar por seguir qualquer sistema de controle de versão, incluindo controle de versão semântico. Os usuários da especificação de modelo podem fornecer o nome da versão que desejam usar ao implantá-lo. Você pode ter um número ilimitado de versões.

Usar marcações

As marcas ajudam você a organizar logicamente seus recursos. Você pode adicionar marcas às especificações de modelo usando Azure PowerShell e CLI do Azure:

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.json `
  -Tag @{Dept="Finance";Environment="Production"}

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json" \
  --tags Dept=Finance Environment=Production

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.json `
  -Tag @{Dept="Finance";Environment="Production"}

az ts update \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json" \
  --tags Dept=Finance Environment=Production

Quando você cria ou modifica uma especificação de modelo com o parâmetro de versão especificado, mas sem o parâmetro de marca:

• Se a especificação de modelo existir e tiver tags, mas a versão não existir, a nova versão herdará as mesmas tags da especificação de modelo existente.

Quando você cria ou modifica uma especificação de modelo com o parâmetro de marca e o parâmetro de versão especificados:

• Se a especificação de modelo e a versão não existirem, as tags serão adicionadas à nova especificação de modelo e à nova versão.
• Se a especificação de modelo existir, mas a versão não existir, as tags serão adicionadas somente à nova versão.
• Se a especificação de modelo e a versão existirem, as tags se aplicarão somente à versão.

Ao modificar um modelo especificando o parâmetro de marca, mas sem especificar o parâmetro de versão, você adiciona as marcas apenas à especificação de modelo.

Criar uma especificação de modelo com modelos vinculados

Se o modelo principal para a especificação do modelo fizer referência a modelos vinculados, os comandos do PowerShell e da CLI poderão localizar e empacotar automaticamente os modelos vinculados da unidade local. Você não precisa configurar manualmente as contas de armazenamento ou repositórios para hospedar as especificações de modelo - tudo é independente no recurso de especificação de modelo.

O exemplo a seguir consiste em um modelo principal com dois modelos vinculados. O exemplo é apenas um trecho do modelo. Observe que ele usa uma propriedade chamada relativePath para vincular a outros modelos. Você deve usar apiVersion de 2020-06-01 ou posterior para o recurso de implantações.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2025-04-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/webapp.json"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2025-04-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/database.json"
        }
      }
    }
  ],
  "outputs": {}
}

Quando você executa o comando do PowerShell ou da CLI para criar a especificação de modelo para o exemplo anterior, o comando localiza três arquivos: o modelo principal, o modelo de aplicativo Web (webapp.json) e o modelo de banco de dados (database.json) - e os empacota para a especificação de modelo.

Para obter mais informações, consulte Tutorial: Criar uma especificação de modelo com modelos vinculados.

Implantar a especificação de modelo como um modelo vinculado

Depois de criar uma especificação de modelo, você pode reutilizá-la facilmente de um modelo do ARM ou de outra especificação de modelo. Para vincular a uma especificação de modelo, adicione sua ID de recurso ao modelo. Quando você implanta o modelo principal, ele implanta automaticamente a especificação de modelo vinculado. Esse comportamento permite desenvolver especificações de modelo modulares e reutilizá-las conforme necessário.

Por exemplo, você pode criar uma especificação de modelo que implanta recursos de rede e outra especificação de modelo que implanta recursos de armazenamento. Em modelos ARM, você vincula a essas duas especificações de modelo sempre que precisar configurar recursos de rede ou de armazenamento.

O exemplo a seguir é semelhante ao exemplo anterior, mas você usa a id propriedade para vincular a uma especificação de modelo em vez da relativePath propriedade a ser vinculada a um modelo local. Use 2020-06-01 para a versão da API para o recurso de implantações. No exemplo, as especificações de modelo estão em um grupo de recursos chamado templateSpecsRG.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2025-04-01",
      "name": "networkingDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'networkingSpec', '1.0a')]"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2025-04-01",
      "name": "storageDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'storageSpec', '1.0a')]"
        }
      }
    }
  ],
  "outputs": {}
}

Para obter mais informações sobre como vincular especificações de modelo, consulte Tutorial: Implantar uma especificação de modelo como um modelo vinculado.

Próximas etapas

• Para criar e implantar uma especificação de modelo, consulte Início rápido: Criar e implantar especificação de modelo.

• Para obter mais informações sobre como vincular modelos em especificações de modelo, consulte Tutorial: Criar uma especificação de modelo com modelos vinculados.

• Para obter mais informações sobre como implantar uma especificação de modelo como um modelo vinculado, consulte Tutorial: Implantar uma especificação de modelo como um modelo vinculado.