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.

extensionResourceId

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

Gibt die Ressourcen-ID für eine Erweiterungsressource zurück. Eine Erweiterungsressource ist ein Ressourcentyp, der auf eine andere Ressource angewendet wird, um deren Funktionen zu erweitern.

Namespace: az.

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

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 die Erweiterungsressource auf eine Ressource angewendet wird, hat die zurückgegebene Ressourcen-ID das folgende Format:

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

Wenn die Erweiterungsressource auf eine Ressourcengruppe angewendet wird, ist das Format wie folgt:

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

Wenn die Erweiterungsressource auf ein Abonnement angewendet wird, ist das Format wie folgt:

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

Wenn die Erweiterungsressource auf eine Verwaltungsgruppe angewendet wird, ist das Format wie folgt:

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

Eine benutzerdefinierte, für eine Verwaltungsgruppe bereitgestellte Richtliniendefinition wird als Erweiterungsressource implementiert. Stellen Sie die folgende Bicep-Datei für eine Verwaltungsgruppe bereit, um eine Richtlinie zu erstellen und zuzuweisen.

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@2021-06-01' = {
  name: 'locationRestriction'
  properties: {
    policyType: 'Custom'
    mode: 'All'
    parameters: {}
    policyRule: {
      if: {
        not: {
          field: 'location'
          in: allowedLocations
        }
      }
      then: {
        effect: 'deny'
      }
    }
  }
}

resource policyAssignment 'Microsoft.Authorization/policyAssignments@2022-06-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 Azure Key Vault zurück. Verwenden Sie diese Funktion, um ein Geheimnis an einen sicheren Zeichenfolgenparameter eines Bicep-Moduls zu übergeben.

Hinweis

Die az.getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion)-Funktion kann in .bicepparam-Dateien verwendet werden, um Schlüsseltresorgeheimnisse abzurufen. Weitere Informationen finden Sie unter getSecret.

Sie können die Funktion getSecret nur innerhalb des Abschnitts params eines Moduls verwenden. Sie können sie nur mit einer Microsoft.KeyVault/vaults-Ressource verwenden.

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

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

Die Funktion kann nur mit einem Modulparameter verwendet werden, der über den @secure()-Decorator verfügt.

Für den Schlüsseltresor muss enabledForTemplateDeployment auf true gesetzt sein. Der Benutzer, der die Bicep-Datei bereitstellt, muss über Zugriff auf das Geheimnis verfügen. Weitere Informationen finden Sie unter Verwenden von Azure Key Vault zum Übergeben eines sicheren Parameterwerts während der Bicep-Bereitstellung.

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

Parameter

Parameter Erforderlich Art Beschreibung
secretName Ja Zeichenfolge Der Name des Geheimnisses, das in einem Schlüsseltresor gespeichert ist.

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@2022-08-01-preview' = {
  ...
}

Die folgende Bicep-Datei verwendet obige Bicep-Datei als Modul. Die Bicep-Datei verweist auf einen vorhandenen Schlüsseltresor, ruft die getSecret-Funktion auf, um das Schlüsseltresorgeheimnis abzurufen, und übergibt den Wert dann 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@2023-02-01' existing = {
  name: kvName
  scope: resourceGroup(subscriptionId, kvResourceGroup )
}

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

list*

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 Vervollständigungen und Validierungen für list*-Funktionen.

Ab Bicep CLI Version 0.4.X oder höher rufen Sie die Listenfunktion mit dem Accessor-Operator auf. Beispiel: storageAccount.listKeys().

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

Parameter

Parameter Erforderlich Art BESCHREIBUNG
apiVersion Nein Zeichenfolge Wenn Sie diesen Parameter nicht angeben, wird die API-Version für die Ressource verwendet. Stellen Sie nur dann eine benutzerdefinierte API-Version bereit, wenn Sie die Funktion mit einer bestimmten Version ausführen müssen. Verwenden Sie das Format jjjj-mm-tt.
functionValues Nein Objekt (object) Ein Objekt, das über Werte für die Funktion verfügt. Geben Sie dieses Objekt nur für Funktionen an, die den Empfang eines Objekts mit Parameterwerten unterstützen – z. B. listAccountSas für ein Speicherkonto. Ein Beispiel für die Übergabe von Funktionswerten wird in diesem Artikel gezeigt.

Gültige Verwendungen

Die list-Funktionen können in den Eigenschaften einer Ressourcendefinition verwendet werden. Verwenden Sie keine list-Funktionen, die im Abschnitt „outputs“ einer Bicep-Datei vertrauliche Informationen offenlegen. Ausgabewerte werden im Bereitstellungsverlauf gespeichert und könnten von einem böswilligen Benutzer abgerufen werden.

Wenn sie mit einer iterativen Schleife verwendet werden, können Sie die list-Funktionen für input nutzen, weil der Ausdruck der resource-Eigenschaft zugewiesen wird. Sie können sie nicht mit count verwenden, 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.

Rückgabewert

Das zurückgegebene Objekt ist abhängig von der list-Funktion, die Sie verwenden, unterschiedlich. listKeys für ein Speicherkonto wird z. B. im folgenden Format zurückgegeben:

{
  "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 anzuzeigen, geben Sie es wie in der Bicep-Beispieldatei dargestellt im Abschnitt „outputs“ an.

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@2022-09-01' = {
  name: 'dscript${uniqueString(resourceGroup().id)}'
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource dScript 'Microsoft.Resources/deploymentScripts@2020-10-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 Verwendungsmöglichkeiten von list* werden in der folgenden Tabelle gezeigt.

Ressourcentyp Funktionsname
Microsoft.Addons/supportProviders listsupportplaninfo
Microsoft.AnalysisServices/servers listGatewayStatus
Microsoft.ApiManagement/service/authorizationServers listSecrets
Microsoft.ApiManagement/service/gateways listKeys
Microsoft.ApiManagement/service/identityProviders listSecrets
Microsoft.ApiManagement/service/namedValues listValue
Microsoft.ApiManagement/service/openidConnectProviders listSecrets
Microsoft.ApiManagement/service/subscriptions listSecrets
Microsoft.AppConfiguration/configurationStores ListKeys
Microsoft.AppPlatform/Spring listTestKeys
Microsoft.Automation/automationAccounts listKeys
Microsoft.Batch/batchAccounts listkeys
Microsoft.BatchAI/workspaces/experiments/jobs listoutputfiles
Microsoft.BotService/botServices/channels listChannelWithKeys
Microsoft.Cache/redis listKeys
Microsoft.CognitiveServices/accounts listKeys
Microsoft.ContainerRegistry/registries listBuildSourceUploadUrl
Microsoft.ContainerRegistry/registries listCredentials
Microsoft.ContainerRegistry/registries listUsages
Microsoft.ContainerRegistry/registries/agentpools listQueueStatus
Microsoft.ContainerRegistry/registries/buildTasks listSourceRepositoryProperties
Microsoft.ContainerRegistry/registries/buildTasks/steps listBuildArguments
Microsoft.ContainerRegistry/registries/taskruns listDetails
Microsoft.ContainerRegistry/registries/webhooks listEvents
Microsoft.ContainerRegistry/registries/runs listLogSasUrl
Microsoft.ContainerRegistry/registries/tasks listDetails
Microsoft.ContainerService/managedClusters listClusterAdminCredential
Microsoft.ContainerService/managedClusters listClusterMonitoringUserCredential
Microsoft.ContainerService/managedClusters listClusterUserCredential
Microsoft.ContainerService/managedClusters/accessProfiles listCredential
Microsoft.DataBox/jobs listCredentials
Microsoft.DataFactory/datafactories/gateways listauthkeys
Microsoft.DataFactory/factories/integrationruntimes listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokens
Microsoft.DataShare/accounts/shares listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions listSourceShareSynchronizationSettings
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizationDetails
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizations
Microsoft.Devices/iotHubs listkeys
Microsoft.Devices/iotHubs/iotHubKeys listkeys
Microsoft.Devices/provisioningServices/keys listkeys
Microsoft.Devices/provisioningServices listkeys
Microsoft.DevTestLab/labs ListVhds
Microsoft.DevTestLab/labs/schedules ListApplicable
Microsoft.DevTestLab/labs/users/serviceFabrics ListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachines ListApplicableSchedules
Microsoft.DocumentDB/databaseAccounts listKeys
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces listConnectionInfo
Microsoft.DomainRegistration listDomainRecommendations
Microsoft.DomainRegistration/topLevelDomains listAgreements
Microsoft.EventGrid/domains listKeys
Microsoft.EventGrid/topics listKeys
Microsoft.EventHub/namespaces/authorizationRules listkeys
Microsoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRules listkeys
Microsoft.EventHub/namespaces/eventhubs/authorizationRules listkeys
Microsoft.ImportExport/jobs listBitLockerKeys
Microsoft.Kusto/Clusters/Databases ListPrincipals
Microsoft.LabServices/labs/users list
Microsoft.LabServices/labs/virtualMachines list
Microsoft.Logic/integrationAccounts/agreements listContentCallbackUrl
Microsoft.Logic/integrationAccounts/assemblies listContentCallbackUrl
Microsoft.Logic/integrationAccounts listCallbackUrl
Microsoft.Logic/integrationAccounts listKeyVaultKeys
Microsoft.Logic/integrationAccounts/maps listContentCallbackUrl
Microsoft.Logic/integrationAccounts/partners listContentCallbackUrl
Microsoft.Logic/integrationAccounts/schemas listContentCallbackUrl
Microsoft.Logic/workflows listCallbackUrl
Microsoft.Logic/workflows listSwagger
Microsoft.Logic/workflows/runs/actions listExpressionTraces
Microsoft.Logic/workflows/runs/actions/repetitions listExpressionTraces
Microsoft.Logic/workflows/triggers listCallbackUrl
Microsoft.Logic/workflows/versions/triggers listCallbackUrl
Microsoft.MachineLearning/webServices listkeys
Microsoft.MachineLearning/Workspaces listworkspacekeys
Microsoft.MachineLearningServices/workspaces/computes listKeys
Microsoft.MachineLearningServices/workspaces/computes listNodes
Microsoft.MachineLearningServices/workspaces listKeys
Microsoft.Maps/accounts listKeys
Microsoft.Media/mediaservices/assets listContainerSas
Microsoft.Media/mediaservices/assets listStreamingLocators
Microsoft.Media/mediaservices/streamingLocators listContentKeys
Microsoft.Media/mediaservices/streamingLocators listPaths
Microsoft.Network/applicationSecurityGroups listIpConfigurations
Microsoft.NotificationHubs/Namespaces/authorizationRules listkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRules listkeys
Microsoft.OperationalInsights/workspaces list
Microsoft.OperationalInsights/workspaces listKeys
Microsoft.PolicyInsights/remediations listDeployments
Microsoft.RedHatOpenShift/openShiftClusters listCredentials
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules listkeys
Microsoft.Search/searchServices listAdminKeys
Microsoft.Search/searchServices listQueryKeys
Microsoft.SignalRService/SignalR listkeys
Microsoft.Storage/storageAccounts listAccountSas
Microsoft.Storage/storageAccounts listkeys
Microsoft.Storage/storageAccounts listServiceSas
Microsoft.StorSimple/managers/devices listFailoverSets
Microsoft.StorSimple/managers/devices listFailoverTargets
Microsoft.StorSimple/managers listActivationKey
Microsoft.StorSimple/managers listPublicEncryptionKey
Microsoft.Synapse/workspaces/integrationRuntimes listauthkeys
Microsoft.Web/connectionGateways ListStatus
microsoft.web/connections listconsentlinks
Microsoft.Web/customApis listWsdlInterfaces
microsoft.web/locations listwsdlinterfaces
microsoft.web/apimanagementaccounts/apis/connections listconnectionkeys
microsoft.web/apimanagementaccounts/apis/connections listsecrets
microsoft.web/sites/backups list
Microsoft.Web/sites/config list
microsoft.web/sites/functions listkeys
microsoft.web/sites/functions listsecrets
microsoft.web/sites/hybridconnectionnamespaces/relays listkeys
microsoft.web/sites listsyncfunctiontriggerstatus
microsoft.web/sites/slots/functions listsecrets
microsoft.web/sites/slots/backups list
Microsoft.Web/sites/slots/config list
microsoft.web/sites/slots/functions listsecrets

Um zu bestimmen, welche Ressourcentypen einen list-Vorgang aufweisen, stehen die folgenden Optionen zur Verfügung:

  • 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')]"
    

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 Regionen, die Verfügbarkeitszonen unterstützen.

Namespace: az.

Parameter

Parameter Erforderlich Art BESCHREIBUNG
providerNamespace Ja Zeichenfolge Der Ressourcenanbieternamespace für den Ressourcentyp, der auf Zonenunterstützung überprüft werden soll.
resourceType Ja Zeichenfolge Der Ressourcentyp, der auf Zonenunterstützung überprüft werden soll.
location Ja Zeichenfolge Die Region, die auf Zonenunterstützung überprüft werden soll.
numberOfZones Nein integer Die Anzahl der zurückzugebenden logischen Zonen. Der Standardwert ist 1. Die Anzahl muss eine positive ganze Zahl zwischen 1 und 3 sein. Verwenden Sie 1 für Ressourcen mit nur einer Zone. Für Ressourcen mit mehreren Zonen muss der Wert kleiner als oder gleich der Anzahl der unterstützten Zonen sein.
offset Nein integer Der Offset von der beginnenden logischen Zone. Die Funktion gibt einen Fehler zurück, wenn Offset plus numberOfZones die Anzahl der unterstützten Zonen überschreitet.

Rückgabewert

Ein Array mit den unterstützten Zonen. Wenn Sie die Standardwerte für Offset und numberOfZones verwenden, geben ein Ressourcentyp und eine Region, die Zonen unterstützen, das folgende Array zurück:

[
    "1"
]

Wenn der numberOfZones-Parameter auf 3 festgelegt ist, wird Folgendes zurückgegeben:

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

Wenn der Ressourcentyp oder die Region keine Zonen unterstützt, wird ein leeres Array zurückgegeben.

[
]

Hinweise

Es gibt verschiedene Kategorien für Azure-Verfügbarkeitszonen: Zone und zonenredundant. Die pickZones-Funktion kann verwendet werden, um eine Verfügbarkeitszone für eine Zonenressource 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 Kategorie der Unterstützung für Verfügbarkeitszonen finden Sie unter Azure-Dienste, die Verfügbarkeitszonen unterstützen.

Um zu ermitteln, ob eine bestimmte Azure-Region oder ein angegebener Standort Verfügbarkeitszonen unterstützt, rufen Sie die pickZones-Funktion mit einem Zonenressourcentyp wie z. B. Microsoft.Network/publicIPAddresses auf. 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 pickZones-Funktion.

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.

Name type Wert
Unterstützt array [ "1" ]
notSupportedRegion array []
notSupportedType array []

Sie können anhand der Antwort von pickZones bestimmen, ob NULL für Zonen bereitgestellt werden soll oder VMs verschiedenen Zonen zugewiesen werden sollen.

providers

Die providers-Funktion wurde in Bicep als veraltet markiert. Ihre Verwendung wird nicht mehr empfohlen. Wenn Sie diese Funktion verwendet haben, um eine API-Version für den Ressourcenanbieter abzurufen, sollten Sie eine bestimmte API-Version in Ihrer Bicep-Datei bereitstellen. 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. Er kann außerhalb einer Bicep-Datei verwendet werden, um Informationen zu einem Ressourcenanbieter abzurufen.

Namespace: az.

Referenz

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

Gibt ein Objekt zurück, das den Laufzeitstatus einer Ressource darstellt.

Namespace: az.

Die Bicep-Dateien bieten Zugriff auf die Verweisfunktion, obwohl sie in der Regel nicht erforderlich ist. Es wird empfohlen, stattdessen den symbolischen Namen der Ressource zu verwenden. Die Verweisfunktion kann nur innerhalb des properties-Objekts einer Ressource verwendet werden und nicht für Eigenschaften der obersten Ebene wie name oder location. Das gleiche gilt im Allgemeinen für Verweise, die den symbolischen Namen verwenden. Bei Eigenschaften wie name ist es jedoch möglich, eine Vorlage zu generieren, ohne die Verweisfunktion zu verwenden. Es sind genügend Informationen über den Ressourcennamen bekannt, um den Namen direkt auszugeben. Sie werden als Kompilierzeiteigenschaften bezeichnet. Die Bicep-Überprüfung kann jede falsche Verwendung des symbolischen Namens erkennen.

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@2022-09-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

Zum Abrufen einer Eigenschaft einer vorhandenen Ressource, die nicht in der Vorlage bereitgestellt ist, verwenden Sie das Schlüsselwort existing:

param storageAccountName string

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

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

Um auf eine Ressource zu verweisen, die innerhalb einer übergeordneten Ressource geschachtelt ist, verwenden Sie den geschachtelten 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.

resourceId

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

Gibt den eindeutigen Bezeichner einer Ressource zurück.

Namespace: az.

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

Diese Funktion wird verwendet, wenn der Ressourcenname zweideutig ist oder nicht innerhalb der gleichen Bicep-Datei zur Verfügung gestellt wird. 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@2022-09-01' = {
  name: storageAccountName
  location: location
  kind: 'Storage'
  sku: {
    name: 'Standard_LRS'
  }
}

output storageID string = storageAccount.id

Verwenden Sie das Schlüsselwort „existing“, um die Ressourcen-ID für eine Ressource abzurufen, die nicht in der Bicep-Datei bereitgestellt wird.

param storageAccountName string

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

output storageID string = storageAccount.id

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 subscriptionResourceId-Funktion ist zwar in Bicep-Dateien verfügbar, aber Sie werden sie in der Regel nicht benötigen. 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

Mit dieser Funktion können Sie die Ressourcen-ID für Ressourcen abrufen, die im Abonnement bereitgestellt werden und nicht in einer Ressourcengruppe. Die zurückgegebene ID unterscheidet sich dadurch von dem Wert, der von der Funktion resourceId zurückgegeben wird, dass kein Ressourcengruppenwert enthalten ist.

Beispiel für „subscriptionResourceId“

Mit der folgenden Bicep-Datei wird eine integrierte Rolle zugewiesen. 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
  }
}

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 zwar in Bicep-Dateien verfügbar, aber Sie werden sie in der Regel nicht benötigen. 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

Mit dieser Funktion können Sie die Ressourcen-ID für Ressourcen abrufen, die in der Verwaltungsgruppe bereitgestellt werden und nicht in einer Ressourcengruppe. 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@2021-06-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@2021-06-01' = {
  name: 'location-lock'
  properties: {
    scope: mgScope
    policyDefinitionId: managementGroupResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionName)
  }
  dependsOn: [
    policyDefinition
  ]
}

tenantResourceId

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

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

Namespace: az.

Die tenantResourceId-Funktion ist zwar in Bicep-Dateien verfügbar, aber Sie werden sie in der Regel nicht benötigen. 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@2022-06-01' = {
  name: policyAssignmentName
  properties: {
    scope: subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)
    policyDefinitionId: tenantResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionID)
  }
}

Nächste Schritte