ARM 範本中的類型定義

發行項
09/26/2024

本文描述如何在 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} 或任何沒有 foo 或 bar 屬性的物件。

"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')]"
    }
  }
}

下一步

若要了解類型定義的可用屬性，請參閱了解 ARM 範本的結構和語法。

共用方式為