分享方式:


ARM 範本中的類型定義

本文描述如何在 Azure Resource Manager 範本 (ARM 範本) 中建立和使用定義。 藉由定義您自己的類型,您可以重複使用這些類型。 類型定義只能與 languageVersion 2.0 搭配使用。

注意

適用於 Visual Studio Code 的 Azure Resource Manager 工具延伸模組目前版本無法辨識 languageVersion 2.0 中所做的增強功能。

提示

我們建議使用 Bicep,因為其提供的功能與 ARM 範本相同,而且語法更易於使用。 若要深入了解,請參閱 Bicep 中的使用者定義資料類型

基本宣告

每個類型定義至少都需要名稱和 type$ref

"definitions": {
  "demoStringType": {
    "type": "string"
  },
  "demoIntType": {
    "type": "int"
  },
  "demoBoolType": {
    "type": "bool"
  },
  "demoObjectType": {
    "type": "object"
  },
  "demoArrayType": {
    "type": "array"
  }
}

允許的值

您可以定義允許的類型定義值。 您可以用陣列方式提供允許的值。 如果針對類型定義傳入的參數值不是其中一個允許的值,則部署會在驗證期間失敗。

"definitions": {
  "demoEnumType": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

長度限制

您可以為字串和陣列類型定義指定最小和最大長度。 您可以設定一或兩個限制式。 若為字串,長度代表字元數。 若為陣列,長度代表陣列中的項目數。

下列範例會宣告兩個類型定義。 其中一個類型定義是儲存體帳戶名稱,該名稱必須包含 3-24 個字元。 另一個類型定義是陣列,必須包含 1-5 個項目。

"definitions": {
  "storageAccountNameType": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNameType": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

整數限制式

您可以設定整數參數定義的最小值和最大值。 您可以設定一或兩個限制式。

"definitions": {
  "monthType": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

物件條件約束

屬性

properties 的值是屬性名稱 => 類型定義的對應。

下列範例會接受 {"foo": "string", "bar": 1},但拒絕 {"foo": "string", "bar": -1}{"foo": "", "bar": 1} 或任何沒有 foobar 屬性的物件。

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
},
"parameters": {
  "objectParameter": {
    "$ref": "#/definitions/objectDefinition",
  }
}

除非屬性’的類型定義具有 "nullable": true 條件約束,否則所有屬性都是必要的。 若要讓上述範例中的這兩個屬性成為選擇性屬性,其外觀如下:

"definitions": {
  "objectDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

additionalProperties 的值是類型定義或布林值。 如果未定義任何 additionalProperties 條件約束,則預設值為 true

如果值是類型定義,則值會描述套用至 properties 條件約束中未提及之所有屬性的結構描述。 下列範例會接受 {"fizz": "buzz", "foo": "bar"},但拒絕 {"property": 1}

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

如果值是 false,則可能不會提供 properties 條件約束中所定義以外的屬性。 下列範例會接受 {"foo": "string", "bar": 1},但拒絕 {"foo": "string", "bar": 1, "fizz": "buzz"}

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

如果值是 true,則 properties 條件約束中未定義的任何屬性都接受任何值。 下列範例會接受 {"foo": "string", "bar": 1, "fizz": "buzz"}

"definitions": {
  "dictionaryDefinition": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

discriminator

discriminator 定義要根據鑑別子屬性套用的結構描述。 下列範例會接受 {"type": "ints", "foo": 1, "bar": 2}{"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"},但拒絕 {"type": "ints", "fizz": "buzz"}

"definitions": {
  "taggedUnionDefinition": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

陣列條件約束

prefixItems

prefixItems 的值是類型定義的陣列。 值中的每個類型定義,都是用來驗證相同索引陣列元素的結構描述。 下列範例會接受 [1, true],但拒絕 [1, "string"][1]

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ]
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

項目

items 的值是類型定義或布林值。 如果未定義任何 items 條件約束,則預設值為 true

如果值是類型定義,則值會描述套用至陣列 (其索引大於 prefixItems 條件約束的最大索引) 中所有元素的結構描述。 下列範例會接受 [1, true, 1][1, true, 1, 1],但拒絕 [1, true, "foo"]

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" }
  }
},
"parameters": {
  "tupleParameter": {
    "$ref": "#/definitions/tupleDefinition"
  }
}

您可以使用 items 而不使用 prefixItems。 下列範例會接受 [1, 2][1],但拒絕 ["foo"]

"definitions": {
  "intArrayDefinition": {
    "type": "array",
    "items": { "type": "int" }
  }
},
"parameters": {
  "intArrayParameter": {
    "$ref": "#/definitions/intArrayDefinition"
  }
}

如果值是 false,則已驗證的陣列長度必須與 prefixItems 條件約束完全相同。 下列範例會接受 [1, true],但拒絕 [1, true, 1][1, true, false, "foo", "bar"]

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": false
}

如果值為 true,則陣列 (其索引大於 prefixItems 條件約束的最大索引) 的元素接受任何值。 下列範例會接受 [1, true][1, true, 1][1, true, false, "foo", "bar"]

"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}
"definitions": {
  "tupleDefinition": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

可為 Null 的限制式

可為 Null 的條件約束表示值可能為 null 或省略。 如需範例,請參閱屬性

描述

您可以將描述新增至類型定義,以協助範本的使用者了解要提供的值。

"definitions": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

使用定義

若要參考類型定義,請使用下列語法:

"$ref": "#/definitions/<definition-name>"

下列範例示範如何從參數和輸出參考類型定義:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "languageVersion": "2.0",

  "definitions": {
    "naturalNumber": {
      "type": "int",
      "minValue": 1
    }
  },
  "parameters": {
    "numberParam": {
      "$ref": "#/definitions/naturalNumber",
      "defaultValue": 0
    }
  },
  "resources": {},
  "outputs": {
    "output1": {
      "$ref": "#/definitions/naturalNumber",
      "value": "[parameters('numberParam')]"
    }
  }
}

下一步