Uživatelem definované datové typy v Bicep

Článek
10/29/2024

Naučte se vytvářet uživatelem definované datové typy v Bicep. Informace o systémově definovaných datových typech najdete v tématu Datové typy. Použití uživatelem definovaných datových typů automaticky povolí generování kódu verze 2.0 .

K použití této funkce se vyžaduje rozhraní příkazového řádku Bicep verze 0.12.X nebo vyšší .

Definování typů

Tento příkaz můžete použít type k vytvoření uživatelem definovaných datových typů. K definování vlastních typů můžete také použít výrazy typu na některých místech.

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

Dekorátor @allowed je povolen pouze u param příkazů. Chcete-li deklarovat typ se sadou předdefinovaných hodnot v příkazu type, použijte syntaxi sjednocovacího typu.

Mezi platné výrazy typu patří:

Symbolické odkazy jsou identifikátory, které odkazují na okolní typ (například string nebo int) nebo symbol definovaného uživatelem type deklarovaný v příkazu:
```
// Bicep data type reference
type myStringType = string

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

Primitivní literály, včetně řetězců, celých čísel a logických hodnot, jsou platné výrazy typu. Příklad:

// 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

Typy polí můžete deklarovat [] připojením k libovolnému platnému výrazu typu:

// 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)[]

Typy objektů obsahují nula nebo více vlastností mezi složenými závorkami:
```
type storageAccountConfigType = {
  name: string
  sku: string
}
```
Každá vlastnost v objektu se skládá z klíče a hodnoty oddělené dvojtečku :. Klíč může být libovolný řetězec s neidentifikátorovými hodnotami uzavřenými v uvozovkách. Hodnota může být libovolný typ výrazu.

Vlastnosti jsou vyžadovány, pokud nemají za hodnotou vlastnosti značku ? volitelné vlastnosti. Například vlastnost v následujícím příkladu sku je volitelná:
```
type storageAccountConfigType = {
  name: string
  sku: string?
}
```
Dekorátory můžete použít u vlastností. Pomocí hvězdičky (*) můžete nastavit, aby všechny hodnoty vyžadovaly omezení. Pomocí .* Tento příklad vytvoří objekt, který vyžaduje klíč typu int s názvem id. Všechny ostatní položky v objektu musí být řetězcová hodnota minimálně 10 znaků dlouhá.
```
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}
```
Následující ukázka ukazuje, jak pomocí syntaxe sjednocovacího typu vypsat sadu předdefinovaných hodnot:
```
type directions = 'east' | 'south' | 'west' | 'north'

type obj = {
  level: 'bronze' | 'silver' | 'gold'
}
```
Typy objektů můžou používat přímé nebo nepřímé rekurze, pokud je nepovinná alespoň noha cesty k bodu rekurze. Například definice v následujícím příkladu myObjectType je platná, protože přímo rekurzivní recursiveProp vlastnost je volitelná:
```
type myObjectType = {
  stringProp: string
  recursiveProp: myObjectType?
}
```
Následující definice typu by nebyla platná, protože žádná z level1, level2, level3, level4, nebo level5 je nepovinná.
```
type invalidRecursiveObjectType = {
  level1: {
    level2: {
      level3: {
        level4: {
          level5: invalidRecursiveObjectType
        }
      }
    }
  }
}
```

Unární operátory Bicep můžete použít s celočíselnou a logickou literály nebo odkazy na celočíselné nebo logické symboly literálů:

type negativeIntLiteral = -10
type negatedIntReference = -negativeIntLiteral

type negatedBoolLiteral = !true
type negatedBoolReference = !negatedBoolLiteral

Sjednocení můžou obsahovat libovolný počet výrazů typu literál. Typy sjednocení se překládají do omezení povolené hodnoty v Bicep, takže jako členy jsou povoleny pouze literály.
```
type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
```

V příkazu můžete použít výrazy type typu a pomocí výrazů typů můžete také vytvářet uživatelsky definované datové typy, jak je znázorněno na následujících místech:

Jako klauzule param typu příkazu. Příklad:

param storageAccountConfig {
  name: string
  sku: string
}

Následuje za : vlastností typu objektu. Příklad:

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

[] Předchází výrazu typu pole. Příklad:

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

Typický soubor Bicep pro vytvoření účtu úložiště vypadá takto:

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'
}

U uživatelem definovaných datových typů to může vypadat takto:

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'
}

Použití dekorátorů

Dekorátory jsou zapsány ve formátu @expression a jsou umístěny nad deklaracemi uživatelem definovaného datového typu. Následující tabulka uvádí dostupné dekorátory pro uživatelem definované datové typy.

Dekoratér	Platí pro	Argument	Popis
popis	vše	string	Zadejte popis uživatelem definovaného datového typu.
diskriminátor	objekt	string	Pomocí tohoto dekorátoru se ujistěte, že je identifikována a spravována správná podtřída.
export	vše	Žádná	Označuje, že uživatelem definovaný datový typ je k dispozici pro import jiným souborem Bicep.
maxLength	array, string	int	Maximální délka datových typů řetězců a polí. Hodnota je inkluzivní.
maxValue	int	int	Maximální hodnota datových typů celých čísel. Tato hodnota je inkluzivní.
metadata	vše	objekt	Vlastní vlastnosti, které se mají použít u datových typů. Může obsahovat vlastnost popisu, která odpovídá dekorátoru popisu.
minLength	array, string	int	Minimální délka datových typů řetězců a polí. Hodnota je inkluzivní.
minValue	int	int	Minimální hodnota datových typů celé číslo. Tato hodnota je inkluzivní.
sealed	objekt	Žádná	Zvýšení úrovně BCP089 z upozornění na chybu, pokud je název vlastnosti uživatelem definovaného datového typu pravděpodobně překlep. Další informace naleznete v tématu Zvýšení úrovně chyby.
zajistit	string, object	Žádná	Označí typy jako bezpečné. Hodnota zabezpečeného typu se neuloží do historie nasazení a nezaprotokoluje se. Další informace naleznete v tématu Zabezpečení řetězců a objektů.

Dekorátory jsou v oboru názvů sys. Pokud potřebujete odlišit dekorátor od jiné položky se stejným názvem, předkožte dekorátorem .sys Pokud například váš soubor Bicep obsahuje proměnnou s názvem description, musíte přidat sys obor názvů při použití dekorátoru description .

Diskriminátor

Viz Označení sjednocovacího datového typu.

Popis

Přidejte popis k uživatelem definovanému datovému typu. Dekorátory můžete použít u vlastností. Příklad:

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

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

Pro text popisu můžete použít text ve formátu Markdownu.

Export

Slouží @export() ke sdílení uživatelem definovaného datového typu s jinými soubory Bicep. Další informace najdete v tématu Export proměnných, typů a funkcí.

Celočíselná omezení

Pro celočíselné typy můžete nastavit minimální a maximální hodnoty. Můžete nastavit jedno nebo obě omezení.

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

Omezení délky

Pro typy řetězců a polí můžete zadat minimální a maximální délku. Můžete nastavit jedno nebo obě omezení. U řetězců délka označuje počet znaků. U polí určuje délka počet položek v matici.

Následující příklad deklaruje dva typy. Jedním typem je název účtu úložiště, který musí mít 3 až 24 znaků. Druhým typem je pole, které musí mít jednu až pět položek.

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

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

Metadata

Pokud máte vlastní vlastnosti, které chcete použít u uživatelem definovaného datového typu, přidejte dekorátor metadat. V metadatech definujte objekt s vlastními názvy a hodnotami. Objekt, který definujete pro metadata, může obsahovat vlastnosti libovolného názvu a typu.

Tento dekorátor můžete použít ke sledování informací o datovém typu, který nemá smysl přidat do popisu.

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

Když poskytnete @metadata() dekorátoru vlastnost, která je v konfliktu s jiným dekorátorem, má tento dekorátor vždy přednost před čímkoli v dekorátoru @metadata() . Konfliktní vlastnost v rámci @metadata() hodnoty je tedy redundantní a je nahrazena. Další informace naleznete v tématu Žádné konfliktní metadata.

Zapečetěný

Viz Úroveň chyby Zvýšení úrovně.

Typy zabezpečení

Jako zabezpečený můžete označit řetězec nebo objektově definovaný datový typ. Hodnota zabezpečeného typu se neuloží do historie nasazení a nezaprotokoluje se.

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Zvýšení úrovně chyb

Ve výchozím nastavení deklarování typu objektu v Bicep umožňuje přijmout více vlastností libovolného typu. Například následující bicep je platný, ale vyvolá upozornění [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'
}

Upozornění vás informuje, že anObject typ neobsahuje vlastnost s názvem otionalProperty. I když během nasazování nedojde k žádným chybám, kompilátor Bicep předpokládá, že otionalProperty jde o překlep a že jste ho chtěli použít optionalProperty , ale chybně napsaný. Bicep vás upozorní na nekonzistence.

Chcete-li eskalovat tato upozornění na chyby, použijte @sealed() dekorátor na typ objektu:

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

Stejné výsledky získáte použitím @sealed() dekorátoru param na deklaraci:

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

Modul nasazení Azure Resource Manager také kontroluje zapečetěné typy dalších vlastností. Poskytnutím jakýchkoli dalších vlastností zapečetěných parametrů dojde k chybě ověření, která způsobí selhání nasazení. Příklad:

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

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

Označený sjednocovaný datový typ

Pokud chcete deklarovat vlastní sjednocovací datový typ v souboru Bicep, můžete umístit discriminator dekorátor nad deklaraci typu definované uživatelem. K použití tohoto dekorátoru se vyžaduje rozhraní příkazového řádku Bicep verze 0.21.X nebo vyšší . Následující příklad ukazuje, jak deklarovat označený sjednocovacího datového typu:

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

Další informace naleznete v tématu Vlastní označený sjednocovacího datového typu.

Seznam datových typů Bicep najdete v tématu Datové typy.

Sdílet prostřednictvím

Uživatelem definované datové typy v Bicep

Definování typů

Použití dekorátorů

Diskriminátor

Popis

Export

Celočíselná omezení

Omezení délky

Metadata

Zapečetěný

Typy zabezpečení

Zvýšení úrovně chyb

Označený sjednocovaný datový typ

Váš názor

Další materiály

Sdílet prostřednictvím

Uživatelem definované datové typy v Bicep

Definování typů

Použití dekorátorů

Diskriminátor

Popis

Export

Celočíselná omezení

Omezení délky

Metadata

Zapečetěný

Typy zabezpečení

Zvýšení úrovně chyb

Označený sjednocovaný datový typ

Související obsah

Váš názor

Další materiály