Ressourcenfunktionen für Bicep

In diesem Artikel werden die Bicep Funktionen zum Abrufen von Ressourcenwerten beschrieben.

Informationen zum Abrufen von Werten aus der aktuellen Bereitstellung finden Sie unter Funktionen für Bereitstellungswerte.

Der this Namensraum

Der this Namensraum stellt Funktionen zur Ressourcenzustandserkennung zur Laufzeit innerhalb einer Ressourcendefinition bereit. Diese Funktionen ermöglichen es Ihrer Vorlage, ihre Konfiguration entsprechend anzupassen, ob bereits eine Ressource in der Umgebung existiert.

• this.exists(): Gibt einen Bool-Wert zurück, der angibt, ob die Ressource derzeit existiert.
• this.existingResource(): Gibt die Objektdarstellung der Ressource zurück, falls sie existiert, oder null, wenn nicht.

existiert

this.exists()

Gibt einen Bool-Wert zurück, der angibt, ob die Ressource derzeit in Azure existiert. Diese Funktion wird während der Bereitstellung evaluiert und ist für die Verwendung innerhalb von Ressourceneigenschaftszuweisungen gedacht, um bedingte Logik zu verarbeiten, ohne separate bestehende Ressourcendeklarationen zu benötigen.

Namensraum: das

Beispiel

resource stg 'Microsoft.Storage/storageAccounts@2026-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
  kind:  'StorageV2'
  properties:{
    accessTier: this.exists() ? this.existingResource()!.properties.accessTier : 'Cold'
  }
}

existierenRessource

this.existingResource()

Gibt die Objektdarstellung der Ressource zurück, falls sie existiert oder null nicht. Diese Funktion paart sich mit this.exists(). Während exists() ein einfaches Boolean zurückgegeben wird, existingResource() gibt das tatsächliche Ressourcenobjekt zurück. Du kannst sicher auf verschachtelte Eigenschaften zugreifen, indem du den null-verzeihlichen Operator (!) oder den sicheren Navigationsoperator (.?) benutzt.

Namensraum: das

Beispiel

resource stg 'Microsoft.Storage/storageAccounts@2026-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'  }
  kind:  'StorageV2'
  properties:{
    accessTier: this.existingResource().?properties.accessTier ?? 'Cold'
  }
}

extensionResourceId

extensionResourceId(resourceId, resourceType, resourceName1, [resourceName2], ...)

Gibt die Ressourcen-ID für eine Erweiterungsressource zurück. Eine Erweiterungsressource ist ein Ressourcentyp, den man auf eine andere Ressource anwendet, um deren Fähigkeiten zu erweitern.

Namespace: az

Das erste Argument muss die vollständig qualifizierte Ressourcen-ID der Ressource sein, auf die die Erweiterungsressource angewendet wird. Diese Anforderung ist besonders wichtig, wenn Sie eine Ressource auf Mieterebene aus einem niedrigeren Umfang wie einem Abonnement oder einer Ressourcengruppe bereitstellen. Ein Wert, der im Tenant-Scope aufgelöst wird, kann ausfallen, wenn die Bereitstellung von einem niedrigeren Scope startet.

Du kannst die extensionResourceId Funktion in Bicep-Dateien verwenden, aber normalerweise brauchst du sie nicht. Verwenden Sie stattdessen den symbolischen Namen für die Ressource, und greifen Sie auf die id-Eigenschaft zu. Die Immobilie id liefert die vollständig qualifizierte Ressourcen-ID.

Das Standardformat der Ressourcen-ID, die von dieser Funktion zurückgegeben wird, ist wie folgt:

{scope}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Das „scope“-Segment ist je nach erweiterter Ressource unterschiedlich.

Wenn Sie die Erweiterungsressource auf eine Ressource anwenden, wird die Ressourcen-ID im folgenden Format zurückgegeben:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{baseResourceProviderNamespace}/{baseResourceType}/{baseResourceName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Wenn Sie die Erweiterungsressource auf eine Ressourcengruppe anwenden, lautet das Format:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Wenn Sie die Erweiterungsressource auf ein Abonnement anwenden, lautet das Format:

/subscriptions/{subscriptionId}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Wenn Sie die Erweiterungsressource auf eine Managementgruppe anwenden, lautet das Format:

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Eine benutzerdefinierte, für eine Verwaltungsgruppe bereitgestellte Richtliniendefinition wird als Erweiterungsressource implementiert. Um eine Richtlinie zu erstellen und zuzuweisen, stellen Sie die folgende Bicep Datei in einer Verwaltungsgruppe bereit.

targetScope = 'managementGroup'

@description('An array of the allowed locations, all other locations will be denied by the created policy.')
param allowedLocations array = [
  'australiaeast'
  'australiasoutheast'
  'australiacentral'
]

resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2025-03-01' = {
  name: 'locationRestriction'
  properties: {
    policyType: 'Custom'
    mode: 'All'
    parameters: {}
    policyRule: {
      if: {
        not: {
          field: 'location'
          in: allowedLocations
        }
      }
      then: {
        effect: 'deny'
      }
    }
  }
}

resource policyAssignment 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
  name: 'locationAssignment'
  properties: {
    policyDefinitionId: policyDefinition.id
  }
}

Integrierte Richtliniendefinitionen sind Ressourcen auf Mandantenebene. Ein Beispiel für die Bereitstellung einer integrierten Richtliniendefinition finden Sie unter tenantResourceId.

getSecret

keyVaultName.getSecret(secretName)

Gibt ein Geheimnis aus einer Azure Key Vault zurück. Verwenden Sie diese Funktion, um einen geheimen Schlüssel an einen sicheren Zeichenfolgenparameter eines Bicep Moduls zu übergeben.

Sie können die Funktion getSecret nur innerhalb des Abschnitts params eines Moduls verwenden. Sie können es nur mit einer Microsoft.KeyVault/vaultsRessource verwenden.

module sql './sql.bicep' = {
  name: 'deploySQL'
  params: {
    adminPassword: keyVault.getSecret('vmAdminPassword')
  }
}

Wenn Sie versuchen, diese Funktion in einem anderen Teil der Bicep Datei zu verwenden, wird ein Fehler angezeigt. Ebenso erhalten Sie einen Fehler, wenn Sie diese Funktion mit Zeichenfolgeninterpolation verwenden. Dies gilt selbst bei Verwendung im Abschnitt „params“.

Verwenden Sie die Funktion nur mit einem Modulparameter, der den @secure() Dekorateur enthält.

Für den Schlüsseltresor muss enabledForTemplateDeployment auf true gesetzt sein. Der Benutzer, der die Bicep Datei bereitstellt, muss Zugriff auf den geheimen Schlüssel haben. Weitere Informationen finden Sie unter Use Azure Key Vault to pass secure parameter value during Bicep deployment.

Ein Namespacequalifizierer ist nicht erforderlich, da die Funktion mit einem Ressourcentyp verwendet wird.

Parameter

Rückgabewert

Der Geheimniswert für den Geheimnisnamen.

Beispiel

Die folgende Bicep Datei wird als Modul verwendet. Sie verfügt über einen adminPassword-Parameter, der mit dem @secure()-Decorator definiert ist.

param sqlServerName string
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2024-11-01-preview' = {
  ...
}

Die folgende Bicep Datei verwendet die vorherige Bicep Datei als Modul. Die Bicep Datei verweist auf einen vorhandenen Schlüsseltresor und ruft die Funktion getSecret auf, um den Schlüsseltresorschlüssel abzurufen, und übergibt dann den Wert als Parameter an das Modul.

param sqlServerName string
param adminLogin string

param subscriptionId string
param kvResourceGroup string
param kvName string

resource keyVault 'Microsoft.KeyVault/vaults@2025-05-01' existing = {
  name: kvName
  scope: resourceGroup(subscriptionId, kvResourceGroup )
}

module sql './sql.bicep' = {
  name: 'deploySQL'
  params: {
    sqlServerName: sqlServerName
    adminLogin: adminLogin
    adminPassword: keyVault.getSecret('vmAdminPassword')
  }
}

Liste*

resourceName.list([apiVersion], [functionValues])

Sie können eine Listenfunktion für jeden Ressourcentyp mit einem Vorgang aufrufen, der mit list beginnt. Häufig werden list, listKeys, listKeyValue und listSecrets verwendet.

Die Syntax für diese Funktion variiert je nach dem Namen des Auflistungsvorgangs. Die zurückgegebenen Werte variieren auch je nach Vorgang. Bicep unterstützt derzeit keine Fertigstellungen und Überprüfungen für list*-Funktionen.

Mit Bicep CLI Version 0.4.X oder höher rufen Sie die Listenfunktion mithilfe des Accessoroperators auf. Beispiel: storageAccount.listKeys().

Ein Namespacequalifizierer ist nicht erforderlich, da die Funktion mit einem Ressourcentyp verwendet wird.

Parameter

Gültige Verwendungen

Verwenden Sie die list Funktionen in den Eigenschaften einer Ressourcendefinition. Verwenden Sie keine list Funktion, die sensible Informationen im Abschnitt outputs einer Bicep-Datei offenlegt. Ausgabewerte werden in der Bereitstellungshistorie gespeichert, und ein böswilliger Nutzer könnte sie abrufen.

Wenn du eine list Funktion mit einer iterativen Schleife verwendest, kannst du sie verwenden input , weil der Ausdruck der Ressource-Eigenschaft zugeordnet ist. Du kannst es nicht verwenden count , weil die Anzahl bestimmt werden muss, bevor die list Funktion aufgelöst wird.

Bei Verwendung einer list-Funktion mit einer Ressource mit bedingter Bereitstellung wird die Funktion auch dann ausgewertet, wenn die Ressource nicht bereitgestellt wird. Es wird eine Fehlermeldung angezeigt, wenn die list-Funktion auf eine nicht vorhandene Ressource verweist. Verwenden Sie den Operator bedingter Ausdruck ?:, um sicherzustellen, dass die Funktion nur ausgewertet wird, wenn die Ressource bereitgestellt wird.

Die Linter-Regel use-recognized-resource-type markiert jede referenzierte Ressource, die einen nicht erkannten oder ungültigen Ressourcentyp verwendet.

Rückgabewert

Das zurückgegebene Objekt variiert abhängig von der verwendeten list-Funktion. Zum Beispiel gibt die listKeys Funktion für ein Speicherkonto folgendes Format zurück:

{
  "keys": [
    {
      "keyName": "key1",
      "permissions": "Full",
      "value": "{value}"
    },
    {
      "keyName": "key2",
      "permissions": "Full",
      "value": "{value}"
    }
  ]
}

Andere list-Funktionen weisen andere Rückgabeformate auf. Um das Format einer Funktion zu sehen, fügen Sie sie in den outputs Abschnitt ein, wie in der Beispiel-Bicep-Datei gezeigt.

list-Beispiel

Im folgenden Beispiel wird ein Speicherkonto bereitgestellt und dann listKeys für dieses Speicherkonto aufgerufen. Der Schlüssel wird verwendet, wenn ein Wert für Bereitstellungsskripte festgelegt wird.

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'dscript${uniqueString(resourceGroup().id)}'
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource dScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'scriptWithStorage'
  location: location
  ...
  properties: {
    azCliVersion: '2.0.80'
    storageAccountSettings: {
      storageAccountName: storageAccount.name
      storageAccountKey: storageAccount.listKeys().keys[0].value
    }
    ...
  }
}

Das nächste Beispiel zeigt eine list-Funktion, die einen Parameter verwendet. In diesem Fall lautet die Funktion listAccountSas. Übergeben Sie ein Objekt für die Ablaufzeit. Die Ablaufzeit muss in der Zukunft liegen.

param accountSasProperties object {
  default: {
    signedServices: 'b'
    signedPermission: 'r'
    signedExpiry: '2020-08-20T11:00:00Z'
    signedResourceTypes: 's'
  }
}
...
sasToken: storageAccount.listAccountSas('2021-04-01', accountSasProperties).accountSasToken

Implementierungen

Die folgende Tabelle zeigt mögliche Verwendungen von list* Funktionen.

Um zu bestimmen, welche Ressourcentypen eine Listenoperation haben, verwenden Sie die folgenden Optionen:

• Zeigen Sie die REST-API-Vorgänge für einen Ressourcenanbieter an, und suchen Sie nach List-Vorgängen. Speicherkonten weisen z. B. den listKeys-Vorgang auf.

• Verwenden Sie das PowerShell-Cmdlet Get-AzProviderOperation. Im folgenden Beispiel werden alle List-Vorgänge für Speicherkonten abgerufen:

  Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
  

• Verwenden Sie den folgenden Azure CLI Befehl, um nur die Listenvorgänge zu filtern:

  az provider operation show --namespace Microsoft.Storage --query "resourceTypes[?name=='storageAccounts'].operations[].name | [?contains(@, 'list')]"
  

managementGroupResourceId

managementGroupResourceId(resourceType, resourceName1, [resourceName2], ...)

Gibt den eindeutigen Bezeichner für eine Ressource zurück, die auf Verwaltungsgruppenebene bereitgestellt wird.

Namespace: az

Die managementGroupResourceId Funktion ist in Bicep-Dateien verfügbar, aber normalerweise brauchst du sie nicht. Verwenden Sie stattdessen den symbolischen Namen für die Ressource, und greifen Sie auf die id-Eigenschaft zu.

Der Bezeichner wird im folgenden Format zurückgeben:

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{resourceType}/{resourceName}

Bemerkungen

Verwenden Sie diese Funktion, um die Ressourcen-ID für Ressourcen zu erhalten, die in der Verwaltungsgruppe und nicht in einer Ressourcengruppe bereitgestellt werden. Die zurückgegebene ID unterscheidet sich dadurch von dem Wert, der von der Funktion resourceId zurückgegeben wird, dass keine Abonnement-ID und kein Ressourcengruppenwert enthalten ist.

managementGroupResourceID-Beispiel

Die folgende Vorlage erstellt eine Richtliniendefinition, und weist diese zu. Hierbei wird die Funktion managementGroupResourceId verwendet, um die Ressourcen-ID für die Richtliniendefinition abzurufen.

targetScope = 'managementGroup'

@description('Target Management Group')
param targetMG string

@description('An array of the allowed locations, all other locations will be denied by the created policy.')
param allowedLocations array = [
  'australiaeast'
  'australiasoutheast'
  'australiacentral'
]

var mgScope = tenantResourceId('Microsoft.Management/managementGroups', targetMG)
var policyDefinitionName = 'LocationRestriction'

resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2025-03-01' = {
  name: policyDefinitionName
  properties: {
    policyType: 'Custom'
    mode: 'All'
    parameters: {}
    policyRule: {
      if: {
        not: {
          field: 'location'
          in: allowedLocations
        }
      }
      then: {
        effect: 'deny'
      }
    }
  }
}

resource location_lock 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
  name: 'location-lock'
  properties: {
    scope: mgScope
    policyDefinitionId: managementGroupResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionName)
  }
  dependsOn: [
    policyDefinition
  ]
}

pickZones

pickZones(providerNamespace, resourceType, location, [numberOfZones], [offset])

Bestimmt, ob ein Ressourcentyp Zonen für eine Region unterstützt. Diese Funktion unterstützt nur Zonenressourcen. Zonenredundante Dienste geben ein leeres Array zurück. Weitere Informationen finden Sie unter Azure Services, die Verfügbarkeitszonen unterstützen.

Namespace: az

Parameter

Rückgabewert

Ein Array mit den unterstützten Zonen. Wenn Sie die Standardwerte für offset und numberOfZonesverwenden, gibt ein Ressourcentyp und eine Region, die Zonen unterstützt, folgendes Array zurück:

[
  "1"
]

Wenn du den Parameter numberOfZones auf 3 setzt, gibt er zurück:

[
  "1",
  "2",
  "3"
]

Wenn der Ressourcentyp oder die Region keine Zonen unterstützt, gibt die Funktion ein leeres Array zurück.

[
]

Bemerkungen

Azure Verfügbarkeitszonen lassen sich in zwei Kategorien einteilen – zonale und zonenredundante. Verwenden Sie die Funktion, pickZones um eine Verfügbarkeitszone für eine zonale Ressource zurückzugeben. Für zonenredundante Dienste (ZRS) gibt die Funktion ein leeres Array zurück. Zonenressourcen verfügen normalerweise über eine zones-Eigenschaft auf der obersten Ebene der Ressourcendefinition. Informationen zur Ermittlung der Kategorie der Unterstützung für Verfügbarkeitszonen finden Sie unter Azure Services, die Verfügbarkeitszonen unterstützen.

Um festzustellen, ob eine bestimmte Azure Region oder ein bestimmter Standort Verfügbarkeitszonen unterstützt, rufen Sie die Funktion pickZones mit einem Zonalressourcentyp auf, z. B. Microsoft.Network/publicIPAddresses. Wenn die Antwort nicht leer ist, unterstützt die Region Verfügbarkeitszonen.

Beispiel für pickZones

Die folgende Bicep Datei zeigt drei Ergebnisse für die Verwendung der Funktion pickZones.

output supported array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')
output notSupportedRegion array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus')
output notSupportedType array = pickZones('Microsoft.Cdn', 'profiles', 'westus2')

Die Ausgabe aus den vorherigen Beispielen gibt drei Arrays zurück.

Verwenden Sie die Antwort von pickZones Methoden, um zu entscheiden, ob Sie Null für Zonen bereitstellen oder virtuelle Maschinen verschiedenen Zonen zuweisen.

Anbieter

Die Funktion des Anbieters ist in Bicep eingestellt. Verwenden Sie es nicht. Wenn Sie diese Funktion verwendet haben, um eine API-Version für den Ressourcenanbieter zu erhalten, geben Sie eine spezifische API-Version in Ihrer Bicep-Datei an. Die Verwendung einer dynamisch zurückgegebenen API-Version kann Ihre Vorlage beschädigen, wenn sich die Eigenschaften zwischen Versionen ändern.

Der providers-Vorgang ist weiterhin über die REST-API verfügbar. Sie können es außerhalb einer Bicep-Datei verwenden, um Informationen über einen Ressourcenanbieter zu erhalten.

Namespace: az

Referenz

reference(resourceName or resourceIdentifier, [apiVersion], ['Full'])

Gibt ein Objekt zurück, das den Laufzeitzustand einer Ressource darstellt. Die Ausgabe und das Verhalten der reference Funktion hängen stark davon ab, wie jeder Ressourcenanbieter (RP) seine PUT- und GET-Antworten implementiert.

Namespace: az

Bicep-Dateien bieten Zugriff auf die Referenzfunktion, obwohl man sie in der Regel nicht benötigt. Verwenden Sie stattdessen den symbolischen Namen der Ressource. Man kann die Referenzfunktion nur innerhalb des properties Objekts einer Ressource verwenden. Man kann es nicht für Top-Level-Eigenschaften wie name oder locationverwenden. Die gleiche Regel gilt im Allgemeinen für Referenzen, die den symbolischen Namen verwenden. Für Eigenschaften wie name, kann man jedoch eine Vorlage generieren, ohne die Referenzfunktion zu verwenden. Man weiß genug über den Ressourcennamen, um den Namen direkt auszusprechen. Dies sind Kompilierungszeit-Eigenschaften. Bicep Überprüfung kann jede falsche Verwendung des symbolischen Namens identifizieren.

Im folgenden Beispiel wird ein Speicherkonto bereitgestellt. Die ersten beiden Ausgaben liefern die gleichen Ergebnisse.

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

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: storageAccountName
  location: location
  kind: 'Storage'
  sku: {
    name: 'Standard_LRS'
  }
}

output storageObjectSymbolic object = storageAccount.properties
output storageObjectReference object = reference('storageAccount')
output storageName string = storageAccount.name
output storageLocation string = storageAccount.location

Um eine Eigenschaft aus einer bestehenden Ressource zu erhalten, die Sie nicht in der Vorlage bereitgestellt haben, verwenden Sie das existing Schlüsselwort:

param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: storageAccountName
}

// use later in template as often as needed
output blobAddress string = storageAccount.properties.primaryEndpoints.blob

Um auf eine Ressource zu referenzieren, die innerhalb einer Elternressource verschachtelt ist, verwenden Sie den verschachtelten Accessor (::). Sie verwenden diese Syntax nur, wenn Sie auf die geschachtelte Ressource von außerhalb der übergeordneten Ressource zugreifen.

vNet1::subnet1.properties.addressPrefix

Wenn Sie versuchen, auf eine Ressource zu verweisen, die nicht vorhanden ist, erhalten Sie den Fehler NotFound, und Ihre Bereitstellung schlägt fehl. Die Linter-Regel use-recognized-resource-type markiert jede referenzierte Ressource, die einen nicht erkannten oder ungültigen Ressourcentyp verwendet.

Ressourcen-ID

resourceId([subscriptionId], [resourceGroupName], resourceType, resourceName1, [resourceName2], ...)

Gibt den eindeutigen Bezeichner einer Ressource zurück.

Namespace: az

Die resourceId Funktion ist in Bicep-Dateien verfügbar, aber normalerweise brauchst du sie nicht. Verwenden Sie stattdessen den symbolischen Namen für die Ressource, und greifen Sie auf die id-Eigenschaft zu.

Verwenden Sie diese Funktion, wenn der Ressourcenname mehrdeutig oder nicht innerhalb derselben Bicep-Datei bereitgestellt ist. Das Format des zurückgegebenen Bezeichners variiert abhängig davon, ob die Bereitstellung im Bereich einer Ressourcengruppe, eines Abonnements, einer Verwaltungsgruppe oder eines Mandanten erfolgt.

Beispiel:

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

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: storageAccountName
  location: location
  kind: 'Storage'
  sku: {
    name: 'Standard_LRS'
  }
}

output storageID string = storageAccount.id

Um die Ressourcen-ID für eine Ressource abzurufen, die nicht in der Bicep-Datei bereitgestellt wird, verwenden Sie das vorhandene Schlüsselwort.

param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: storageAccountName
}

output storageID string = storageAccount.id

Weitere Informationen finden Sie unter der resourceId-Funktion für JSON-Vorlagen.

roleDefinitions

roleDefinitions(roleName)

Gibt Informationen zur angegebenen Rollendefinition zurück, einschließlich id und roleDefinitionId. Es ist ein namensbasiertes Hilfsprogramm für Azure RBAC-Rollenzuweisungen. Anstatt dass Sie die GUID einer benutzerdefinierten oder eingebauten Rollendefinition (wie Contributor, Reader und andere) festcodieren, können Sie den benutzerdefinierten oder integrierten Rollen-Anzeigenamen angeben, und die Funktion löst die entsprechenden Rollendefinitionsinformationen zur Bereitstellung auf.

Namespace: az

Parameter

Rückgabewert

Ein Objekt, das die Rollendefinition einschließlich id und roleDefinitionId.

Beispiele

Der folgende Bicep-Code erstellt eine deterministische Azure RBAC-Rollenzuweisung, die einem bestimmten Hauptverantwortlichen die integrierte Rolle Storage Blob Data Reader im Bereitstellungsbereich zuweist, indem die Rollendefinition zum Zeitpunkt der Bereitstellung anhand des Namens aufgelöst wird.

@description('Specifies the role definition ID used in the role assignment.')
param roleDefinitionName string = 'Storage Blob Data Reader'

@description('Specifies the principal ID assigned to the role.')
param principalId string

var roleAssignmentName= guid(principalId, roleDefinitionName, resourceGroup().id)
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: roleDefinitions(roleDefinitionName).id
    principalId: principalId
  }
}

Weitere Informationen finden Sie unter der resourceId-Funktion für JSON-Vorlagen.

subscriptionResourceId

subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)

Gibt den eindeutigen Bezeichner für eine Ressource zurück, die auf Abonnementebene bereitgestellt wird.

Namespace: az

Die funktion subscriptionResourceId ist in Bicep Dateien verfügbar, aber in der Regel benötigen Sie sie nicht. Verwenden Sie stattdessen den symbolischen Namen für die Ressource, und greifen Sie auf die id-Eigenschaft zu.

Der Bezeichner wird im folgenden Format zurückgeben:

/subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Bemerkungen

Verwenden Sie diese Funktion, um die Ressourcen-ID für Ressourcen zu erhalten, die im Abonnement und nicht für eine Ressourcengruppe bereitgestellt werden. Die zurückgegebene ID unterscheidet sich dadurch von dem Wert, der von der Funktion resourceId zurückgegeben wird, dass kein Ressourcengruppenwert enthalten ist.

subscriptionResourceId(Beispiel)

Die folgende Bicep Datei weist eine integrierte Rolle zu. Sie können diese entweder in einer Ressourcengruppe oder einem Abonnement bereitstellen. Hierbei wird die Funktion subscriptionResourceId verwendet, um die Ressourcen-ID für integrierte Rollen abzurufen.

@description('Principal Id')
param principalId string

@allowed([
  'Owner'
  'Contributor'
  'Reader'
])
@description('Built-in role to assign')
param builtInRoleType string

var roleDefinitionId = {
  Owner: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')
  }
  Contributor: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
  }
  Reader: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')
  }
}

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(resourceGroup().id, principalId, roleDefinitionId[builtInRoleType].id)
  properties: {
    roleDefinitionId: roleDefinitionId[builtInRoleType].id
    principalId: principalId
  }
}

tenantResourceId

tenantResourceId(resourceType, resourceName1, [resourceName2], ...)

Gibt den eindeutigen Bezeichner für eine Ressource zurück, die auf Mandantenebene bereitgestellt wird.

Namespace: az

Die funktion tenantResourceId ist in Bicep Dateien verfügbar, aber in der Regel benötigen Sie sie nicht. Verwenden Sie stattdessen den symbolischen Namen für die Ressource, und greifen Sie auf die id-Eigenschaft zu.

Der Bezeichner wird im folgenden Format zurückgeben:

/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

Integrierte Richtliniendefinitionen sind Ressourcen auf Mandantenebene. Verwenden Sie die Funktion tenantResourceId, um eine Richtlinienzuweisung bereitzustellen, die auf eine integrierte Richtliniendefinition verweist.

@description('Specifies the ID of the policy definition or policy set definition being assigned.')
param policyDefinitionID string = '0a914e76-4921-4c19-b460-a2d36003525a'

@description('Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides.')
param policyAssignmentName string = guid(policyDefinitionID, resourceGroup().name)

resource policyAssignment 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
  name: policyAssignmentName
  properties: {
    scope: subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)
    policyDefinitionId: tenantResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionID)
  }
}

toLogicalZone

toLogicalZone(subscriptionId, location, physicalZone)

Gibt die logische Verfügbarkeitszone zurück (zum Beispiel 1, 2, oder 3), die einer physischen Verfügbarkeitszone für ein bestimmtes Abonnement in einer bestimmten Azure-Region entspricht.

Namensraum: az

Parameter

Rückgabewert

Eine Zeichenfolge, die die logische Verfügbarkeitszone (z. B. , , 1oder 2) darstellt, 3die der angegebenen physischen Zone in der angegebenen Region und dem angegebenen Abonnement entspricht. Wenn die physikalische Zone ungültig oder nicht unterstützt wird, gibt die Funktion eine leere Zeichenkette zurück ('').

Bemerkungen

• Die toLogicalZone Funktion ruft die logische Zonenzuordnung basierend auf der Zonenkonfiguration des Abonnements in der angegebenen Region ab.
• Logische Zonen sind standardisierte Bezeichner (z. B. 1, 2, 3), die in Ressourcenkonfigurationen verwendet werden, um konsistente Zonenzuordnungen über Azure Dienste hinweg sicherzustellen.
• Physische Zonenkennungen sind regionsspezifisch und können je nach Abo variieren. Verwenden Sie die toPhysicalZone Funktion, um diese Zuordnung umzukehren.
• Die Funktion erfordert, dass die Region Verfügbarkeitszonen unterstützt. Eine Liste der unterstützten Regionen finden Sie unter Azure Services, die Verfügbarkeitszonen unterstützen.
• Wenn die physische Zone nicht vorhanden ist oder für das Abonnement nicht zugeordnet ist, gibt die Funktion eine leere Zeichenfolge zurück.
• Diese Funktion ist nützlich für die Ausrichtung von Bereitstellungen physischer Zonen mit logischen Zonenkonfigurationen in Vorlagen, insbesondere für Szenarien mit abonnementübergreifender oder mehreren Regionen.

Beispiele

Im folgenden Beispiel wird die logische Zone für eine physische Zone in West-US 2 für ein bestimmtes Abonnement abgerufen:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'

output logicalZone string = toLogicalZone(subscriptionId, 'westus2', physicalZone)

Erwartete Ausgabe:

Im folgenden Beispiel wird toLogicalZone ein virtueller Computer mit der richtigen logischen Zone konfiguriert:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'
param location string = 'westus2'

var logicalZone = toLogicalZone(subscriptionId, location, physicalZone)

resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
  name: 'myVM'
  location: location
  zones: logicalZone != '' ? [logicalZone] : []
  properties: {
    // VM properties
  }
}

output logicalZone string = logicalZone

Erwartete Ausgabe:

toLogicalZones

toLogicalZones(subscriptionId, location, physicalZones)

Gibt die logischen Verfügbarkeitszonen (z. B. 1, 2 oder 3) zurück, die physischen Verfügbarkeitszonen für ein angegebenes Abonnement in einer bestimmten Azure Region entsprechen. Verwenden Sie die toLogicalZone Funktion, um eine einzelne physische Zone zu konvertieren.

Namensraum: az

Parameter

Rückgabewert

Ein Array logischer Zonennamen, die den bereitgestellten physischen Zonen entsprechen (z 1. B. , , 2oder 3). Wenn eine physikalische Zone ungültig oder nicht unterstützt wird, gibt die Funktion eine leere Zeichenkette zurück ('').

Bemerkungen

Die toLogicalZones-Funktion ordnet physische Zonennamen ihren logischen Zonenentsprechungen für ein angegebenes Azure Abonnement und eine bestimmte Region zu. Dieses Mapping ist nützlich, um Ressourcen basierend auf logischen Zonen innerhalb einer Azure-Region zu konfigurieren oder abzufragen. Für die Funktion ist eine gültige Abonnement-ID, ein unterstützter Azure Standort und ein Array physischer Zonennamen erforderlich. Wenn eine physische Zone an der angegebenen Stelle ungültig oder nicht verfügbar ist, kann die Funktion je nach Kontext einen leeren String für diese Zone zurückgeben oder einen Fehler anzeigen.

Beispiele

Im folgenden Beispiel werden die logischen Zonen für eine Liste der physischen Zonen in West-US 2 für ein bestimmtes Abonnement abgerufen:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZones array = ['westus2-az1', 'westus2-az2', 'westus2-az3']

output logicalZones array = toLogicalZones(subscriptionId, 'westus2', physicalZones)

Erwartete Ausgabe:

toPhysicalZone

toPhysicalZone(subscriptionId, location, logicalZone)

Gibt die physische Verfügbarkeitszonen-Kennung zurück, wie z. B. eine rechenzentrumsspezifische Kennung wie westus2-az1, die einer logischen Verfügbarkeitszone für ein bestimmtes Abonnement in einer bestimmten Azure-Region entspricht.

Namensraum: az

Parameter

Rückgabewert

Ein String, der die physische Verfügbarkeitszonen-Identifikator, wie westus2-az1, darstellt und der angegebenen logischen Zone in der jeweiligen Region und dem Abonnement entspricht. Wenn die logische Zone ungültig oder nicht unterstützt wird, gibt die Funktion eine leere Zeichenkette zurück ('').

Bemerkungen

• Die toPhysicalZone Funktion ruft die physische Zonenzuordnung basierend auf der Zonenkonfiguration des Abonnements in der angegebenen Region ab.
• Physische Zonen sind rechenzentrumsspezifische Identifikatoren, die zwischen Abonnements variieren können, während logische Zonen wie 1, 2, 3, für Ressourcenkonfigurationen standardisiert sind.
• Verwenden Sie die Funktion, toLogicalZone um diese Abbildung umzukehren und eine physikalische Zone in ihr logisches Äquivalent umzuwandeln.
• Die Funktion erfordert, dass die Region Verfügbarkeitszonen unterstützt. Eine Liste der unterstützten Regionen finden Sie unter Azure Services, die Verfügbarkeitszonen unterstützen.
• Wenn die logische Zone nicht vorhanden ist oder für das Abonnement nicht zugeordnet ist, gibt die Funktion eine leere Zeichenfolge zurück.
• Diese Funktion ist nützlich für Szenarien, die physische Zonenkennungen erfordern, wie Logging, Auditing oder Zonenausrichtung zwischen Abschriften in Multiregion-Deployments.

Beispiele

Im folgenden Beispiel wird die physische Zone für eine logische Zone in West-US 2 für ein bestimmtes Abonnement abgerufen:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'

output physicalZone string = toPhysicalZone(subscriptionId, 'westus2', logicalZone)

Erwartete Ausgabe (vorausgesetzt, logische Zone 1 ist zugeordnet westus2-az1zu):

Im folgenden Beispiel wird toPhysicalZone die physische Zone für eine Bereitstellung eines virtuellen Computers protokolliert:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'
param location string = 'westus2'

var physicalZone = toPhysicalZone(subscriptionId, location, logicalZone)

resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
  name: 'myVM'
  location: location
  zones: [logicalZone]
  properties: {
    // VM properties
  }
}

output physicalZone string = physicalZone

Erwartete Ausgabe:

toPhysicalZones

toPhysicalZones(subscriptionId, location, logicalZones)

Gibt die bezeichner der physischen Verfügbarkeitszone zurück (z. B. einen rechenzentrumsspezifischen Bezeichner wie westus2-az1), der logischen Verfügbarkeitszonen für ein bestimmtes Abonnement in einer bestimmten Azure Region entspricht. Verwenden Sie die toPhysicalZone Funktion, um eine einzelne logische Zone zu konvertieren.

Namensraum: az

Parameter

Rückgabewert

Ein Array physischer Zonennamen (z westus2-az1. B. , westus2-az2 ), das den bereitgestellten logischen Zonen entspricht. Wenn eine logische Zone ungültig oder nicht unterstützt wird, gibt die Funktion eine leere Zeichenkette zurück ('').

Bemerkungen

Die toPhysicalZones-Funktion ordnet logische Zonennamen ihren physischen Zonenentsprechungen für ein angegebenes Azure Abonnement und eine bestimmte Region zu. Diese Zuordnung ist nützlich, um Ressourcen in bestimmten physischen Zonen innerhalb einer Azure-Region bereitzustellen oder zu konfigurieren. Die Funktion erfordert eine gültige Abonnement-ID, einen unterstützten Azure Standort und ein Array von logischen Zonennamen. Wenn eine logische Zone an der angegebenen Stelle ungültig oder nicht verfügbar ist, kann die Funktion je nach Kontext eine leere Zeichenkette für diese Zone zurückgeben oder einen Fehler anzeigen.

Beispiele

Im folgenden Beispiel werden die physischen Zonen für eine Liste der logischen Zonen in West-US 2 für ein bestimmtes Abonnement abgerufen:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZones array = ['1', '2', '3']

output physicalZones array = toPhysicalZones(subscriptionId, 'westus2', logicalZones)

Erwartete Ausgabe (vorausgesetzt, logische Zonenzuordnungen, logische Zonenzuordnungen 1westus2-az1und logische Zonenzuordnungen1westus2-az1):3westus2-az3

Nächste Schritte

• Informationen zum Abrufen von Werten aus der aktuellen Bereitstellung finden Sie unter Funktionen für Bereitstellungswerte.
• Informationen zum Durchlaufen einer bestimmten Anzahl von Wiederholungen beim Erstellen eines Ressourcentyps finden Sie unter Iterative Schleifen in Bicep.