Uživatelem definované datové typy v Bicep

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@2025-06-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@2025-06-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	Důvod	Popis
popis	vše	řetězec	Zadejte popis uživatelem definovaného datového typu.
diskriminátor	objekt	řetězec	Pomocí tohoto dekorátoru se ujistěte, že je identifikována a spravována správná podtřída.
exportu	vše	Žádná	Označuje, že uživatelem definovaný datový typ je k dispozici pro import jiným souborem Bicep.
maxLength	pole, řetězec	int (integer)	Maximální délka datových typů řetězců a polí. Hodnota je inkluzivní.
maxValue	int (integer)	int (integer)	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	pole, řetězec	int (integer)	Minimální délka datových typů řetězců a polí. Hodnota je inkluzivní.
minValue	int (integer)	int (integer)	Minimální hodnota datových typů celé číslo. Tato hodnota je inkluzivní.
zapečetěno	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	řetězec, objekt	Žá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.

Vývoz

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

Metadatové informace

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.

Typy odvozené od zdrojů

Bicep umožňuje odvozovat typy přímo ze schémat prostředků Azure pomocí konstruktorů resourceInput<> a resourceOutput<>. Typy odvozené od prostředků umožňují zkontrolovat parametry a proměnné proti části těla prostředku namísto pomocí vlastního typu. K použití těchto konstruktorů se vyžaduje rozhraní příkazového řádku Bicep verze 0.34.1 nebo vyšší.

Šablony můžou opakovaně používat typy prostředků všude, kde se očekává typ.

resourceInput<'type@version'>

resourceInput<>: Představuje zapisovatelné vlastnosti typu prostředku, které odstraní všechny vlastnosti označené jako ReadOnly ve schématu šablony ARM. Používá typ (například datový typ), který musíte předat při deklaraci prostředku.

resourceOutput<'type@version'>

resourceOutput<>: Představuje čitelné vlastnosti typu prostředku, které odstraní všechny vlastnosti označené jako WriteOnly ve schématu šablony ARM. Odpovídá typu hodnoty vrácené po zřízení prostředku.

Můžete použít resourceInput<> nebo resourceOutput<> ke extrakci pouze části schématu prostředků. Pokud například chcete zadat proměnnou nebo parametr na základě pouze určitého kind nebo properties účtu úložiště:

type accountKind = resourceInput<'Microsoft.Storage/storageAccounts@2024-01-01'>.kind

Předchozí příklad je ekvivalentní:

type accountKind = 'BlobStorage' | 'BlockBlobStorage' | 'FileStorage' | 'Storage' | 'StorageV2'

Následující příklad ukazuje, jak použít resourceInput<> k vytvoření typového parametru na základě properties prostředku účtu úložiště. To vám umožní definovat parametr, který odpovídá zapisovatelným vlastnostem účtu úložiště, jako jsou například accessTier, minimumTlsVersion a další vlastnosti.

// Typed parameter using the .properties path of a storage account
param storageAccountProps resourceInput<'Microsoft.Storage/storageAccounts@2023-01-01'>.properties = {
  accessTier: 'Hot'
  minimumTlsVersion: 'TLS1_2'
  allowBlobPublicAccess: false
  supportsHttpsTrafficOnly: true
}

// Resource declaration using the typed parameter
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'mystorageacct123'
  location: resourceGroup().location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: storageAccountProps
}

Následující příklad ukazuje, jak použít resourceOutput<> k vytvoření typového výstupu na základě primaryEndPoints prostředku účtu úložiště.

output storageEndpoints resourceOutput<'Microsoft.Storage/storageAccounts@2024-01-01'>.properties.primaryEndpoints = ...

Na rozdíl od uživatelem definovaných datových typů Bicep kontroluje odvozené typy prostředků při úpravách nebo kompilaci souboru, ale služba ARM je nekontroluje.

Související obsah

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