Ressourcenfunktionen für ARM-Vorlagen

  • Artikel

Resource Manager stellt die folgenden Funktionen zum Abrufen von Ressourcenwerten in Ihrer Azure Resource Manager-Vorlage (ARM-Vorlage) bereit:

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 listBuildSourceUploadUrl
Microsoft.ContainerRegistry/registries listCredentials
Microsoft.ContainerRegistry/registries listUsages
Microsoft.ContainerRegistry/registries/agentpools listQueueStatus
Microsoft.ContainerRegistry/registries/buildTasks listSourceRepositoryProperties
Microsoft.ContainerRegistry/registries/buildTasks/steps listBuildArguments
Microsoft.ContainerRegistry/registries/taskruns listDetails
Microsoft.ContainerRegistry/registries/webhooks listEvents
Microsoft.ContainerRegistry/registries/runs listLogSasUrl
Microsoft.ContainerRegistry/registries/tasks listDetails
Microsoft.ContainerService/managedClusters listClusterAdminCredential
Microsoft.ContainerService/managedClusters listClusterMonitoringUserCredential
Microsoft.ContainerService/managedClusters listClusterUserCredential
Microsoft.ContainerService/managedClusters/accessProfiles listCredential
Microsoft.DataBox/jobs listCredentials
Microsoft.DataFactory/datafactories/gateways listauthkeys
Microsoft.DataFactory/factories/integrationruntimes listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokens
Microsoft.DataShare/accounts/shares listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions listSourceShareSynchronizationSettings
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizationDetails
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizations
Microsoft.Devices/iotHubs listKeys
Microsoft.Devices/iotHubs/iotHubKeys listKeys
Microsoft.Devices/provisioningServices/keys listKeys
Microsoft.Devices/provisioningServices listKeys
Microsoft.DevTestLab/labs ListVhds
Microsoft.DevTestLab/labs/schedules ListApplicable
Microsoft.DevTestLab/labs/users/serviceFabrics ListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachines ListApplicableSchedules
Microsoft.DocumentDB/databaseAccounts listKeys
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces listConnectionInfo
Microsoft.DomainRegistration/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 Regionen, 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 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 Verweisfunktion bereit, in den meisten Fällen ist die Verweisfunktion 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/11111111-1111-1111-1111-111111111111/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