Ketik definisi dalam templat ARM

Artikel
09/26/2024

Artikel ini menjelaskan cara membuat dan menggunakan definisi di templat Azure Resource Manager (templat ARM) Anda. Dengan menentukan jenis Anda sendiri, Anda dapat menggunakan kembali jenis ini. Definisi jenis hanya dapat digunakan dengan languageVersion 2.0.

Catatan

Rilis ekstensi Azure Resource Manager Tools saat ini untuk Visual Studio Code tidak mengenali penyempurnaan yang dibuat dalam languageVersion 2.0.

Tip

Kami merekomendasikan Bicep karena menawarkan kemampuan yang sama dengan templat ARM dan sintaksnya lebih mudah digunakan. Untuk mempelajari selengkapnya, lihat Jenis data yang ditentukan pengguna di Bicep.

Deklarasi minimal

Minimal, setiap definisi jenis memerlukan nama dan type atau $ref.

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

Nilai yang diizinkan

Anda dapat menentukan nilai yang diizinkan untuk definisi jenis. Anda memberikan nilai yang diizinkan dalam array. Penyebaran gagal selama validasi jika nilai diteruskan untuk definisi jenis yang bukan salah satu nilai yang diizinkan.

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

Batasan panjang

Anda dapat menentukan panjang minimum dan maksimum untuk definisi jenis string dan array. Anda dapat mengatur salah satu atau kedua batasan. Untuk string, panjangnya menunjukkan jumlah karakter. Untuk array, panjangnya menunjukkan jumlah item dalam array.

Contoh berikut mendeklarasikan dua definisi jenis. Satu definisi jenis adalah untuk nama akun penyimpanan yang harus memiliki 3-24 karakter. Definisi jenis lainnya adalah array yang harus memiliki dari 1-5 item.

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

Batasan bilangan bulat

Anda dapat mengatur nilai minimum dan maksimum untuk definisi jenis bilangan bulat. Anda dapat mengatur salah satu atau kedua batasan.

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

Batasan objek

Properti

Nilai properties adalah peta nama properti => definisi jenis.

Contoh berikut akan menerima {"foo": "string", "bar": 1}, tetapi menolak {"foo": "string", "bar": -1}, , {"foo": "", "bar": 1}atau objek apa pun tanpa foo properti atau bar .

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

Semua properti diperlukan kecuali definisi jenis properti memiliki "nullable": batasan true . Untuk membuat kedua properti dalam contoh sebelumnya opsional, ini akan terlihat seperti:

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

additionalProperties

Nilai adalah additionalProperties definisi jenis atau nilai boolean. Jika tidak ada additionalProperties batasan yang ditentukan, nilai defaultnya adalah true.

Jika nilai adalah definisi jenis, nilai menjelaskan skema yang diterapkan ke semua properti yang tidak disebutkan dalam properties batasan. Contoh berikut akan menerima {"fizz": "buzz", "foo": "bar"} tetapi menolak {"property": 1}.

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

Jika nilainya adalah false, tidak ada properti di luar properti yang ditentukan dalam properties batasan yang dapat disediakan. Contoh berikut akan menerima {"foo": "string", "bar": 1}, tetapi menolak {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

Jika nilainya adalah true, properti apa pun yang properties tidak ditentukan dalam batasan menerima nilai apa pun. Contoh berikut akan menerima {"foo": "string", "bar": 1, "fizz": "buzz"}.

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

diskriminator

Nilai discriminator menentukan skema apa yang akan diterapkan berdasarkan properti diskriminator. Contoh berikut akan menerima atau {"type": "ints", "foo": 1, "bar": 2}{"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, tetapi menolak {"type": "ints", "fizz": "buzz"}.

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

Batasan array

prefixItems

Nilai adalah prefixItems array definisi jenis. Setiap definisi jenis dalam nilai adalah skema yang akan digunakan untuk memvalidasi elemen array pada indeks yang sama. Contoh berikut akan menerima [1, true] tetapi menolak [1, "string"] atau [1]:

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

item

Nilai adalah items definisi jenis atau boolean. Jika tidak ada items batasan yang ditentukan, nilai defaultnya adalah true.

Jika nilai adalah definisi jenis, nilai menjelaskan skema yang diterapkan ke semua elemen array yang indeksnya lebih besar dari indeks terbesar batasan prefixItems . Contoh berikut akan menerima [1, true, 1] atau [1, true, 1, 1] tetapi menolak [1, true, "foo"]:

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

Anda dapat menggunakan items tanpa menggunakan prefixItems. Contoh berikut akan menerima [1, 2] atau [1] tetapi menolak ["foo"]:

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

Jika nilainya adalah false, array yang divalidasi harus memiliki panjang prefixItems yang sama persis dengan batasan. Contoh berikut akan menerima [1, true], tetapi menolak [1, true, 1], dan [1, true, false, "foo", "bar"].

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

Jika nilainya benar, elemen array yang indeksnya lebih besar dari indeks terbesar batasan prefixItems menerima nilai apa pun. Contoh berikut akan menerima [1, true], [1, true, 1] dan [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
}

batasan nullable

Batasan nullable menunjukkan bahwa nilai mungkin atau dihilangkan null . Lihat Properti untuk contoh.

Deskripsi

Anda dapat menambahkan deskripsi ke definisi jenis untuk membantu pengguna templat Anda memahami nilai yang akan disediakan.

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

Gunakan definisi

Untuk mereferensikan definisi jenis, gunakan sintaks berikut:

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

Contoh berikut menunjukkan cara mereferensikan definisi jenis dari parameter dan output:

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

Langkah berikutnya

Untuk mempelajari tentang properti yang tersedia untuk definisi jenis, lihat Memahami struktur dan sintaks templat ARM.

Bagikan melalui