Ressourcenfunktionen für ARM-Vorlagen
Resource Manager stellt die folgenden Funktionen zum Abrufen von Ressourcenwerten in Ihrer Azure Resource Manager-Vorlage (ARM-Vorlage) bereit:
- extensionResourceId
- list*
- pickZones
- providers (veraltet)
- reference
- references
- Ressourcen-ID
- subscriptionResourceId
- managementGroupResourceId
- tenantResourceId
Informationen zum Abrufen von Werten aus Parametern, Variablen oder der aktuellen Bereitstellung finden Sie unter Funktionen für Bereitstellungswerte.
Informationen zum Abrufen von Werten für den Bereitstellungsbereich finden Sie unter Bereichsfunktionen.
Tipp
Wir empfehlen Bicep, weil es dieselben Funktionen wie ARM-Vorlagen bietet und die Syntax einfacher zu verwenden ist. Weitere Informationen finden Sie unter Ressourcenfunktionen (resource).
extensionResourceId
extensionResourceId(baseResourceId, 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.
Verwenden Sie in Bicep die Funktion extensionResourceId.
Parameter
Parameter | Erforderlich | Type | BESCHREIBUNG |
---|---|---|---|
baseResourceId | Ja | Zeichenfolge | Die Ressourcen-ID für die Ressource, auf die die Erweiterungsressource angewendet wird. |
resourceType | Ja | Zeichenfolge | Typ der Erweiterungsressource, einschließlich Namespace des Ressourcenanbieters. |
resourceName1 | Ja | Zeichenfolge | Name der Erweiterungsressource. |
resourceName2 | Nein | Zeichenfolge | Nächstes Ressourcennamensegment, sofern erforderlich. |
Fügen Sie weitere Ressourcennamen als Parameter hinzu, wenn der Ressourcentyp mehrere Segmente enthält.
Rückgabewert
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 Basisressource unterschiedlich. Beispielsweise hat die ID für ein Abonnement andere Segmente als die ID für eine Ressourcengruppe.
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 zurückgegebene Format wie folgt:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
Ein Beispiel für die Verwendung dieser Funktion mit einer Ressourcengruppe finden Sie im nächsten Abschnitt.
Wenn die Erweiterungsressource auf ein Abonnement angewendet wird, ist das zurückgegebene Format wie folgt:
/subscriptions/{subscriptionId}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
Wenn die Erweiterungsressource auf eine Verwaltungsgruppe angewendet wird, ist das zurückgegebene Format wie folgt:
/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
Ein Beispiel für die Verwendung dieser Funktion mit einer Verwaltungsgruppe finden Sie im nächsten Abschnitt.
Beispiel für „extensionResourceId“
Im folgenden Beispiel wird die Ressourcen-ID für eine Ressourcengruppensperre zurückgegeben.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"lockName": {
"type": "string"
}
},
"variables": {},
"resources": [],
"outputs": {
"lockResourceId": {
"type": "string",
"value": "[extensionResourceId(resourceGroup().Id , 'Microsoft.Authorization/locks', parameters('lockName'))]"
}
}
}
Eine benutzerdefinierte, für eine Verwaltungsgruppe bereitgestellte Richtliniendefinition wird als Erweiterungsressource implementiert. Stellen Sie die folgende Vorlage für eine Verwaltungsgruppe bereit, um eine Richtlinie zu erstellen und zuzuweisen.
{
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"metadata": {
"_generator": {
"name": "bicep",
"version": "0.5.6.12127",
"templateHash": "1532257987028557958"
}
},
"parameters": {
"targetMG": {
"type": "string",
"metadata": {
"description": "Target Management Group"
}
},
"allowedLocations": {
"type": "array",
"defaultValue": [
"australiaeast",
"australiasoutheast",
"australiacentral"
],
"metadata": {
"description": "An array of the allowed locations, all other locations will be denied by the created policy."
}
}
},
"variables": {
"mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
"policyDefinitionName": "LocationRestriction"
},
"resources": [
{
"type": "Microsoft.Authorization/policyDefinitions",
"apiVersion": "2020-03-01",
"name": "[variables('policyDefinitionName')]",
"properties": {
"policyType": "Custom",
"mode": "All",
"parameters": {},
"policyRule": {
"if": {
"not": {
"field": "location",
"in": "[parameters('allowedLocations')]"
}
},
"then": {
"effect": "deny"
}
}
}
},
{
"type": "Microsoft.Authorization/policyAssignments",
"apiVersion": "2020-03-01",
"name": "location-lock",
"properties": {
"scope": "[variables('mgScope')]",
"policyDefinitionId": "[extensionResourceId(variables('mgScope'), 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
},
"dependsOn": [
"[extensionResourceId(managementGroup().id, 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
]
}
]
}
Integrierte Richtliniendefinitionen sind Ressourcen auf Mandantenebene. Ein Beispiel für die Bereitstellung einer integrierten Richtliniendefinition finden Sie unter tenantResourceId.
list*
list{Value}(resourceName or resourceIdentifier, apiVersion, functionValues)
Die Syntax für diese Funktion variiert je nach dem Namen der Auflistungsvorgänge. Jede Implementierung gibt Werte für den Ressourcentyp zurück, der einen Auflistungsvorgang unterstützt. Der Name des Vorgangs muss mit list
beginnen und kann ein Suffix aufweisen. Häufig werden list
, listKeys
, listKeyValue
und listSecrets
verwendet.
Verwenden Sie in Bicep die list*-Funktion.
Parameter
Parameter | Erforderlich | Type | BESCHREIBUNG |
---|---|---|---|
resourceName oder resourceIdentifier | Ja | Zeichenfolge | Eindeutiger Bezeichner für die Ressource. |
apiVersion | Ja | Zeichenfolge | API-Version eines Ressourcen-Laufzeitstatus. In der Regel im 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 vertrauliche Informationen im Ausgabeabschnitt einer Vorlage offenlegen. Ausgabewerte werden im Bereitstellungsverlauf gespeichert und könnten von einem böswilligen Benutzer abgerufen werden.
Wenn sie mit Eigenschafteniteration verwendet werden, können Sie die Listenfunktionen für input
verwenden, weil der Ausdruck der Ressourceneigenschaft zugewiesen wird. Sie können sie nicht mit count
verwenden, weil die Anzahl bestimmt werden muss, bevor die Listenfunktion aufgelöst wird.
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/topLevelDomains | listAgreements |
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.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/authorizationRules | listKeys |
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules | listKeys |
Microsoft.Relay/namespaces/HybridConnections/authorizationRules | listKeys |
Microsoft.Relay/namespaces/WcfRelays/authorizationRules | listkeys |
Microsoft.Search/searchServices | listAdminKeys |
Microsoft.Search/searchServices | listQueryKeys |
Microsoft.ServiceBus/namespaces/authorizationRules | listKeys |
Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules | listKeys |
Microsoft.ServiceBus/namespaces/queues/authorizationRules | listKeys |
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')]"
Rückgabewert
Das zurückgegebene Objekt variiert abhängig von der verwendeten list
-Funktion. 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 im Abschnitt „outputs“ wie in der Beispielvorlage dargestellt an.
Bemerkungen
Geben Sie die Ressource entweder mithilfe des Ressourcennamens oder der resourceId-Funktion an. Wenn Sie eine list
-Funktion in derselben Vorlage verwenden, die auch die referenzierte Ressource bereitstellt, verwenden Sie den Ressourcennamen.
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 die if
-Funktion, um sicherzustellen, dass die Funktion nur ausgewertet wird, wenn die Ressource bereitgestellt wird. Eine Beispielvorlage, die if
und list
mit einer bedingt bereitgestellten Ressource verwendet, finden Sie unter der if-Funktion.
list-Beispiel
Im folgenden Beispiel wird listKeys
beim Festlegen eines Werts für Bereitstellungsskripts verwendet.
"storageAccountSettings": {
"storageAccountName": "[variables('storageAccountName')]",
"storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').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.
"parameters": {
"accountSasProperties": {
"type": "object",
"defaultValue": {
"signedServices": "b",
"signedPermission": "r",
"signedExpiry": "2020-08-20T11:00:00Z",
"signedResourceTypes": "s"
}
}
},
...
"sasToken": "[listAccountSas(parameters('storagename'), '2018-02-01', parameters('accountSasProperties')).accountSasToken]"
pickZones
pickZones(providerNamespace, resourceType, location, [numberOfZones], [offset])
Bestimmt, ob ein Ressourcentyp Zonen für den angegebenen Standort oder die angegebene 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.
Verwenden Sie in Bicep die pickZones-Funktion.
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. Ein leeres Array wird auch für zonenredundante Dienste 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 Vorlage zeigt drei Ergebnisse für die Verwendung der pickZones
-Funktion.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {},
"functions": [],
"variables": {},
"resources": [],
"outputs": {
"supported": {
"type": "array",
"value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')]"
},
"notSupportedRegion": {
"type": "array",
"value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'westus')]"
},
"notSupportedType": {
"type": "array",
"value": "[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. Im folgenden Beispiel wird ein Wert für die Zone auf der Verfügbarkeit von Zonen basierend festgelegt.
"zones": {
"value": "[if(not(empty(pickZones('Microsoft.Compute', 'virtualMachines', 'westus2'))), string(add(mod(copyIndex(),3),1)), json('null'))]"
},
Azure Cosmos DB ist keine zonale Ressource, aber Sie können mithilfe der pickZones
-Funktion bestimmen, ob Zonenredundanz für die Georeplikation aktiviert werden soll. Übergeben Sie die Datei Microsoft.Storage /storageAccounts-Ressourcentyp, um zu bestimmen, ob Zonenredundanz aktiviert werden soll.
"resources": [
{
"type": "Microsoft.DocumentDB/databaseAccounts",
"apiVersion": "2021-04-15",
"name": "[variables('accountName_var')]",
"location": "[parameters('location')]",
"kind": "GlobalDocumentDB",
"properties": {
"consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
"locations": [
{
"locationName": "[parameters('primaryRegion')]",
"failoverPriority": 0,
"isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('primaryRegion'))), bool('false'), bool('true'))]",
},
{
"locationName": "[parameters('secondaryRegion')]",
"failoverPriority": 1,
"isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('secondaryRegion'))), bool('false'), bool('true'))]",
}
],
"databaseAccountOfferType": "Standard",
"enableAutomaticFailover": "[parameters('automaticFailover')]"
}
}
]
providers
Die providers-Funktion wurde in ARM-Vorlagen als veraltet markiert. Ihre Verwendung wird nicht mehr empfohlen. Wenn Sie diese Funktion verwendet haben, um eine API-Version für den Ressourcenanbieter abzurufen, empfehlen wir, dass Sie eine bestimmte API-Version in Ihrer Vorlage bereitstellen. Die Verwendung einer dynamisch zurückgegebenen API-Version kann Ihre Vorlage beschädigen, wenn sich die Eigenschaften zwischen Versionen ändern.
In Bicep ist der providers-Funktion veraltet.
Der providers-Vorgang ist weiterhin über die REST-API verfügbar. Er kann außerhalb einer ARM-Vorlage verwendet werden, um Informationen zu einem Ressourcenanbieter abzurufen.
reference
In den Vorlagen ohne symbolische Namen:
reference(resourceName or resourceIdentifier, [apiVersion], ['Full'])
In den Vorlagen mit symbolischen Namen:
reference(symbolicName 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. Informationen zur Rückgabe eines Arrays von Objekten, die die Zustände einer Ressourcensammlung zur Laufzeit repräsentieren, finden Sie unter Referenzen.
Bicep stellt die Referenzfunktion bereit, in den meisten Fällen ist die Referenzfunktion jedoch nicht erforderlich. Es wird empfohlen, stattdessen den symbolischen Namen für die Ressource zu verwenden. Weitere Informationen finden Sie unter Verweis.
Parameter
Parameter | Erforderlich | Type | Beschreibung |
---|---|---|---|
resourceName/resourceIdentifier oder symbolicName/resourceIdentifier | Ja | Zeichenfolge | Geben Sie in den Vorlagen ohne symbolische Namen den Namen oder den eindeutigen Bezeichner einer Ressource an. Wenn Sie auf eine Ressource in der aktuellen Vorlage verweisen, stellen Sie nur den Ressourcennamen als Parameter bereit. Wenn Sie auf eine zuvor bereitgestellte Ressource verweisen oder der Name der Ressource nicht eindeutig ist, geben Sie die Ressourcen-ID an. Geben Sie in den Vorlagen mit symbolischen Namen den symbolischen Namen oder den eindeutigen Bezeichner einer Ressource an. Wenn Sie auf eine Ressource in der aktuellen Vorlage verweisen, stellen Sie nur den symbolischen Ressourcennamen als Parameter bereit. Wenn Sie auf eine zuvor bereitgestellte Ressource verweisen, geben Sie die Ressourcen-ID an. |
apiVersion | Nein | Zeichenfolge | API-Version der angegebenen Ressource. Dieser Parameter ist erforderlich, wenn die Ressource nicht innerhalb derselben Vorlage bereitgestellt wird. In der Regel im Format jjjj-mm-tt. Informationen zu gültigen API-Versionen für Ihre Ressource finden Sie in der Vorlagenreferenz. |
'Full' | Nein | Zeichenfolge | Ein Wert, der angibt, ob das vollständige Ressourcenobjekt zurückgegeben werden soll. Wird 'Full' nicht angegeben, wird nur das Eigenschaftenobjekt der Ressource zurückgegeben. Das vollständige Objekt enthält Werte wie die Ressourcen-ID und den Standort. |
Rückgabewert
Jeder Ressourcentyp gibt andere Eigenschaften für die Verweisfunktion zurück. Die Funktion gibt kein einzelnes vordefiniertes Format zurück. Darüber hinaus variiert der zurückgegebene Wert auch je nach dem Wert des 'Full'
-Arguments. Um die Eigenschaften für einen Ressourcentyp anzuzeigen, geben Sie das Objekt wie im Beispiel gezeigt im Abschnitt „outputs“ zurück.
Bemerkungen
Die Verweisfunktion ruft den Runtime-Status einer zuvor bereitgestellten Ressource oder einer in der aktuellen Vorlage bereitgestellten Ressource ab. Dieser Artikel zeigt Beispiele für beide Szenarios.
Sie verwenden in der Regel die Funktion reference
, um einen bestimmten Wert aus einem Objekt zurückzugeben, wie z.B. den Blob-Endpunkt-URI oder den vollständig qualifizierten Domänennamen.
"outputs": {
"BlobUri": {
"type": "string",
"value": "[reference(resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))).primaryEndpoints.blob]"
},
"FQDN": {
"type": "string",
"value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName'))).dnsSettings.fqdn]"
}
}
Verwenden Sie 'Full'
, wenn Sie Ressourcenwerte benötigen, die nicht Teil des Eigenschaftsschemas sind. Rufen Sie zum Festlegen von Schlüsseltresor-Zugriffsrichtlinien beispielsweise die Identitätseigenschaften für einen virtuellen Computer ab.
{
"type": "Microsoft.KeyVault/vaults",
"apiVersion": "2022-07-01",
"name": "vaultName",
"properties": {
"tenantId": "[subscription().tenantId]",
"accessPolicies": [
{
"tenantId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.tenantId]",
"objectId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.principalId]",
"permissions": {
"keys": [
"all"
],
"secrets": [
"all"
]
}
}
],
...
Gültige Verwendungen
Die reference
-Funktion kann nur im Abschnitt „outputs“ einer Vorlage oder Bereitstellung und im „properties“-Objekt einer Ressourcendefinition verwendet werden. Sie kann nicht für Ressourceneigenschaften wie type
, name
, location
und andere Eigenschaften auf oberster Ebene der Ressourcendefinition verwendet werden. Wenn sie mit der Eigenschafteniteration verwendet wird, können Sie die reference
-Funktion für input
verwenden, weil der Ausdruck der Ressourceneigenschaft zugewiesen wird.
Sie können die reference
-Funktion nicht verwenden, um den Wert der count
-Eigenschaft in einer Kopierschleife festzulegen. Sie können damit andere Eigenschaften in der Schleife festlegen. Der Verweis ist für die count-Eigenschaft gesperrt, da diese Eigenschaft vor dem Auflösen der reference
-Funktion bestimmt werden muss.
Wenn Sie die reference
-Funktion oder eine beliebige list*
-Funktion im Abschnitt „outputs“ einer geschachtelten Vorlage verwenden möchten, müssen Sie die expressionEvaluationOptions
so festlegen, dass die Auswertung des inneren Bereichs verwendet wird, oder Sie müssen eine verknüpfte anstelle einer geschachtelten Vorlage verwenden.
Bei Verwendung der reference
-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 reference
-Funktion auf eine nicht vorhandene Ressource verweist. Verwenden Sie die if
-Funktion, um sicherzustellen, dass die Funktion nur ausgewertet wird, wenn die Ressource bereitgestellt wird. Eine Beispielvorlage, die if
und reference
mit einer bedingt bereitgestellten Ressource verwendet, finden Sie unter der if-Funktion.
Implizite Abhängigkeit
Mithilfe der reference
-Funktion deklarieren Sie implizit, dass eine Ressource von einer anderen abhängt, wenn die referenzierte Ressource innerhalb derselben Vorlage zur Verfügung gestellt wird und Sie anhand des Ressourcennamens (nicht der Ressourcen-ID) auf die Ressource verweisen. Die dependsOn
-Eigenschaft muss nicht zusätzlich verwendet werden. Die Funktion wird erst dann ausgewertet, wenn die Ressource, auf die verwiesen wird, die Bereitstellung abgeschlossen hat.
Ressourcenname, symbolischer Name oder Bezeichner
Wenn Sie auf eine Ressource verweisen, die in der gleichen Vorlage ohne symbolischen Namen bereitgestellt wird, geben Sie den Namen der Ressource an.
"value": "[reference(parameters('storageAccountName'))]"
Wenn Sie auf eine Ressource verweisen, die in der gleichen Vorlage ohne symbolischen Namen bereitgestellt wird, geben Sie den Namen der Ressource an.
"value": "[reference('myStorage').primaryEndpoints]"
Oder
"value": "[reference('myStorage', '2022-09-01', 'Full').location]"
Wenn Sie auf eine Ressource verweisen, die nicht in derselben Vorlage bereitgestellt wird, geben Sie die Ressourcen-ID und die apiVersion
an.
"value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2022-09-01')]"
Um Mehrdeutigkeiten in Bezug auf die Ressource zu vermeiden, auf die Sie verweisen, können Sie eine vollqualifizierte Ressourcen-ID angeben.
"value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName')))]"
Wenn Sie einen vollqualifizierten Verweis auf eine Ressource erstellen, ist die Reihenfolge für die Kombination von Segmenten von Typ und Name nicht einfach eine Verkettung beider Werte. Verwenden Sie stattdessen nach dem Namespace eine Folge von Typ-Name-Paaren, beginnend mit dem am wenigsten spezifischen bis zum spezifischsten:
{resource-provider-namespace}/{parent-resource-type}/{parent-resource-name}[/{child-resource-type}/{child-resource-name}]
Beispiel:
Microsoft.Compute/virtualMachines/myVM/extensions/myExt
ist richtig Microsoft.Compute/virtualMachines/extensions/myVM/myExt
ist nicht richtig
Um die Erstellung von Ressourcen-IDs zu vereinfachen, verwenden Sie die in diesem Dokument beschriebenen resourceId()
-Funktionen anstelle der concat()
-Funktion.
Abrufen einer verwalteten Identität
Verwaltete Identitäten für Azure-Ressourcen sind Erweiterungsressourcentypen, die implizit für einige Ressourcen erstellt werden. Da die verwaltete Identität nicht explizit in der Vorlage definiert ist, müssen Sie auf die Ressource verweisen, auf die die Identität angewendet wird. Verwenden Sie Full
, um alle Eigenschaften, einschließlich der implizit erstellten Identität, abzurufen.
Das Muster lautet:
"[reference(resourceId(<resource-provider-namespace>, <resource-name>), <API-version>, 'Full').Identity.propertyName]"
Um z. B. die Prizipal-ID für eine verwaltete Identität abzurufen, die auf einen virtuellen Computer angewandt wird, verwenden Sie:
"[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')),'2019-12-01', 'Full').identity.principalId]",
Um die Mandanten-ID für eine verwaltete Identität abzurufen, die auf eine VM-Skalierungsgruppe angewandt wird, verwenden Sie:
"[reference(resourceId('Microsoft.Compute/virtualMachineScaleSets', variables('vmNodeType0Name')), 2019-12-01, 'Full').Identity.tenantId]"
reference-Beispiel
Das folgende Beispiel stellt eine Ressource bereit und verweist auf diese Ressource.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"storageAccountName": {
"type": "string"
},
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]"
}
},
"resources": [
{
"type": "Microsoft.Storage/storageAccounts",
"apiVersion": "2022-09-01",
"name": "[parameters('storageAccountName')]",
"location": "[parameters('location')]",
"sku": {
"name": "Standard_LRS"
},
"kind": "Storage",
"tags": {},
"properties": {
}
}
],
"outputs": {
"referenceOutput": {
"type": "object",
"value": "[reference(parameters('storageAccountName'))]"
},
"fullReferenceOutput": {
"type": "object",
"value": "[reference(parameters('storageAccountName'), '2022-09-01', 'Full')]"
}
}
}
Im vorherigen Beispiel werden die beiden Objekt zurückgegeben. Das Eigenschaftenobjekt hat das folgende Format:
{
"creationTime": "2017-10-09T18:55:40.5863736Z",
"primaryEndpoints": {
"blob": "https://examplestorage.blob.core.windows.net/",
"file": "https://examplestorage.file.core.windows.net/",
"queue": "https://examplestorage.queue.core.windows.net/",
"table": "https://examplestorage.table.core.windows.net/"
},
"primaryLocation": "southcentralus",
"provisioningState": "Succeeded",
"statusOfPrimary": "available",
"supportsHttpsTrafficOnly": false
}
Das vollständige Objekt hat das folgende Format:
{
"apiVersion":"2022-09-01",
"location":"southcentralus",
"sku": {
"name":"Standard_LRS",
"tier":"Standard"
},
"tags":{},
"kind":"Storage",
"properties": {
"creationTime":"2021-10-09T18:55:40.5863736Z",
"primaryEndpoints": {
"blob":"https://examplestorage.blob.core.windows.net/",
"file":"https://examplestorage.file.core.windows.net/",
"queue":"https://examplestorage.queue.core.windows.net/",
"table":"https://examplestorage.table.core.windows.net/"
},
"primaryLocation":"southcentralus",
"provisioningState":"Succeeded",
"statusOfPrimary":"available",
"supportsHttpsTrafficOnly":false
},
"subscriptionId":"<subscription-id>",
"resourceGroupName":"functionexamplegroup",
"resourceId":"Microsoft.Storage/storageAccounts/examplestorage",
"referenceApiVersion":"2021-04-01",
"condition":true,
"isConditionTrue":true,
"isTemplateResource":false,
"isAction":false,
"provisioningOperation":"Read"
}
Die folgende Beispielvorlage verweist auf ein Speicherkonto, das nicht in dieser Vorlage bereitgestellt wird. Das Speicherkonto ist bereits in demselben Abonnement vorhanden.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"storageResourceGroup": {
"type": "string"
},
"storageAccountName": {
"type": "string"
}
},
"resources": [],
"outputs": {
"ExistingStorage": {
"type": "object",
"value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2021-04-01')]"
}
}
}
Verweist auf
references(symbolic name of a resource collection, ['Full', 'Properties])
Die references
-Funktion arbeitet ähnlich wie reference
. Anstatt ein Objekt zurückzugeben, das den Laufzeitzustand einer Ressource repräsentiert, gibt die Funktion references
ein Array von Objekten zurück, die die Laufzeitzustände einer Ressourcensammlung darstellen. Diese Funktion erfordert eine ARM-Vorlagensprachversion 2.0
und die Aktivierung von symbolischen Namen:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"languageVersion": "2.0",
"contentVersion": "1.0.0.0",
...
}
In Bicep gibt es keine explizite references
-Funktion. Stattdessen wird die symbolische Sammlungsverwendung direkt verwendet, und während der Codegenerierung übersetzt Bicep sie in eine ARM-Vorlage, die die ARM-Vorlagenfunktion references
verwendet. Weitere Informationen finden Sie unter Referenzressource/Modulsammlungen.
Parameter
Parameter | Erforderlich | Type | Beschreibung |
---|---|---|---|
Symbolischer Name einer Ressourcensammlung | Ja | Zeichenfolge | Symbolischer Name einer Ressourcensammlung, die in der aktuellen Vorlage definiert ist. Die references -Funktion unterstützt nicht das Verweisen auf Ressourcen außerhalb der aktuellen Vorlage. |
'Full', 'Properties' | Nein | Zeichenfolge | Ein Wert, der angibt, ob ein Array des vollständigen Ressourcenobjekts zurückgegeben werden soll. Der Standardwert ist 'Properties' . Wird 'Full' nicht angegeben, wird nur das Eigenschaftenobjekt der Ressource zurückgegeben. Das vollständige Objekt enthält Werte wie die Ressourcen-ID und den Standort. |
Rückgabewert
Ein Array der Ressourcensammlung. Jeder Ressourcentyp gibt andere Eigenschaften für die reference
-Funktion zurück. Darüber hinaus variiert der zurückgegebene Wert auch je nach dem Wert des 'Full'
-Arguments. Weitere Informationen finden Sie unter Referenz.
Die Ausgabereihenfolge von references
wird immer in aufsteigender Reihenfolge basierend auf dem Kopierindex angeordnet. Daher wird zuerst die erste Ressource in der Auflistung mit Index 0 angezeigt, gefolgt von Index 1 usw. Beispielsweise [worker-0, worker-1, worker-2, ...].
Wenn im vorherigen Beispiel worker-0 und worker-2 bereitgestellt werden, worker-1 aufgrund einer falschen Bedingung jedoch nicht, lässt die Ausgabe von references
die nicht bereitgestellte Ressource aus und zeigt die bereitgestellten Ressourcen an, geordnet nach ihren Zahlen. Die Ausgabe von references
ist [worker-0, worker-2, ...]. Wenn alle Ressourcen ausgelassen werden, gibt die Funktion ein leeres Array zurück.
Gültige Verwendungen
Die references
-Funktion kann nicht in Ressourcenkopierschleifen oder in Bicep-for-Schleifen verwendet werden. So ist beispielsweise references
im folgenden Szenario nicht zulässig:
{
resources: {
"resourceCollection": {
"copy": { ... },
"properties": {
"prop": "[references(...)]"
}
}
}
}
Wenn Sie die references
-Funktion oder eine beliebige list*
-Funktion im Abschnitt „outputs“ einer geschachtelten Vorlage verwenden möchten, müssen Sie die expressionEvaluationOptions
so festlegen, dass die Auswertung des inneren Bereichs verwendet wird, oder Sie müssen eine verknüpfte anstelle einer geschachtelten Vorlage verwenden.
Implizite Abhängigkeit
Mit der references
-Funktion deklarieren Sie implizit, dass eine Ressource von einer anderen abhängt. Die dependsOn
-Eigenschaft muss nicht zusätzlich verwendet werden. Die Funktion wird erst dann ausgewertet, wenn die Ressource, auf die verwiesen wird, die Bereitstellung abgeschlossen hat.
reference-Beispiel
Das folgende Beispiel stellt eine Ressourcensammlung bereit und verweist auf diese Ressourcensammlung.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"languageVersion": "2.0",
"contentVersion": "1.0.0.0",
"parameters": {
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]",
"metadata": {
"description": "Location for all resources."
}
},
"numWorkers": {
"type": "int",
"defaultValue": 4,
"metadata": {
"description": "The number of workers"
}
}
},
"resources": {
"containerWorkers": {
"copy": {
"name": "containerWorkers",
"count": "[length(range(0, parameters('numWorkers')))]"
},
"type": "Microsoft.ContainerInstance/containerGroups",
"apiVersion": "2023-05-01",
"name": "[format('worker-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
"location": "[parameters('location')]",
"properties": {
"containers": [
{
"name": "[format('worker-container-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
"properties": {
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
],
"resources": {
"requests": {
"cpu": 1,
"memoryInGB": 2
}
}
}
}
],
"osType": "Linux",
"restartPolicy": "Always",
"ipAddress": {
"type": "Public",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
]
}
}
},
"containerController": {
"type": "Microsoft.ContainerInstance/containerGroups",
"apiVersion": "2023-05-01",
"name": "controller",
"location": "[parameters('location')]",
"properties": {
"containers": [
{
"name": "controller-container",
"properties": {
"command": [
"echo",
"[format('Worker IPs are {0}', join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ','))]"
],
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
],
"resources": {
"requests": {
"cpu": 1,
"memoryInGB": 2
}
}
}
}
],
"osType": "Linux",
"restartPolicy": "Always",
"ipAddress": {
"type": "Public",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
]
}
},
"dependsOn": [
"containerWorkers"
]
}
},
"outputs": {
"workerIpAddresses": {
"type": "string",
"value": "[join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ',')]"
},
"containersFull": {
"type": "array",
"value": "[references('containerWorkers', 'full')]"
},
"container": {
"type": "array",
"value": "[references('containerWorkers')]"
}
}
}
Im vorherigen Beispiel werden die drei Objekte zurückgegeben.
"outputs": {
"workerIpAddresses": {
"type": "String",
"value": "20.66.74.26,20.245.100.10,13.91.86.58,40.83.249.30"
},
"containersFull": {
"type": "Array",
"value": [
{
"apiVersion": "2023-05-01",
"condition": true,
"copyContext": {
"copyIndex": 0,
"copyIndexes": {
"": 0,
"containerWorkers": 0
},
"name": "containerWorkers"
},
"copyLoopSymbolicName": "containerWorkers",
"deploymentResourceLineInfo": {
"lineNumber": 30,
"linePosition": 25
},
"existing": false,
"isAction": false,
"isConditionTrue": true,
"isTemplateResource": true,
"location": "westus",
"properties": {
"containers": [
{
"name": "worker-container-0",
"properties": {
"environmentVariables": [],
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
"instanceView": {
"currentState": {
"detailStatus": "",
"startTime": "2023-07-31T19:25:31.996Z",
"state": "Running"
},
"restartCount": 0
},
"ports": [
{
"port": 80,
"protocol": "TCP"
}
],
"resources": {
"requests": {
"cpu": 1.0,
"memoryInGB": 2.0
}
}
}
}
],
"initContainers": [],
"instanceView": {
"events": [],
"state": "Running"
},
"ipAddress": {
"ip": "20.66.74.26",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
],
"type": "Public"
},
"isCustomProvisioningTimeout": false,
"osType": "Linux",
"provisioningState": "Succeeded",
"provisioningTimeoutInSeconds": 1800,
"restartPolicy": "Always",
"sku": "Standard"
},
"provisioningOperation": "Create",
"references": [],
"resourceGroupName": "demoRg",
"resourceId": "Microsoft.ContainerInstance/containerGroups/worker-0",
"scope": "",
"subscriptionId": "",
"symbolicName": "containerWorkers[0]"
},
...
]
},
"containers": {
"type": "Array",
"value": [
{
"containers": [
{
"name": "worker-container-0",
"properties": {
"environmentVariables": [],
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
"instanceView": {
"currentState": {
"detailStatus": "",
"startTime": "2023-07-31T19:25:31.996Z",
"state": "Running"
},
"restartCount": 0
},
"ports": [
{
"port": 80,
"protocol": "TCP"
}
],
"resources": {
"requests": {
"cpu": 1.0,
"memoryInGB": 2.0
}
}
}
}
],
"initContainers": [],
"instanceView": {
"events": [],
"state": "Running"
},
"ipAddress": {
"ip": "20.66.74.26",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
],
"type": "Public"
},
"isCustomProvisioningTimeout": false,
"osType": "Linux",
"provisioningState": "Succeeded",
"provisioningTimeoutInSeconds": 1800,
"restartPolicy": "Always",
"sku": "Standard"
},
...
]
}
}
resourceGroup
Informationen finden Sie unter der resourceGroup-Bereichsfunktion.
Verwenden Sie in Bicep die Bereichsfunktion resourceGroup.
resourceId
resourceId([subscriptionId], [resourceGroupName], resourceType, resourceName1, [resourceName2], ...)
Gibt den eindeutigen Bezeichner einer Ressource zurück. Diese Funktion wird verwendet, wenn der Ressourcenname zweideutig ist oder nicht innerhalb der gleichen Vorlage 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.
Verwenden Sie in Bicep die resourceId-Funktion.
Parameter
Parameter | Erforderlich | Type | BESCHREIBUNG |
---|---|---|---|
subscriptionId | Nein | Zeichenfolge (im GUID-Format) | Der Standardwert ist das aktuelle Abonnement. Geben Sie diesen Wert an, wenn Sie eine Ressource in einem anderen Abonnement abrufen möchten. Geben Sie diesen Wert nur an, wenn die Bereitstellung im Bereich einer Ressourcengruppe oder eines Abonnements erfolgt. |
resourceGroupName | Nein | Zeichenfolge | Der Standardwert ist die aktuelle Ressourcengruppe. Geben Sie diesen Wert an, wenn Sie eine Ressource in einer anderen Ressourcengruppe abrufen möchten. Geben Sie diesen Wert nur an, wenn die Bereitstellung im Bereich einer Ressourcengruppe erfolgt. |
resourceType | Ja | Zeichenfolge | Ressourcentyp einschließlich Namespace von Ressourcenanbieter. |
resourceName1 | Ja | Zeichenfolge | Name der Ressource. |
resourceName2 | Nein | Zeichenfolge | Nächstes Ressourcennamensegment, sofern erforderlich. |
Fügen Sie weitere Ressourcennamen als Parameter hinzu, wenn der Ressourcentyp mehrere Segmente enthält.
Rückgabewert
Die Ressourcen-ID wird in verschiedenen Formaten in verschiedenen Bereichen zurückgegeben:
Ressourcengruppenbereich:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
Abonnementbereich:
/subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
Verwaltungsgruppe oder Mandantenbereich:
/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
Um Verwechslungen zu vermeiden, empfiehlt es sich, resourceId
bei der Arbeit mit Ressourcen, die für das Abonnement, für die Verwaltungsgruppe oder für den Mandanten bereitgestellt werden, nicht zu verwenden. Verwenden Sie stattdessen die für den jeweiligen Bereich vorgesehene ID-Funktion.
- Verwenden Sie für Ressourcen auf Abonnementebene die Funktion subscriptionResourceId.
- Verwenden Sie für Ressourcen auf Verwaltungsgruppenebene die Funktion managementGroupResourceId. Verwenden Sie die Funktion extensionResourceId, um auf eine Ressource zu verweisen, die als Erweiterung einer Verwaltungsgruppe implementiert ist. Benutzerdefinierte Richtliniendefinitionen, die für eine Verwaltungsgruppe bereitgestellt werden, sind beispielsweise Erweiterungen der Verwaltungsgruppe. Verwenden Sie die Funktion tenantResourceId, um auf Ressourcen zu verweisen, die für den Mandanten bereitgestellt wurden, aber in Ihrer Verwaltungsgruppe verfügbar sind. Integrierte Richtliniendefinitionen werden beispielsweise als Ressourcen auf Mandantenebene implementiert.
- Verwenden Sie für Ressourcen auf Mandantenebene die Funktion tenantResourceId. Verwenden Sie
tenantResourceId
für integrierte Richtliniendefinitionen, da diese auf der Mandantenebene implementiert werden.
Bemerkungen
Die Anzahl der Parameter, die Sie angeben, hängt davon ab, ob es sich bei der Ressource um eine übergeordnete oder untergeordnete Ressource handelt und ob sich die Ressource im gleichen Abonnement oder in der gleichen Ressourcengruppe befindet.
Um die Ressourcen-ID für eine übergeordnete Ressource im gleichen Abonnement und in der gleichen Ressourcengruppe abzurufen, geben Sie den Typ und den Namen der Ressource an.
"[resourceId('Microsoft.ServiceBus/namespaces', 'namespace1')]"
Um die Ressourcen-ID für eine untergeordnete Ressource abzurufen, achten Sie auf die Anzahl der Segmente im Ressourcentyp. Geben Sie einen Ressourcennamen für jedes Segment des Ressourcentyps an. Der Name des Segments entspricht der Ressource, die für den jeweiligen Teil der Hierarchie vorhanden ist.
"[resourceId('Microsoft.ServiceBus/namespaces/queues/authorizationRules', 'namespace1', 'queue1', 'auth1')]"
Um die Ressourcen-ID für eine Ressource im gleichen Abonnement, jedoch in einer anderen Ressourcengruppe abzurufen, geben Sie den Ressourcengruppennamen an.
"[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts', 'examplestorage')]"
Um die Ressourcen-ID für eine Ressource in einem anderen Abonnement und in einer anderen Ressourcengruppe abzurufen, geben Sie die Abonnement-ID und den Ressourcengruppennamen an.
"[resourceId('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
Sie müssen diese Funktion oft nutzen, wenn Sie ein Speicherkonto oder einen virtuellen Computer in einer alternativen Ressourcengruppe verwenden. Das folgende Beispiel zeigt, wie eine Ressource von einer externen Ressourcengruppe leicht verwendet werden kann:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"location": {
"type": "string"
},
"virtualNetworkName": {
"type": "string"
},
"virtualNetworkResourceGroup": {
"type": "string"
},
"subnet1Name": {
"type": "string"
},
"nicName": {
"type": "string"
}
},
"variables": {
"subnet1Ref": "[resourceId(parameters('virtualNetworkResourceGroup'), 'Microsoft.Network/virtualNetworks/subnets', parameters('virtualNetworkName'), parameters('subnet1Name'))]"
},
"resources": [
{
"type": "Microsoft.Network/networkInterfaces",
"apiVersion": "2022-11-01",
"name": "[parameters('nicName')]",
"location": "[parameters('location')]",
"properties": {
"ipConfigurations": [
{
"name": "ipconfig1",
"properties": {
"privateIPAllocationMethod": "Dynamic",
"subnet": {
"id": "[variables('subnet1Ref')]"
}
}
}
]
}
}
]
}
resourceId-Beispiel
Im folgenden Beispiel wird die Ressourcen-ID für ein Speicherkonto in der Ressourcengruppe zurückgegeben:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"resources": [],
"outputs": {
"sameRGOutput": {
"type": "string",
"value": "[resourceId('Microsoft.Storage/storageAccounts','examplestorage')]"
},
"differentRGOutput": {
"type": "string",
"value": "[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
},
"differentSubOutput": {
"type": "string",
"value": "[resourceId('11111111-1111-1111-1111-111111111111', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
},
"nestedResourceOutput": {
"type": "string",
"value": "[resourceId('Microsoft.SQL/servers/databases', 'serverName', 'databaseName')]"
}
}
}
Die Ausgabe aus dem vorherigen Beispiel mit den Standardwerten lautet:
Name | type | Wert |
---|---|---|
sameRGOutput | String | /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage |
differentRGOutput | String | /subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage |
differentSubOutput | String | /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage |
nestedResourceOutput | String | /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName |
Abonnement
Weitere Informationen finden Sie unter der Abonnementbereichsfunktion.
Verwenden Sie in Bicep die Bereichsfunktion subscription.
subscriptionResourceId
subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)
Gibt den eindeutigen Bezeichner für eine Ressource zurück, die auf Abonnementebene bereitgestellt wird.
Verwenden Sie in Bicep die SubscriptionResourceId-Funktion.
Parameter
Parameter | Erforderlich | Type | BESCHREIBUNG |
---|---|---|---|
subscriptionId | Nein | Zeichenfolge (im GUID-Format) | Der Standardwert ist das aktuelle Abonnement. Geben Sie diesen Wert an, wenn Sie eine Ressource in einem anderen Abonnement abrufen möchten. |
resourceType | Ja | Zeichenfolge | Ressourcentyp einschließlich Namespace von Ressourcenanbieter. |
resourceName1 | Ja | Zeichenfolge | Name der Ressource. |
resourceName2 | Nein | Zeichenfolge | Nächstes Ressourcennamensegment, sofern erforderlich. |
Fügen Sie weitere Ressourcennamen als Parameter hinzu, wenn der Ressourcentyp mehrere Segmente enthält.
Rückgabewert
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 Vorlage 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.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"principalId": {
"type": "string",
"metadata": {
"description": "The principal to assign the role to"
}
},
"builtInRoleType": {
"type": "string",
"allowedValues": [
"Owner",
"Contributor",
"Reader"
],
"metadata": {
"description": "Built-in role to assign"
}
},
"roleNameGuid": {
"type": "string",
"defaultValue": "[newGuid()]",
"metadata": {
"description": "A new GUID used to identify the role assignment"
}
}
},
"variables": {
"Owner": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
"Contributor": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
"Reader": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]"
},
"resources": [
{
"type": "Microsoft.Authorization/roleAssignments",
"apiVersion": "2022-04-01",
"name": "[parameters('roleNameGuid')]",
"properties": {
"roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
"principalId": "[parameters('principalId')]"
}
}
]
}
managementGroupResourceId
managementGroupResourceId([managementGroupResourceId],resourceType, resourceName1, [resourceName2], ...)
Gibt den eindeutigen Bezeichner für eine Ressource zurück, die auf Verwaltungsgruppenebene bereitgestellt wird.
Verwenden Sie in Bicep die Funktion managementGroupResourceId.
Parameter
Parameter | Erforderlich | Type | BESCHREIBUNG |
---|---|---|---|
managementGroupResourceId | Nein | Zeichenfolge (im GUID-Format) | Der Standardwert ist die aktuelle Verwaltungsgruppe. Geben Sie diesen Wert an, wenn Sie eine Ressource in einer anderen Verwaltungsgruppe abrufen möchten. |
resourceType | Ja | Zeichenfolge | Ressourcentyp einschließlich Namespace von Ressourcenanbieter. |
resourceName1 | Ja | Zeichenfolge | Name der Ressource. |
resourceName2 | Nein | Zeichenfolge | Nächstes Ressourcennamensegment, sofern erforderlich. |
Fügen Sie weitere Ressourcennamen als Parameter hinzu, wenn der Ressourcentyp mehrere Segmente enthält.
Rückgabewert
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.
{
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"targetMG": {
"type": "string",
"metadata": {
"description": "Target Management Group"
}
},
"allowedLocations": {
"type": "array",
"defaultValue": [
"australiaeast",
"australiasoutheast",
"australiacentral"
],
"metadata": {
"description": "An array of the allowed locations, all other locations will be denied by the created policy."
}
}
},
"variables": {
"mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
"policyDefinitionName": "LocationRestriction"
},
"resources": [
{
"type": "Microsoft.Authorization/policyDefinitions",
"apiVersion": "2021-06-01",
"name": "[variables('policyDefinitionName')]",
"properties": {
"policyType": "Custom",
"mode": "All",
"parameters": {},
"policyRule": {
"if": {
"not": {
"field": "location",
"in": "[parameters('allowedLocations')]"
}
},
"then": {
"effect": "deny"
}
}
}
},
"location_lock": {
"type": "Microsoft.Authorization/policyAssignments",
"apiVersion": "2022-06-01",
"name": "location-lock",
"properties": {
"scope": "[variables('mgScope')]",
"policyDefinitionId": "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
},
"dependsOn": [
"[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
]
}
]
}
tenantResourceId
tenantResourceId(resourceType, resourceName1, [resourceName2], ...)
Gibt den eindeutigen Bezeichner für eine Ressource zurück, die auf Mandantenebene bereitgestellt wird.
Verwenden Sie in Bicep die TenantResourceId-Funktion.
Parameter
Parameter | Erforderlich | Type | BESCHREIBUNG |
---|---|---|---|
resourceType | Ja | Zeichenfolge | Ressourcentyp einschließlich Namespace von Ressourcenanbieter. |
resourceName1 | Ja | Zeichenfolge | Name der Ressource. |
resourceName2 | Nein | Zeichenfolge | Nächstes Ressourcennamensegment, sofern erforderlich. |
Fügen Sie weitere Ressourcennamen als Parameter hinzu, wenn der Ressourcentyp mehrere Segmente enthält.
Rückgabewert
Der Bezeichner wird im folgenden Format zurückgeben:
/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
Bemerkungen
Mit dieser Funktion können Sie die Ressourcen-ID für eine Ressource abrufen, die für den Mandanten bereitgestellt wird. Die zurückgegebene ID unterscheidet sich dadurch von den Werten, die von anderen Ressourcen-ID-Funktionen zurückgegeben werden, dass keinen Ressourcengruppen- oder Abonnementwerte enthalten sind.
Beispiel für „tenantResourceId“
Integrierte Richtliniendefinitionen sind Ressourcen auf Mandantenebene. Verwenden Sie die Funktion tenantResourceId
, um eine Richtlinienzuweisung bereitzustellen, die auf eine integrierte Richtliniendefinition verweist.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"policyDefinitionID": {
"type": "string",
"defaultValue": "0a914e76-4921-4c19-b460-a2d36003525a",
"metadata": {
"description": "Specifies the ID of the policy definition or policy set definition being assigned."
}
},
"policyAssignmentName": {
"type": "string",
"defaultValue": "[guid(parameters('policyDefinitionID'), resourceGroup().name)]",
"metadata": {
"description": "Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides."
}
}
},
"resources": [
{
"type": "Microsoft.Authorization/policyAssignments",
"name": "[parameters('policyAssignmentName')]",
"apiVersion": "2022-06-01",
"properties": {
"scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
"policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
}
}
]
}
Nächste Schritte
- Eine Beschreibung der Abschnitte in einer ARM-Vorlage finden Sie unter Grundlegendes zur Struktur und Syntax von ARM-Vorlagen.
- Weitere Informationen zum Mergen mehrerer Vorlagen finden Sie unter Verwenden von verknüpften und geschachtelten Vorlagen bei der Bereitstellung von Azure-Ressourcen.
- Wenn Sie beim Erstellen eines Ressourcentyps eine angegebene Anzahl von Wiederholungen durchlaufen möchten, finden Sie weitere Informationen unter Ressourceniteration in ARM-Vorlagen.
- Informationen zum Bereitstellen der von Ihnen erstellten Vorlage finden Sie unter Bereitstellen von Ressourcen mit ARM-Vorlagen und Azure PowerShell.