Criar Resource Manager ficheiro de parâmetros

Artigo
03/20/2024

Em vez de transmitir parâmetros como valores inline no script, pode utilizar um ficheiro JSON que contenha os valores dos parâmetros. Este artigo mostra como criar um ficheiro de parâmetros que utiliza com um modelo JSON.

Dica

Recomendamos o Bicep porque oferece as mesmas capacidades que os modelos do ARM e a sintaxe é mais fácil de utilizar. Para saber mais, veja ficheiros de parâmetros.

Ficheiro de parâmetros

Um ficheiro de parâmetros utiliza 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 notar que o ficheiro de parâmetros guarda valores de parâmetros como texto simples. Por motivos de segurança, esta abordagem não é recomendada para valores confidenciais, como palavras-passe. Se tiver de transmitir um parâmetro com um valor confidencial, mantenha o valor num cofre de chaves. Em seguida, no ficheiro de parâmetros, inclua uma referência ao cofre de chaves. Durante a implementação, o valor confidencial é obtido de forma segura. Para obter mais informações, veja Utilizar o Azure Key Vault para transmitir o valor do parâmetro seguro durante a implementação.

O seguinte ficheiro de parâmetros inclui um valor de texto simples e um valor confidencial armazenado num 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 obter mais informações sobre como utilizar valores de um cofre de chaves, veja Utilizar o Azure Key Vault para transmitir o valor do parâmetro seguro durante a implementação.

Definir valores de parâmetros

Para determinar como definir os nomes e valores dos parâmetros, abra o modelo JSON e reveja a parameters secção . O exemplo seguinte 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 ficheiro de parâmetros, o primeiro detalhe a notar é o nome de cada parâmetro. Os nomes dos parâmetros no ficheiro de parâmetros têm de corresponder aos nomes dos parâmetros no modelo.

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

Repare no tipo de parâmetro. Os tipos de parâmetros no ficheiro de parâmetros têm de utilizar os mesmos tipos que o modelo. Neste exemplo, ambos os tipos de parâmetros são cadeias.

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

Verifique se existem parâmetros no modelo com um valor predefinido. Se um parâmetro tiver um valor predefinido, pode fornecer um valor no ficheiro de parâmetros, mas não é necessário. O valor do ficheiro de parâmetro substitui o valor predefinido 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 quaisquer restrições, como o comprimento máximo. Esses valores especificam o intervalo de valores que pode fornecer para um parâmetro. Neste exemplo, storagePrefix pode ter um máximo de 11 carateres e storageAccountType tem de 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"
    }
  }
}

Nota

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

Formatos de tipo de parâmetro

O exemplo seguinte mostra os formatos de diferentes tipos de parâmetros: cadeia, número 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"
      }
    }
  }
}

Implementar modelo com ficheiro de parâmetros

Na CLI do Azure, transmite um ficheiro de parâmetro local com @ o nome do ficheiro e o nome do ficheiro de parâmetro. 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, veja Implementar recursos com modelos arm e a CLI do Azure.

A partir de Azure PowerShell transmite um ficheiro de parâmetro local com o TemplateParameterFile parâmetro .

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

Para obter mais informações, veja Implementar recursos com modelos arm e Azure PowerShell.

Nota

Não é possível utilizar um ficheiro de parâmetros com o painel de modelo personalizado no portal.

Dica

Se estiver a utilizar o projeto do Grupo de Recursos do Azure no Visual Studio, certifique-se de que o ficheiro de parâmetros tem a Ação de Compilação definida como Conteúdo.

Nome de ficheiro

A convenção de nomenclatura geral para o ficheiro de parâmetros é incluir parâmetros no nome do modelo. Por exemplo, se o seu modelo tiver o nome azuredeploy.json, o ficheiro de parâmetros tem o nome azuredeploy.parameters.json. Esta convenção de nomenclatura ajuda-o a ver a ligação entre o modelo e os parâmetros.

Para implementar em ambientes diferentes, crie mais do que um ficheiro de parâmetros. Quando atribuir um nome aos ficheiros de parâmetros, identifique a respetiva utilização, como desenvolvimento e produção. Por exemplo, utilize azuredeploy.parameters-dev.json e azuredeploy.parameters-prod.json para implementar recursos.

Precedência de parâmetros

Pode utilizar parâmetros inline e um ficheiro de parâmetro local na mesma operação de implementação. Por exemplo, pode especificar alguns valores no ficheiro de parâmetros local e adicionar outros valores inline durante a implementação. Se fornecer valores para um parâmetro no ficheiro de parâmetro local e inline, o valor inline tem precedência.

É possível utilizar um ficheiro de parâmetro externo ao fornecer o URI ao ficheiro. Quando utiliza um ficheiro de parâmetro externo, não pode transmitir outros valores inline ou a partir de um ficheiro local. Todos os parâmetros inline são ignorados. Indique todos os valores de parâmetros no ficheiro externo.

Conflitos de nomes de parâmetros

Se o seu modelo incluir um parâmetro com o mesmo nome que um dos parâmetros no comando do PowerShell, o PowerShell apresenta o parâmetro do seu modelo com o postfixo FromTemplate. Por exemplo, um parâmetro com o nome ResourceGroupName no modelo entra em conflito com o ResourceGroupName parâmetro no cmdlet New-AzResourceGroupDeployment . É-lhe pedido que forneça um valor para ResourceGroupNameFromTemplate. Para evitar esta confusão, utilize nomes de parâmetros que não são utilizados para comandos de implementação.

Passos seguintes

Para obter mais informações sobre como definir parâmetros num modelo, veja Parameters in ARM templates (Parâmetros em modelos do ARM).
Para obter mais informações sobre como utilizar valores de um cofre de chaves, veja Utilizar o Azure Key Vault para transmitir o valor do parâmetro seguro durante a implementação.