Criar um arquivo de parâmetro do Resource Manager

Artigo
03/20/2024

Em vez de passar parâmetros como valores embutidos no script, você pode usar um arquivo JSON que contenha os valores de parâmetro. Este artigo mostra como criar um arquivo de parâmetros usado com o modelo JSON.

Dica

Recomendamos o Bicep porque ele oferece as mesmas funcionalidades que os modelos do ARM e a sintaxe é mais fácil de usar. Para saber mais, confira arquivos de parâmetro.

Arquivo de parâmetro.

Um arquivo de parâmetros usa o seguinte formato:

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

Vale a pena observar que o arquivo de parâmetro salva valores de parâmetro como texto sem formatação. Por motivos de segurança, essa abordagem não é recomendada para valores confidenciais, como senhas. Se você precisar passar um parâmetro com um valor confidencial, mantenha o valor em um cofre de chaves. Em seguida, no arquivo de parâmetros, inclua uma referência ao cofre de chaves. Durante a implantação, o valor confidencial é recuperado com segurança. Para saber mais, confira Usar o Azure Key Vault para passar um valor de parâmetro seguro durante a implantação.

O arquivo de parâmetros a seguir inclui um valor de texto sem formatação e um valor confidencial que é armazenado em um cofre de chaves.

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

Para saber mais sobre ambas como usar valores de um cofre de chaves, confira Usar o Azure Key Vault para passar um valor de parâmetro seguro durante a implantação.

Definir valores de parâmetro

Para determinar como definir os nomes e valores de parâmetro, abra o modelo JSON e revise a seção parameters. O seguinte exemplo mostra os parâmetros do modelo JSON.

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

No arquivo de parâmetros, o primeiro detalhe a ser observado é o nome de cada parâmetro. Os nomes de parâmetro no arquivo de parâmetros devem corresponder aos nomes de parâmetro no modelo.

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

Observe o tipo de parâmetro. Os tipos de parâmetro no arquivo de parâmetros devem usar os mesmos tipos que o modelo. Neste exemplo, ambos os tipos de parâmetro são cadeias de caracteres.

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

Verifique o modelo em busca de parâmetros com um valor padrão. Se um parâmetro tiver um valor padrão, você poderá fornecer um valor no arquivo de parâmetros, mas não é necessário. O valor do arquivo de parâmetros substitui o valor padrão do modelo.

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

Verifique os valores permitidos do modelo e as restrições, como tamanho máximo. Esses valores especificam o intervalo de valores que você pode fornecer para um parâmetro. Neste exemplo, storagePrefix pode ter no máximo 11 caracteres e storageAccountType deve especificar um valor permitido.

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

Observação

O arquivo de parâmetros só pode conter valores para os parâmetros definidos no modelo. Se o arquivo de parâmetros contiver parâmetros adicionais que não correspondem aos parâmetros do modelo, você receberá um erro.

Formatos do tipo de parâmetro

O exemplo a seguir mostra os formatos dos diferentes tipos de parâmetro: cadeia de caracteres, inteiro, booleano, matriz e objeto.

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

Implantar o modelo com o arquivo de parâmetros

Na CLI do Azure, passe um arquivo de parâmetros local usando @ e o nome do arquivo de parâmetros. Por exemplo, @storage.parameters.json.

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

Para obter mais informações, confira Implantar recursos com modelos do ARM e a CLI do Azure.

No Azure PowerShell, passe um arquivo de parâmetros local usando o parâmetro TemplateParameterFile.

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

Para obter mais informações, confira Implantar recursos com modelos do ARM e o PowerShell.

Observação

Não é possível usar um arquivo de parâmetros com a folha do modelo personalizado no portal.

Dica

Se você estiver usando o projeto do grupo de recursos do Azure no Visual Studio, verifique se a Ação de Compilação do arquivo de parâmetros foi definida como Conteúdo.

Nome do arquivo

A convenção geral de nomenclatura para o arquivo de parâmetros determina que o termo parameters seja incluído no nome do modelo. Por exemplo, se seu modelo for nomeado azuredeploy.json, o arquivo de parâmetros será nomeado azuredeploy.parameters.json. Essa convenção de nomenclatura ajuda a ver a conexão entre o modelo e os parâmetros.

Para implantar em ambientes diferentes, crie mais de um arquivo de parâmetros. Ao nomear os arquivos de parâmetros, identifique o uso, como desenvolvimento e produção. Por exemplo, use azuredeploy.parameters-dev.json e azuredeploy.parameters-prod.json para implantar os recursos.

Precedência de parâmetro

Você pode usar parâmetros embutidos e um arquivo de parâmetro local na mesma operação de implantação. Por exemplo, você pode especificar alguns valores no arquivo de parâmetro local e adicionar outros valores embutidos durante a implantação. Se você fornecer valores para um parâmetro no arquivo de parâmetros local e embutido, o valor embutido terá precedência.

É possível usar um arquivo de parâmetros externo, fornecendo o URI para o arquivo. Quando você usa um arquivo de parâmetros externo, não é possível transmitir outros valores em linha ou em um arquivo local. Todos os parâmetros embutidos são ignorados. Forneça todos os valores de parâmetro no arquivo externo.

Conflitos de nome de parâmetro

Se o modelo incluir um parâmetro com o mesmo nome que um dos parâmetros no comando do PowerShell, o PowerShell apresentará o parâmetro do modelo com o postfix FromTemplate. Por exemplo, um parâmetro chamado ResourceGroupName no seu modelo entra em conflito com o parâmetro ResourceGroupName no cmdlet ResourceGroupName. Você é solicitado a fornecer um valor para ResourceGroupNameFromTemplate. Para evitar essa confusão, use nomes de parâmetros que não são usados para comandos de implantação.

Próximas etapas

Para obter mais informações sobre como definir parâmetros em um modelo, confira Parâmetros nos modelos do ARM.
Para saber mais sobre ambas como usar valores de um cofre de chaves, confira Usar o Azure Key Vault para passar um valor de parâmetro seguro durante a implantação.