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@2023-04-01' = {
name: 'locationRestriction'
properties: {
policyType: 'Custom'
mode: 'All'
parameters: {}
policyRule: {
if: {
not: {
field: 'location'
in: allowedLocations
}
}
then: {
effect: 'deny'
}
}
}
}
resource policyAssignment 'Microsoft.Authorization/policyAssignments@2024-04-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 | Type | 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@2023-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-07-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 | Type | 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@2023-04-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 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 | 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 OperationVerwenden 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 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@2023-04-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@2024-04-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-Dienste, die Verfügbarkeitszonen unterstützen.
Namespace: az.
Parameter
| Parameter | Erforderlich | Type | 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 Ermittlung der 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. Die Ausgabe und das Verhalten der reference Funktion basieren stark darauf, wie jeder Ressourcenanbieter (RP) seine PUT- und GET-Antworten implementiert.
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@2023-04-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@2023-04-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@2023-04-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@2023-04-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
}
}
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@2024-04-01' = {
name: policyAssignmentName
properties: {
scope: subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)
policyDefinitionId: tenantResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionID)
}
}
Nächste Schritte
- Informationen zum Abrufen von Werten aus der aktuellen Bereitstellung finden Sie unter Funktionen für Bereitstellungswerte.
- Wenn Sie beim Erstellen eines Ressourcentyps eine angegebene Anzahl von Wiederholungen durchlaufen möchten, finden Sie weitere Informationen unter Iterative Schleifen in Bicep.