建立 Resource Manager 參數檔案

  • 發行項

相對於在指令碼中將參數作為內嵌值傳遞，您可以使用包含參數值的 JSON 檔案。 本文說明如何建立與 JSON 範本搭配使用的參數檔案。

提示

我們建議使用 Bicep，因為其提供的功能與 ARM 範本相同，而且語法更易於使用。 若要深入了解，請參閱參數檔案。

參數檔案

參數檔案使用下列格式：

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

值得注意的是，參數檔案會將參數值儲存為純文字。 基於安全性考慮，不建議將此方法用於敏感性值，例如密碼。 如果您必須傳遞具敏感性值的參數，請在金鑰保存庫中保留值。 然後，在您的參數檔案中，包括對金鑰保存庫的參考。 在部署期間，會以安全的方式擷取敏感性值。 如需詳細資訊，請參閱在部署期間使用 Azure Key Vault 以傳遞安全的參數值。

下列參數檔案包含純文字值和儲存於金鑰保存庫的敏感值。

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

如需使用來自金鑰保存庫之值的詳細資訊，請參閱在部署期間使用 Azure Key Vault 以傳遞安全的參數值。

定義參數值

若要判斷如何定義參數名稱和值，請開啟您的 JSON 範本並檢閱 parameters 一節。 下列範例顯示 JSON 範本的參數。

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

在參數檔案中，要注意的第一個詳細資料是每個參數的名稱。 參數檔案中參數名稱必須符合範本的參數名稱。

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

注意參數類型。 參數檔案必須與範本使用相同的參數類型。 在此範例中，這兩個參數類型都是字串。

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

檢查範本中是否有具預設值的參數。 如果參數具有預設值，您可視所需在參數檔案中提供值。 參數檔案值會覆寫範本的預設值。

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

檢查範本的允許值和任何限制，例如長度上限。 這些值會指定您可以為參數提供的值範圍。 在此範例中，storagePrefix 最多可以有 11 個字元，且 storageAccountType 必須指定允許值。

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

注意

您的參數檔案只可包含範本中定義的參數值。 如果您的參數檔案包含不符合範本參數的額外參數，則會收到錯誤。

參數類型格式

下列範例顯示不同參數類型的格式：字串、整數、布林值、陣列和物件。

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

使用參數檔案部署範本

在 Azure CLI 中，您可以使用 @ 和參數檔案名稱，來傳遞本機參數檔案。 例如： @storage.parameters.json 。

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

如需詳細資訊，請參閱使用 ARM 範本與 Azure CLI 來部署資源。

在 Azure PowerShell 中，您可以使用 TemplateParameterFile 參數，來傳遞本機參數檔案。

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

如需詳細資訊，請參閱使用 ARM 範本與 Azure PowerShell 來部署資源。

注意

參數檔案無法用於入口網站中的自訂範本刀鋒視窗。

提示

如果您使用 Visual Studio 中的 Azure 資源群組專案，請確定參數檔案將其 [建置動作] 設定為 [內容]。

File name

參數檔案的一般命名慣例，是在範本名稱中包含 parameters。 例如，如果您的範本名稱為 azuredeploy.json，則會將您的參數檔案命名為 azuredeploy.parameters.json。 此命名慣例可協助您查看範本和參數之間的關係。

若要部署到不同的環境，您可以建立一個以上的參數檔案。 為參數檔案命名時，請識別其使用方式，例如用於開發和生產環境。 例如，使用 azuredeploy.parameters-dev.json 和 azuredeploy.parameters-prod.json 以部署資源。

參數優先順序

您可以在相同的部署作業中使用內嵌參數和本機參數檔案。 例如，您可以在部署期間指定本機參數檔案中的某些值，並新增其他內嵌值。 如果您同時為本機檔案中和內嵌的參數提供值，內嵌值的優先順序較高。

藉由提供檔案的 URI，就能夠使用外部參數檔案。 使用外部參數檔案時，您無法傳遞內嵌或本機檔案的其他值。 所有內嵌參數均會遭到忽略。 請提供外部檔案中的所有參數值。

參數名稱衝突

如果範本所包含的參數名稱與 PowerShell 命令中的其中一個參數相同，則 PowerShell 會以加上後置詞 FromTemplate 的方式，呈現範本中的參數。 例如，範本中名為 ResourceGroupName 的參數會與 New-AzResourceGroupDeployment Cmdlet 中的 ResourceGroupName 參數發生衝突。 系統會提示您提供 ResourceGroupNameFromTemplate 的值。 若要避免此混淆情形，請使用未用於部署命令的參數名稱。

下一步