Jenis data yang ditentukan pengguna di Bicep

Artikel
10/29/2024

Pelajari cara membuat jenis data yang ditentukan pengguna di Bicep. Untuk jenis data yang ditentukan sistem, lihat Jenis data. Menggunakan jenis data yang ditentukan pengguna secara otomatis mengaktifkan pembuatan kode bahasa versi 2.0 .

Bicep CLI versi 0.12.X atau yang lebih tinggi diperlukan untuk menggunakan fitur ini.

Tentukan jenis

Anda dapat menggunakan type pernyataan untuk membuat jenis data yang ditentukan pengguna. Anda juga dapat menggunakan ekspresi jenis di beberapa tempat untuk menentukan jenis kustom.

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

Dekorator @allowed hanya diizinkan pada param pernyataan. Untuk mendeklarasikan jenis dengan sekumpulan nilai yang telah ditentukan sebelumnya dalam type, gunakan sintaks jenis union.

Ekspresi jenis yang valid meliputi:

Referensi simbolis adalah pengidentifikasi yang merujuk ke jenis sekitar (seperti string atau int) atau simbol jenis yang ditentukan pengguna yang dideklarasikan dalam type pernyataan:
```
// Bicep data type reference
type myStringType = string

// user-defined type reference
type myOtherStringType = myStringType
```

Literal primitif, termasuk string, bilangan bulat, dan Boolean, adalah ekspresi jenis yang valid. Contohnya:

// a string type with three allowed values.
type myStringLiteralType = 'bicep' | 'arm' | 'azure'

// an integer type with one allowed value
type myIntLiteralType = 10

// an boolean type with one allowed value
type myBoolLiteralType = true

Anda dapat mendeklarasikan jenis array dengan menambahkan [] ke ekspresi jenis yang valid:

// A string type array
type myStrStringsType1 = string[]
// A string type array with three allowed values
type myStrStringsType2 = ('a' | 'b' | 'c')[]

type myIntArrayOfArraysType = int[][]

// A mixed-type array with four allowed values
type myMixedTypeArrayType = ('fizz' | 42 | {an: 'object'} | null)[]

Jenis objek berisi nol atau lebih properti di antara tanda kurung kurawal:
```
type storageAccountConfigType = {
  name: string
  sku: string
}
```
Setiap properti dalam objek terdiri dari kunci dan nilai yang dipisahkan oleh titik dua :. Kunci dapat berupa string apa pun, dengan nilai nonidentifier yang diapit dalam tanda kutip. Nilai dapat berupa semua jenis ekspresi.

Properti diperlukan kecuali memiliki penanda ? opsionalitas setelah nilai properti. Misalnya, sku properti dalam contoh berikut bersifat opsional:
```
type storageAccountConfigType = {
  name: string
  sku: string?
}
```
Anda dapat menggunakan dekorator pada properti. Anda dapat menggunakan tanda bintang (*) untuk membuat semua nilai memerlukan batasan. Anda dapat menentukan lebih banyak properti dengan menggunakan *. Contoh ini membuat objek yang memerlukan kunci jenis int bernama id. Semua entri lain dalam objek harus memiliki nilai string minimal 10 karakter.
```
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}
```
Sampel berikut menunjukkan cara menggunakan sintaks jenis union untuk mencantumkan sekumpulan nilai yang telah ditentukan sebelumnya:
```
type directions = 'east' | 'south' | 'west' | 'north'

type obj = {
  level: 'bronze' | 'silver' | 'gold'
}
```
Jenis objek dapat menggunakan rekursi langsung atau tidak langsung jika setidaknya kaki jalur ke titik rekursi bersifat opsional. Misalnya, myObjectType definisi dalam contoh berikut valid karena properti rekursif recursiveProp langsung bersifat opsional:
```
type myObjectType = {
  stringProp: string
  recursiveProp: myObjectType?
}
```
Definisi jenis berikut tidak akan valid karena tidak ada level1, , level2level3, level4, atau level5 opsional.
```
type invalidRecursiveObjectType = {
  level1: {
    level2: {
      level3: {
        level4: {
          level5: invalidRecursiveObjectType
        }
      }
    }
  }
}
```

Anda dapat menggunakan operator unary Bicep dengan bilangan bulat dan literal Boolean atau referensi ke simbol integer atau boolean yang ditik literal:

type negativeIntLiteral = -10
type negatedIntReference = -negativeIntLiteral

type negatedBoolLiteral = !true
type negatedBoolReference = !negatedBoolLiteral

Gabungan dapat menyertakan sejumlah ekspresi yang dititik harfiah. Jenis gabungan diterjemahkan ke dalam batasan nilai yang diizinkan di Bicep, sehingga hanya literal yang diizinkan sebagai anggota.
```
type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
```

Anda bisa menggunakan ekspresi jenis dalam type pernyataan, dan Anda juga bisa menggunakan ekspresi jenis untuk membuat jenis data yang ditentukan pengguna, seperti yang diperlihatkan di tempat-tempat berikut:

Sebagai klausa param jenis pernyataan. Contohnya:

param storageAccountConfig {
  name: string
  sku: string
}

: Mengikuti dalam properti jenis objek. Contohnya:

param storageAccountConfig {
 name: string
  properties: {
    sku: string
  }
} = {
  name: 'store$(uniqueString(resourceGroup().id)))'
  properties: {
    sku: 'Standard_LRS'
  }
}

[] Sebelum dalam ekspresi jenis array. Contohnya:

param mixedTypeArray ('fizz' | 42 | {an: 'object'} | null)[]

File Bicep umum untuk membuat akun penyimpanan terlihat seperti:

param location string = resourceGroup().location
param storageAccountName string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
])
param storageAccountSKU string = 'Standard_LRS'

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountSKU
  }
  kind: 'StorageV2'
}

Dengan jenis data yang ditentukan pengguna, jenis data dapat terlihat seperti:

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Menggunakan dekorator

Dekorator ditulis dalam format @expression dan ditempatkan di atas deklarasi jenis data yang ditentukan pengguna. Tabel berikut ini memperlihatkan dekorator yang tersedia untuk jenis data yang ditentukan pengguna.

Dekorator	Terapkan ke	Argumen	Deskripsi
description	all	string	Berikan deskripsi untuk jenis data yang ditentukan pengguna.
diskriminator	object	string	Gunakan dekorator ini untuk memastikan subkelas yang benar diidentifikasi dan dikelola.
ekspor	all	tidak ada	Menunjukkan bahwa jenis data yang ditentukan pengguna tersedia untuk diimpor oleh file Bicep lain.
maxLength	array, untai (karakter)	int	Panjang maksimum untuk jenis data string dan array. Nilainya inklusif.
maxValue	int	int	Nilai maksimum untuk jenis data bilangan bulat. Nilai ini inklusif.
metadata	all	object	Properti kustom untuk diterapkan ke jenis data. Dapat menyertakan properti deskripsi yang setara dengan dekorator deskripsi.
minLength	array, untai (karakter)	int	Panjang minimum untuk jenis data string dan array. Nilainya inklusif.
minValue	int	int	Nilai minimum untuk jenis data bilangan bulat. Nilai ini inklusif.
disegel	object	tidak ada	Tingkatkan BCP089 dari peringatan ke kesalahan ketika nama properti dari jenis data yang ditentukan pengguna kemungkinan salah ketik. Untuk informasi selengkapnya, lihat Meningkatkan tingkat kesalahan.
aman	untai (karakter), objek	tidak ada	Menandai jenis sebagai aman. Nilai untuk jenis aman tidak disimpan ke riwayat penyebaran dan tidak dicatat. Untuk informasi lebih lanjut, lihat Untai (karakter) dan objek yang aman.

Dekotaror berada dalam namespace layanan sys. Jika Anda perlu membedakan suatu dekorator dari item lainnya dengan nama yang sama, awali dekorator dengan sys. Misalnya, jika file Bicep Anda menyertakan variabel bernama description, Anda harus menambahkan sys namespace saat Anda menggunakan description dekorator.

Diskriminator

Lihat Jenis data union yang ditandai.

Deskripsi

Tambahkan deskripsi ke jenis data yang ditentukan pengguna. Anda dapat menggunakan dekorator pada properti. Contohnya:

@description('Define a new object type.')
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}

Anda dapat menggunakan teks berformat Markdown untuk teks deskripsi.

Ekspor

Gunakan @export() untuk berbagi jenis data yang ditentukan pengguna dengan file Bicep lainnya. Untuk informasi selengkapnya, lihat Mengekspor variabel, jenis, dan fungsi.

Batasan bilangan bulat

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

@minValue(1)
@maxValue(12)
type month int

Batasan panjang

Anda dapat menentukan panjang minimum dan maksimum untuk 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 jenis. Salah satu jenisnya adalah untuk nama akun penyimpanan yang harus memiliki 3 hingga 24 karakter. Jenis lainnya adalah array yang harus memiliki dari satu hingga lima item.

@minLength(3)
@maxLength(24)
type storageAccountName string

@minLength(1)
@maxLength(5)
type appNames array

Metadata

Jika Anda memiliki properti kustom yang ingin Anda terapkan ke jenis data yang ditentukan pengguna, tambahkan dekorator metadata. Dalam metadata, tentukan objek dengan nama dan nilai kustom. Objek yang Anda tentukan untuk metadata dapat berisi properti nama dan jenis apa pun.

Anda mungkin menggunakan dekorator ini untuk melacak informasi tentang jenis data yang tidak masuk akal untuk ditambahkan ke deskripsi.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
type settings object

Ketika Anda menyediakan @metadata() dekorator dengan properti yang bertentangan dengan dekorator lain, dekorator itu selalu lebih diutamakan daripada apa pun di @metadata() dekorator. Jadi, properti yang bertentangan dalam @metadata() nilai berlebihan dan diganti. Untuk informasi selengkapnya, lihat Tidak ada metadata yang bertentangan.

Disegel

Lihat Meningkatkan tingkat kesalahan.

Jenis aman

Anda dapat menandai string atau jenis data yang ditentukan pengguna sebagai aman. Nilai jenis aman tidak disimpan ke riwayat penyebaran dan tidak dicatat.

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Tingkatkan tingkat kesalahan

Secara default, mendeklarasikan jenis objek di Bicep memungkinkannya untuk menerima lebih banyak properti dari jenis apa pun. Misalnya, Bicep berikut valid tetapi menimbulkan peringatan [BCP089]: The property "otionalProperty" is not allowed on objects of type "{ property: string, optionalProperty: null | string }". Did you mean "optionalProperty"?:

type anObject = {
  property: string
  optionalProperty: string?
}
 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

Peringatan memberi tahu Anda bahwa anObject jenis tidak menyertakan properti bernama otionalProperty. Meskipun tidak ada kesalahan yang terjadi selama penyebaran, kompilator Bicep mengasumsikan bahwa otionalProperty itu adalah kesalahan ketik dan bahwa Anda bermaksud menggunakan optionalProperty tetapi salah eja. Bicep memperingatkan Anda terhadap inkonsistensi.

Untuk meningkatkan peringatan ini ke kesalahan, terapkan @sealed() dekorator ke jenis objek:

@sealed() 
type anObject = {
  property: string
  optionalProperty?: string
}

Anda mendapatkan hasil yang sama dengan menerapkan @sealed() dekorator ke param deklarasi:

type anObject = {
  property: string
  optionalProperty: string?
}
 
@sealed() 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

Mesin penyebaran Azure Resource Manager juga memeriksa jenis yang disegel untuk properti lain. Menyediakan properti tambahan untuk parameter yang disegel menghasilkan kesalahan validasi, yang menyebabkan penyebaran gagal. Contohnya:

@sealed()
type anObject = {
  property: string
}

param aParameter anObject = {
  property: 'value'
  optionalProperty: 'value'
}

Jenis data union bertag

Untuk mendeklarasikan jenis data gabungan yang ditandai kustom dalam file Bicep, Anda dapat menempatkan discriminator dekorator di atas deklarasi jenis yang ditentukan pengguna. Bicep CLI versi 0.21.X atau yang lebih tinggi diperlukan untuk menggunakan dekorator ini. Contoh berikut menunjukkan cara mendeklarasikan jenis data serikat yang ditandai:

type FooConfig = {
  type: 'foo'
  value: int
}

type BarConfig = {
  type: 'bar'
  value: bool
}

@discriminator('type')
type ServiceConfig = FooConfig | BarConfig | { type: 'baz', *: string }

param serviceConfig ServiceConfig = { type: 'bar', value: true }

output config object = serviceConfig

Untuk informasi selengkapnya, lihat Jenis data union yang ditandai kustom.

Untuk daftar jenis data Bicep, lihat Jenis data.

Bagikan melalui

Jenis data yang ditentukan pengguna di Bicep

Tentukan jenis

Menggunakan dekorator

Diskriminator

Deskripsi

Ekspor

Batasan bilangan bulat

Batasan panjang

Metadata

Disegel

Jenis aman

Tingkatkan tingkat kesalahan

Jenis data union bertag

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Jenis data yang ditentukan pengguna di Bicep

Tentukan jenis

Menggunakan dekorator

Diskriminator

Deskripsi

Ekspor

Batasan bilangan bulat

Batasan panjang

Metadata

Disegel

Jenis aman

Tingkatkan tingkat kesalahan

Jenis data union bertag

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: