Datentypen in Bicep

In diesem Artikel werden die in Bicep unterstützten Datentypen beschrieben. Informationen zum Definieren benutzerdefinierter Datentypen finden Sie unter Benutzerdefinierte Datentypen.

Unterstützte Typen

In einer Bicep-Vorlage können Sie die folgenden Datentypen verwenden:

• array
• bool
• int
• object
• secureObject – durch Decorator in Bicep angegeben
• secureString – durch Decorator in Bicep angegeben
• string

Arrays

Arrays beginnen mit einer linken eckigen Klammer ([) und enden mit einer rechten eckigen Klammer (]). In Bicep kann ein Array in einer einzelnen Zeile oder in mehreren Zeilen deklariert werden. Kommas (,) werden zwischen Werten in einzeiligen Deklarationen, aber nicht in mehrzeiligen Deklarationen verwendet. Sie können einzeilige und mehrzeilige Deklarationen kombinieren. Für mehrzeilige Deklarationen ist Bicep CLI Version 0.7.X oder höher erforderlich.

var multiLineArray = [
  'abc'
  'def'
  'ghi'
]

var singleLineArray = ['abc', 'def', 'ghi']

var mixedArray = ['abc', 'def'
    'ghi']

Jedes Arrayelement kann beliebiger Art sein. Sie können über ein Array verfügen, in dem jedes Element denselben Datentyp hat, oder ein Array, das unterschiedliche Datentypen enthält.

Das folgende Beispiel zeigt ein Array von ganzen Zahlen und ein Array verschiedener Typen.

var integerArray = [
  1
  2
  3
]

var mixedArray = [
  resourceGroup().name
  1
  true
  'example string'
]

Arrays in Bicep sind nullbasiert. Beispielsweise ergibt der Ausdruck exampleArray[0] den Wert 1 und exampleArray[2] entspricht 3. Der Index des Indexers kann ein anderer Ausdruck sein. Der Ausdruck exampleArray[index] wird zu 2 ausgewertet. Ganzzahlige Indexer sind nur für den Ausdruck von Arraytypen zulässig.

var index = 1

var exampleArray = [
  1
  2
  3
]

Die folgende Fehlermeldung wird angezeigt, wenn der Index außerhalb der Grenzen liegt:

The language expression property array index 'x' is out of bounds

Um diese Ausnahme zu vermeiden, können Sie den logischen Operator „Or“ verwenden, wie im folgenden Beispiel gezeigt:

param emptyArray array = []
param numberArray array = [1, 2, 3]

output foo bool = empty(emptyArray) || emptyArray[0] == 'bar'
output bar bool = length(numberArray) <= 3 || numberArray[3] == 4

Boolesche Werte

Wenn Sie boolesche Werte angeben, verwenden Sie true oder false. Umschließen Sie den Wert nicht mit Anführungszeichen.

param exampleBool bool = true

Ganze Zahlen

Wenn Sie ganzzahlige Werte angeben, verwenden Sie keine Anführungszeichen.

param exampleInt int = 1

Bicep ganze Zahlen sind 64-Bit-Ganzzahlen. Wenn sie als Inlineparameter übergeben werden, kann der Wertebereich durch das SDK oder befehlszeilentool beschränkt werden, das Sie für die Bereitstellung verwenden. Wenn Sie beispielsweise PowerShell zum Bereitstellen eines Bicep verwenden, können Integertypen im Bereich von -2147483648 bis 2147483647 liegen. Um diese Einschränkung zu vermeiden, geben Sie große Werte in einer Parameterdatei an. Ressourcentypen wenden ihre eigenen Grenzwerte für Integereigenschaften an.

Bicep unterstützt einen ganzzahligen Literaltyp, der auf einen bestimmten Wert verweist, der eine genaue ganze Zahl ist. Im folgenden Beispiel ist 1 ein ganzzahliger Literaltyp, foo kann nur dem Wert 1 und keinem anderen Wert zugewiesen werden.

output foo 1 = 1

Ein ganzzahliger Literaltyp kann entweder inline deklariert werden, wie im vorherigen Beispiel gezeigt, oder in einer type Anweisung.

type oneType = 1

output foo oneType = 1
output bar oneType = 2

Im vorherigen Beispiel führt das Zuweisen von 2 zu Balken zu einem BCP033-Fehler – Erwarteter Wert vom Typ "1", der angegebene Wert ist jedoch vom Typ "2".

Das folgende Beispiel zeigt die Verwendung eines ganzzahligen Literaltyps mit Union-Typ:

output bar 1 | 2 | 3 = 3

Gleitkomma-, Dezimal- oder Binärformate werden derzeit nicht unterstützt.

Objekte

Objekte beginnen mit einer linken geschweiften Klammer ({) und enden mit einer rechten geschweiften Klammer (}). In Bicep kann ein Objekt in einer einzelnen Zeile oder in mehreren Zeilen deklariert werden. Jede Eigenschaft in einem Objekt besteht aus einem Schlüssel und einem Wert. Der Schlüssel und der Wert werden durch einen Doppelpunkt (:) getrennt. Ein Objekt lässt beliebige Eigenschaften jedes Typs zu. Kommas (,) werden zwischen Eigenschaften für einzeilige Deklarationen, aber nicht zwischen Eigenschaften für mehrzeilige Deklarationen verwendet. Sie können einzeilige und mehrzeilige Deklarationen kombinieren. Für mehrzeilige Deklarationen ist Bicep CLI Version 0.7.X oder höher erforderlich.

param singleLineObject object = {name: 'test name', id: '123-abc', isCurrent: true, tier: 1}

param multiLineObject object = {
  name: 'test name'
  id: '123-abc'
  isCurrent: true
  tier: 1
}

param mixedObject object = {name: 'test name', id: '123-abc', isCurrent: true
    tier: 1}

In Bicep sind Anführungszeichen für die Schlüssel von Objekteigenschaften optional zulässig:

var test = {
  'my - special. key': 'value'
}

Im vorangegangenen Beispiel werden Anführungszeichen verwendet, wenn die Objektschlüssel Sonderzeichen enthalten. Zum Beispiel Leerzeichen, '-' oder '.'. Das folgende Beispiel zeigt, wie Sie die Interpolation in Objekt-Eigenschaftsschlüsseln verwenden können.

var stringVar = 'example value'
var objectVar = {
  '${stringVar}': 'this value'
}

Eigenschaftenaccessoren werden verwendet, um auf Eigenschaften eines Objekts zuzugreifen. Sie werden mit dem .-Operator erstellt.

var a = {
  b: 'Dev'
  c: 42
  d: {
    e: true
  }
}

output result1 string = a.b // returns 'Dev'
output result2 int = a.c // returns 42
output result3 bool = a.d.e // returns true

Eigenschaftenaccessoren können mit jedem Objekt verwendet werden, einschließlich Parametern und Variablen von Objekttypen sowie Objektliteralen. Die Verwendung eines Eigenschaftsaccessors für einen Ausdruck des Nichtobjekttyps ist ein Fehler.

Sie können auch die Syntax [] für den Zugriff auf eine Eigenschaft verwenden. Im folgenden Beispiel wird Development zurückgegeben.

var environmentSettings = {
  dev: {
    name: 'Development'
  }
  prod: {
    name: 'Production'
  }
}

output accessorResult string = environmentSettings['dev'].name

In JSON ist ein Objekt eine nicht geordnete Auflistung von null oder mehr Schlüssel-Wert-Paaren. Die Reihenfolge kann je nach Implementierung unterschiedlich sein. Die Items()-Funktion von Bicep sortiert die Objekte beispielsweise in alphabetischer Reihenfolge. An anderen Stellen kann die ursprüngliche Reihenfolge beibehalten werden. Aufgrund dieses Nicht-Determinismus sollten Sie beim Schreiben von Code, der mit den Parametern und Ausgaben der Bereitstellung interagiert, keine Annahmen über die Reihenfolge der Objektschlüssel anstellen.

Beim Zugriff auf eine nicht vorhandene Eigenschaft eines Objekts erhalten Sie den folgenden Fehler:

The language expression property 'foo' doesn't exist

Um diese Ausnahme zu vermeiden, können Sie den logischen Operator „And“ verwenden, wie im folgenden Beispiel gezeigt:

param objectToTest object = {
  one: 1
  two: 2
  three: 3
}

output bar bool = contains(objectToTest, 'four') && objectToTest.four == 4

Zeichenfolgen

In Bicep werden Zeichenfolgen mit einfachen Anführungszeichen markiert und müssen in einer einzelnen Zeile deklariert werden. Alle Unicode-Zeichen mit Codepunkten zwischen 0 und 10FFFF sind zulässig.

param exampleString string = 'test value'

In der folgenden Tabelle sind die reservierten Zeichen aufgeführt, die mit einem schrägen Schrägstrich (\) mit Escapezeichen geschützt werden müssen:

// evaluates to "what's up?"
var myVar = 'what\'s up?'

Bicep unterstützt Zeichenfolgenliteraltyp, der auf einen bestimmten Zeichenfolgenwert verweist. Im folgenden Beispiel ist Rot ein Zeichenfolgenliteraltyp, "redColor " kann nur dem Wert rot und keinem anderen Wert zugewiesen werden.

output redColor 'red' = 'red'

Ein Zeichenfolgenliteraltyp kann entweder inline deklariert werden, wie im vorherigen Beispiel gezeigt, oder in einer type Anweisung.

type redColor = 'red'

output colorRed redColor = 'red'
output colorBlue redColor = 'blue'

Im vorherigen Beispiel führt das Zuweisen von Blau zu colorBlue zu einem BCP033-Fehler : Erwartet einen Wert vom Typ "'rot'", der angegebene Wert ist jedoch vom Typ "'blue'".

Das folgende Beispiel zeigt die Verwendung des Zeichenfolgenliteraltyps mit dem Union-Typ:

type direction = 'north' | 'south' | 'east' | 'west'

output west direction = 'west'
output northWest direction = 'northwest'

Alle Zeichenfolgen in Bicep unterstützen Interpolation. Um einen Ausdruck einzufügen, umschließen Sie ihn mit ${ und }. Ausdrücke, auf die verwiesen wird, können sich nicht über mehrere Zeilen erstrecken.

var storageName = 'storage${uniqueString(resourceGroup().id)}'

Mehrzeilige Zeichenfolgen

In Bicep werden Multi-Linienzeichenfolgen zwischen drei einfachen Anführungszeichen (''') definiert, auf die optional ein Zeilenumbruch (die öffnende Sequenz) folgt, und drei einfache Anführungszeichen (''' – die schließende Sequenz). Zeichen, die zwischen der öffnenden und der schließenden Sequenz eingegeben werden, werden wörtlich gelesen, und es ist kein Schutz mit Escapezeichen erforderlich oder möglich.

// evaluates to "hello!"
var myVar = '''hello!'''

// evaluates to "hello!" because the first newline is skipped
var myVar2 = '''
hello!'''

// evaluates to "hello!\n" because the final newline is included
var myVar3 = '''
hello!
'''

// evaluates to "  this\n    is\n      indented\n"
var myVar4 = '''
  this
    is
      indented
'''

// evaluates to "comments // are included\n/* because everything is read as-is */\n"
var myVar5 = '''
comments // are included
/* because everything is read as-is */
'''

// evaluates to "interpolation\nis ${blocked}"
// note ${blocked} is part of the string, and is not evaluated as an expression
var myVar6 = '''interpolation
is ${blocked}'''

Union-Datentypen

In Bicep ermöglicht ein Union-Typ die Erstellung eines kombinierten Typs, der aus einer Gruppe von Untertypen besteht. Eine Zuordnung ist gültig, wenn eine der einzelnen Untertypzuweisungen zulässig ist. Das | Zeichen trennt einzelne Untertypen durch eine oder eine Bedingung. Die Syntax 'a' | "b" bedeutet, dass eine gültige Zuordnung entweder "a" oder "b" sein könnte. Union-Typen werden in Bicep in die Einschränkung für zulässige Werte übersetzt, sodass nur Literale als Elemente zulässig sind. Unions können eine beliebige Anzahl von Literalausdrücken enthalten.

type color = 'Red' | 'Blue' | 'White'
type trueOrFalse = 'true' | 'false'
type permittedIntegers = 1 | 2 | 3
type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]

Typgewerkschaften müssen auf einen einzelnen ARM-Typ wie "string", "int" oder "bool" zurückgeführt werden. Andernfalls erhalten Sie den BCP294-Fehlercode . Zum Beispiel:

type foo = 'a' | 1

Jeder Typausdruck kann als Untertyp in einer Union-Typdeklaration (zwischen | Zeichen) verwendet werden. Die folgenden Beispiele sind beispielsweise gültig:

type foo = 1 | 2
type bar = foo | 3
type baz = bar | (4 | 5) | 6

Benutzerdefinierter Union-Datentyp

Bicep unterstützt benutzerdefinierten markierten Union-Datentyp, der verwendet wird, um einen Wert darzustellen, der einen von mehreren verschiedenen Typen sein kann. Um einen benutzerdefinierten getaggten Union-Datentyp zu deklarieren, können Sie einen @discriminator() Dekorateur verwenden. Um dieses Decorator-Element nutzen zu können, ist Bicep CLI Version 0.21.X oder höher erforderlich. Die Syntax lautet:

@discriminator('<property-name>')

Das Decorator-Element für den Diskriminator akzeptiert einen einzelnen Parameter, der einen freigegebenen Eigenschaftsnamen zwischen allen Union-Membern darstellt. Bei diesem Eigenschaftsnamen muss es sich um ein erforderliches Zeichenfolgenliteral für alle Member handeln, wobei die Groß-/Kleinschreibung beachtet wird. Die Werte der unterscheidenden Eigenschaft für die Union-Member müssen eindeutig sein, wobei die Groß-/Kleinschreibung nicht beachtet werden muss.

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

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

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

Der Parameterwert wird basierend auf dem unterscheidenden Eigenschaftswert überprüft. Wenn der Parameter "serviceConfig" z. B. im vorherigen Beispiel vom Typ "foo" ist, wird er mithilfe des FooConfig-Typs überprüft. Ebenso wird der Parameter mithilfe des BarConfig-Typs überprüft, wenn der Parameter vom Typ "Typ" ist. Dieses Muster gilt auch für andere Typen.

Es gibt einige Einschränkungen beim Union-Typ.

• Union-Typen müssen auf einen einzelnen Azure Resource Manager (ARM)-Typ zurückgeführt werden. Die folgende Definition ist ungültig:

  type foo = 'a' | 1
  

• Nur Literale sind als Member zulässig.

• Alle Literale müssen denselben primitiven Datentyp aufweisen (z. B. alle Zeichenfolgen oder alle ganzen Zahlen).

Die Union-Typsyntax kann in benutzerdefinierten Datentypen verwendet werden.

Sichere Zeichenfolgen und Objekte

Die sichere Zeichenfolge verwendet das gleiche Format wie die Zeichenfolge, und das sichere Objekt verwendet das gleiche Format wie das Objekt. Mit Bicep fügen Sie den @secure() Dekorateur zu einer Zeichenfolge oder einem Objekt hinzu.

Wenn Sie einen Parameter auf eine sichere Zeichenfolge oder ein sicheres Objekt festlegen, wird der Wert des-Parameters weder im Bereitstellungsverlauf gespeichert noch protokolliert. Wenn Sie diesen sicheren Wert jedoch auf eine Eigenschaft festlegen, die keinen sicheren Wert erwartet, wird der Wert nicht geschützt. Wenn Sie z. B. eine sichere Zeichenfolge auf ein Tag festlegen, wird dieser Wert als reiner Text gespeichert. Verwenden Sie sichere Zeichenfolgen für Kennwörter und Geheimnisse.

Das folgende Beispiel zeigt zwei sichere Parameter:

@secure()
param password string

@secure()
param configValues object

Zuweisbarkeit von Datentypen

In Bicep kann ein Wert eines Typs (Quelltyp) einem anderen Typ (Zieltyp) zugewiesen werden. Die folgende Tabelle zeigt, welcher Quelltyp (horizontal aufgelistet) welchem Zieltyp (vertikal aufgelistet) zugewiesen werden kann oder nicht. In der Tabelle bedeutet X zuweisbar, eine Leerstelle bedeutet nicht zuweisbar, und ? bedeutet nur, wenn die Typen kompatibel sind.

Nächste Schritte

Informationen zur Struktur und Syntax von Bicep finden Sie unter Bicep-Dateistruktur.