Resourcefuncties voor ARM-sjablonen

  • Artikel

Resource Manager biedt de volgende functies voor het ophalen van resourcewaarden in uw Arm-sjabloon (Azure Resource Manager-sjabloon):

Zie Waardefuncties voor implementatie om waarden op te halen uit parameters, variabelen of de huidige implementatie.

Zie Bereikfuncties voor het ophalen van waarden voor het implementatiebereik.

Tip

We raden Bicep aan omdat het dezelfde mogelijkheden biedt als ARM-sjablonen en de syntaxis gemakkelijker te gebruiken is. Zie resourcefuncties voor meer informatie.

extensionResourceId

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

Retourneert de resource-id voor een extensieresource. Een extensieresource is een resourcetype dat wordt toegepast op een andere resource om toe te voegen aan de mogelijkheden ervan.

Gebruik in Bicep de functie extensionResourceId .

Parameters

Parameter Vereist Type Description
baseResourceId Ja tekenreeks De resource-id voor de resource waarop de extensieresource wordt toegepast.
resourceType Ja tekenreeks Type van de extensieresource, inclusief resourceprovidernaamruimte.
resourceName1 Ja tekenreeks Naam van de extensieresource.
resourceName2 Nee tekenreeks Volgend resourcenaamsegment, indien nodig.

Ga door met het toevoegen van resourcenamen als parameters wanneer het resourcetype meer segmenten bevat.

Retourwaarde

De basisindeling van de resource-id die door deze functie wordt geretourneerd, is:

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

Het bereiksegment varieert per basisresource die wordt uitgebreid. De id voor een abonnement heeft bijvoorbeeld verschillende segmenten dan de id voor een resourcegroep.

Wanneer de extensieresource wordt toegepast op een resource, wordt de resource-id geretourneerd in de volgende indeling:

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

Wanneer de extensieresource wordt toegepast op een resourcegroep, is de geretourneerde indeling:

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

In de volgende sectie ziet u een voorbeeld van het gebruik van deze functie met een resourcegroep.

Wanneer de extensieresource wordt toegepast op een abonnement, is de geretourneerde indeling:

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

Wanneer de extensieresource wordt toegepast op een beheergroep, is de geretourneerde indeling:

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

In de volgende sectie ziet u een voorbeeld van het gebruik van deze functie met een beheergroep.

extensionResourceId-voorbeeld

In het volgende voorbeeld wordt de resource-id voor een vergrendeling van een resourcegroep geretourneerd.

{
  "$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'))]"
    }
  }
}

Een aangepaste beleidsdefinitie die is geïmplementeerd in een beheergroep, wordt geïmplementeerd als een extensieresource. Als u een beleid wilt maken en toewijzen, implementeert u de volgende sjabloon in een beheergroep.

{
  "$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'))]"
      ]
    }
  ]
}

Ingebouwde beleidsdefinities zijn resources op tenantniveau. Zie tenantResourceId voor een voorbeeld van het implementeren van een ingebouwde beleidsdefinitie.

Lijst*

list{Value}(resourceName or resourceIdentifier, apiVersion, functionValues)

De syntaxis voor deze functie verschilt per naam van de lijstbewerkingen. Elke implementatie retourneert waarden voor het resourcetype dat een lijstbewerking ondersteunt. De naam van de bewerking moet beginnen met list en kan een achtervoegsel hebben. Sommige veelvoorkomende gebruiksrechten zijn list, listKeys, listKeyValueen listSecrets.

Gebruik in Bicep de functie list* .

Parameters

Parameter Vereist Type Description
resourceName of resourceIdentifier Ja tekenreeks Unieke id voor de resource.
apiVersion Ja tekenreeks API-versie van de runtimestatus van de resource. Normaal gesproken in de notatie jjjj-mm-dd.
functionValues Nee object Een object met waarden voor de functie. Geef dit object alleen op voor functies die ondersteuning bieden voor het ontvangen van een object met parameterwaarden, zoals listAccountSas in een opslagaccount. In dit artikel wordt een voorbeeld weergegeven van het doorgeven van functiewaarden.

Geldig gebruik

De lijstfuncties kunnen worden gebruikt in de eigenschappen van een resourcedefinitie. Gebruik geen lijstfunctie waarmee gevoelige informatie wordt weergegeven in de uitvoersectie van een sjabloon. Uitvoerwaarden worden opgeslagen in de implementatiegeschiedenis en kunnen worden opgehaald door een kwaadwillende gebruiker.

Wanneer u deze functie gebruikt met iteratie van eigenschappen, kunt u de lijstfuncties gebruiken omdat input de expressie is toegewezen aan de resource-eigenschap. U kunt ze niet gebruiken omdat count het aantal moet worden bepaald voordat de lijstfunctie wordt omgezet.

Implementaties

De mogelijke toepassingen worden list* weergegeven in de volgende tabel.

Brontype Functienaam
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/openid Verbinding maken Providers 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/registers listBuildSourceUploadUrl
Microsoft.ContainerRegistry/registers listCredentials
Microsoft.ContainerRegistry/registers 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 listCluster Beheer Credential
Microsoft.ContainerService/managedClusters listClusterMonitoringUserCredential
Microsoft.ContainerService/managedClusters listClusterUserCredential
Microsoft.ContainerService/managedClusters/accessProfiles listCredential
Microsoft.DataBox/jobs listCredentials
Microsoft.DataFactory/datafactories/gateways listauthkeys
Microsoft.DataFactory/factory's/integrationruntimes listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokens
Microsoft.DataShare/accounts/shares listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions listSourceShareSynchronization Instellingen
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 list Verbinding maken ionInfo
Microsoft.DomainRegistration/topLevelDomains listAgreements
Microsoft.EventHub/naamruimten/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/gebruikers lijst
Microsoft.LabServices/labs/virtualMachines lijst
Microsoft.Logic/integrationAccounts/agreements listContentCallbackUrl
Microsoft.Logic/integrationAccounts/assembly's listContentCallbackUrl
Microsoft.Logic/integrationAccounts listCallbackUrl
Microsoft.Logic/integrationAccounts listKeyVaultKeys
Microsoft.Logic/integrationAccounts/maps listContentCallbackUrl
Microsoft.Logic/integrationAccounts/partners listContentCallbackUrl
Microsoft.Logic/integrationAccounts/schema's listContentCallbackUrl
Microsoft.Logic/workflows listCallbackUrl
Microsoft.Logic/workflows listSwagger
Microsoft.Logic/workflows/runs/actions listExpressionTraces
Microsoft.Logic/workflows/runs/actions/herhalingen listExpressionTraces
Microsoft.Logic/workflows/triggers listCallbackUrl
Microsoft.Logic/workflows/versions/triggers listCallbackUrl
Microsoft.MachineLearning/webServices listkeys
Microsoft.MachineLearning/Workspaces listworkspacekeys
Microsoft. Kaarten/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/Naamruimten/authorizationRules listkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRules listkeys
Microsoft.OperationalInsights/workspaces lijst
Microsoft.OperationalInsights/workspaces listKeys
Microsoft.PolicyInsights/herstelbewerkingen listDeployments
Microsoft.RedHatOpenShift/openShiftClusters listCredentials
Microsoft.Relay/naamruimten/authorizationRules listKeys
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.Relay/namespaces/Hybrid Verbinding maken ions/authorizationRules listKeys
Microsoft.Relay/naamruimten/WcfRelays/authorizationRules listkeys
Microsoft.Search/searchServices list Beheer Keys
Microsoft.Search/searchServices listQueryKeys
Microsoft.ServiceBus/naamruimten/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/apparaten listFailoverSets
Microsoft.StorSimple/managers/apparaten 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 lijst
Microsoft.Web/sites/config lijst
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 lijst
Microsoft.Web/sites/slots/config lijst
microsoft.web/sites/slots/functions listSecrets

Als u wilt bepalen welke resourcetypen een lijstbewerking hebben, hebt u de volgende opties:

  • Bekijk de REST API-bewerkingen voor een resourceprovider en zoek naar lijstbewerkingen. Opslagaccounts hebben bijvoorbeeld de bewerking listKeys.

  • Gebruik de Cmdlet Get-AzProviderOperation PowerShell. In het volgende voorbeeld worden alle lijstbewerkingen voor opslagaccounts opgeslagen:

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

  • Gebruik de volgende Azure CLI-opdracht om alleen de lijstbewerkingen te filteren:

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

Retourwaarde

Het geretourneerde object verschilt per list functie die u gebruikt. Het voor een opslagaccount retourneert bijvoorbeeld listKeys de volgende indeling:

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

Andere list functies hebben verschillende retourindelingen. Als u de indeling van een functie wilt zien, neemt u deze op in de uitvoersectie, zoals wordt weergegeven in de voorbeeldsjabloon.

Opmerkingen

Geef de resource op met behulp van de resourcenaam of de resourceId-functie. Wanneer u een list functie gebruikt in dezelfde sjabloon die de resource waarnaar wordt verwezen, gebruikt u de resourcenaam.

Als u een list functie gebruikt in een resource die voorwaardelijk is geïmplementeerd, wordt de functie geëvalueerd, zelfs als de resource niet is geïmplementeerd. Er wordt een fout weergegeven als de list functie verwijst naar een resource die niet bestaat. Gebruik de if functie om ervoor te zorgen dat de functie alleen wordt geëvalueerd wanneer de resource wordt geïmplementeerd. Bekijk de functie voor een voorbeeldsjabloon die gebruikmaakt if van en list met een voorwaardelijk geïmplementeerde resource.

Lijstvoorbeeld

In het volgende voorbeeld wordt gebruikgemaakt listKeys van het instellen van een waarde voor implementatiescripts.

"storageAccountSettings": {
  "storageAccountName": "[variables('storageAccountName')]",
  "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

In het volgende voorbeeld ziet u een list functie die een parameter gebruikt. In dit geval is listAccountSasde functie . Geef een object door voor de verlooptijd. De verlooptijd moet in de toekomst zijn.

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

Bepaalt of een resourcetype zones ondersteunt voor de opgegeven locatie of regio. Deze functie ondersteunt alleen zonegebonden resources. Zoneredundante services retourneren een lege matrix. Zie Azure-services die ondersteuning bieden voor Beschikbaarheidszones voor meer informatie.

Gebruik in Bicep de functie pickZones .

Parameters

Parameter Vereist Type Description
providerNamespace Ja tekenreeks De naamruimte van de resourceprovider voor het resourcetype om te controleren op zoneondersteuning.
resourceType Ja tekenreeks Het resourcetype om te controleren op zoneondersteuning.
locatie Ja tekenreeks De regio om te controleren op zoneondersteuning.
numberOfZones Nee geheel getal Het aantal logische zones dat moet worden geretourneerd. De standaardwaarde is 1. Het getal moet een positief geheel getal tussen 1 en 3 zijn. Gebruik 1 voor resources met één zone. Voor resources met meerdere zones moet de waarde kleiner zijn dan of gelijk zijn aan het aantal ondersteunde zones.
offset Nee geheel getal De verschuiving van de logische beginzone. De functie retourneert een fout als offset plus numberOfZones het aantal ondersteunde zones overschrijdt.

Retourwaarde

Een matrix met de ondersteunde zones. Wanneer u de standaardwaarden gebruikt voor offset en numberOfZones, retourneert een resourcetype en regio die zones ondersteunt de volgende matrix:

[
    "1"
]

Wanneer de numberOfZones parameter is ingesteld op 3, wordt het volgende geretourneerd:

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

Wanneer het resourcetype of de resourceregio geen zones ondersteunt, wordt er een lege matrix geretourneerd. Er wordt ook een lege matrix geretourneerd voor zone-redundante services.

[
]

Opmerkingen

Er zijn verschillende categorieën voor Azure Beschikbaarheidszones : zone-redundant en zone-redundant. De pickZones functie kan worden gebruikt om een beschikbaarheidszone voor een zonegebonden resource te retourneren. Voor zone-redundante services (ZRS) retourneert de functie een lege matrix. Zonegebonden resources hebben doorgaans een zones eigenschap op het hoogste niveau van de resourcedefinitie. Zie Azure-services die ondersteuning bieden voor Beschikbaarheidszones om de categorie van ondersteuning voor beschikbaarheidszones te bepalen.

Als u wilt bepalen of een bepaalde Azure-regio of -locatie beschikbaarheidszones ondersteunt, roept u de pickZones functie aan met een zonegebonden resourcetype, zoals Microsoft.Network/publicIPAddresses. Als het antwoord niet leeg is, ondersteunt de regio beschikbaarheidszones.

pickZones-voorbeeld

In de volgende sjabloon ziet u drie resultaten voor het gebruik van de pickZones functie.

{
  "$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')]"
    }
  }
}

De uitvoer van de voorgaande voorbeelden retourneert drie matrices.

Name Type Weergegeven als
ondersteund matrix [ "1" ]
notSupportedRegion matrix []
notSupportedType matrix []

U kunt het antwoord van waaruit pickZones u kunt gebruiken om te bepalen of null moet worden opgegeven voor zones of om virtuele machines toe te wijzen aan verschillende zones. In het volgende voorbeeld wordt een waarde voor de zone ingesteld op basis van de beschikbaarheid van zones.

"zones": {
  "value": "[if(not(empty(pickZones('Microsoft.Compute', 'virtualMachines', 'westus2'))), string(add(mod(copyIndex(),3),1)), json('null'))]"
},

Azure Cosmos DB is geen zonegebonden resource, maar u kunt de pickZones functie gebruiken om te bepalen of zoneredundantie moet worden ingeschakeld voor georeplicatie. Geef het resourcetype Microsoft.Storage/storageAccounts door om te bepalen of zoneredundantie moet worden ingeschakeld.

"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

De functie providers is afgeschaft in ARM-sjablonen. We raden u niet meer aan om het te gebruiken. Als u deze functie hebt gebruikt om een API-versie voor de resourceprovider op te halen, raden we u aan een specifieke API-versie op te geven in uw sjabloon. Als u een dynamisch geretourneerde API-versie gebruikt, kan uw sjabloon worden verbroken als de eigenschappen tussen versies veranderen.

In Bicep is de functie providers afgeschaft.

De providerbewerking is nog steeds beschikbaar via de REST API. Deze kan buiten een ARM-sjabloon worden gebruikt om informatie over een resourceprovider op te halen.

Verwijzing

In de sjablonen zonder symbolische namen:

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

In de sjablonen met symbolische namen:

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

Retourneert een object dat de runtimestatus van een resource vertegenwoordigt. De uitvoer en het gedrag van de reference functie zijn sterk afhankelijk van de manier waarop elke resourceprovider (RP) de PUT- en GET-antwoorden implementeert. Als u een matrix met objecten wilt retourneren die de runtimestatussen van een resourceverzameling vertegenwoordigen, raadpleegt u verwijzingen.

Bicep geeft de referentiefunctie op, maar in de meeste gevallen is de verwijzingsfunctie niet vereist. Het is raadzaam om in plaats daarvan de symbolische naam voor de resource te gebruiken. Raadpleeg verwijzing.

Parameters

Parameter Vereist Type Description
resourceName/resourceIdentifier of symbolicName/resourceIdentifier Ja tekenreeks Geef in de sjablonen zonder symbolische namen de naam of unieke id van een resource op. Wanneer u verwijst naar een resource in de huidige sjabloon, geeft u alleen de resourcenaam op als parameter. Als u verwijst naar een eerder geïmplementeerde resource of wanneer de naam van de resource niet eenduidig is, geeft u de resource-id op.
Geef in de sjablonen met symbolische namen symbolische naam of unieke id van een resource op. Wanneer u verwijst naar een resource in de huidige sjabloon, geeft u alleen de symbolische naam van de resource op als een parameter. Wanneer u verwijst naar een eerder geïmplementeerde resource, geeft u de resource-id op.
apiVersion Nee tekenreeks API-versie van de opgegeven resource. Deze parameter is vereist wanneer de resource niet binnen dezelfde sjabloon is ingericht. Normaal gesproken in de notatie jjjj-mm-dd. Zie de sjabloonreferentie voor geldige API-versies voor uw resource.
'Vol' Nee tekenreeks Waarde die aangeeft of het volledige resourceobject moet worden geretourneerd. Als u dit niet opgeeft 'Full', wordt alleen het eigenschappenobject van de resource geretourneerd. Het volledige object bevat waarden zoals de resource-id en locatie.

Retourwaarde

Elk resourcetype retourneert verschillende eigenschappen voor de referentiefunctie. De functie retourneert geen enkele, vooraf gedefinieerde indeling. De geretourneerde waarde verschilt ook op basis van de waarde van het 'Full' argument. Als u de eigenschappen voor een resourcetype wilt zien, retourneert u het object in de sectie uitvoer, zoals wordt weergegeven in het voorbeeld.

Opmerkingen

Met de referentiefunctie wordt de runtimestatus opgehaald van een eerder geïmplementeerde resource of een resource die is geïmplementeerd in de huidige sjabloon. Dit artikel bevat voorbeelden voor beide scenario's.

Normaal gesproken gebruikt u de reference functie om een bepaalde waarde van een object te retourneren, zoals de URI van het blob-eindpunt of de fully qualified domain name.

"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]"
  }
}

Gebruik 'Full' deze functie wanneer u resourcewaarden nodig hebt die geen deel uitmaken van het eigenschappenschema. Als u bijvoorbeeld toegangsbeleid voor key vault wilt instellen, haalt u de identiteitseigenschappen voor een virtuele machine op.

{
  "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"
          ]
        }
      }
    ],
    ...

Geldig gebruik

De reference functie kan alleen worden gebruikt in de uitvoersectie van een sjabloon of implementatie- en eigenschappenobject van een resourcedefinitie. Het kan niet worden gebruikt voor resource-eigenschappen zoals type, locationnameen andere eigenschappen op het hoogste niveau van de resourcedefinitie. Wanneer u deze functie gebruikt met iteratie van eigenschappen, kunt u de reference functie input gebruiken omdat de expressie is toegewezen aan de resource-eigenschap.

U kunt de reference functie niet gebruiken om de waarde van de count eigenschap in een kopieerlus in te stellen. U kunt andere eigenschappen in de lus instellen. Verwijzing wordt geblokkeerd voor de eigenschap Count, omdat deze eigenschap moet worden bepaald voordat de reference functie wordt omgezet.

Als u de reference functie of een list* functie in de uitvoersectie van een geneste sjabloon wilt gebruiken, moet u de expressionEvaluationOptions functie instellen op het gebruik van evaluatie binnen het bereik of een gekoppelde sjabloon gebruiken in plaats van een geneste sjabloon.

Als u de reference functie gebruikt in een resource die voorwaardelijk is geïmplementeerd, wordt de functie geëvalueerd, zelfs als de resource niet is geïmplementeerd. Er wordt een fout weergegeven als de reference functie verwijst naar een resource die niet bestaat. Gebruik de if functie om ervoor te zorgen dat de functie alleen wordt geëvalueerd wanneer de resource wordt geïmplementeerd. Bekijk de functie voor een voorbeeldsjabloon die gebruikmaakt if van en reference met een voorwaardelijk geïmplementeerde resource.

Impliciete afhankelijkheid

Door de reference functie te gebruiken, declareert u impliciet dat de ene resource afhankelijk is van een andere resource als de resource waarnaar wordt verwezen in dezelfde sjabloon is ingericht en u verwijst naar de resource op naam (niet resource-id). U hoeft de dependsOn eigenschap niet ook te gebruiken. De functie wordt pas geëvalueerd als de resource waarnaar wordt verwezen de implementatie heeft voltooid.

Resourcenaam, symbolische naam of id

Wanneer u verwijst naar een resource die is geïmplementeerd in dezelfde sjabloon met geen symbolische namen, geeft u de naam van de resource op.

"value": "[reference(parameters('storageAccountName'))]"

Wanneer u verwijst naar een resource die is geïmplementeerd in dezelfde sjabloon voor symbolische namen, geeft u de symbolische naam van de resource op.

"value": "[reference('myStorage').primaryEndpoints]"

Or

"value": "[reference('myStorage', '2022-09-01', 'Full').location]"

Wanneer u verwijst naar een resource die niet in dezelfde sjabloon is geïmplementeerd, geeft u de resource-id en apiVersion.

"value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2022-09-01')]"

Om dubbelzinnigheid te voorkomen over welke resource u verwijst, kunt u een volledig gekwalificeerde resource-id opgeven.

"value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName')))]"

Bij het samenstellen van een volledig gekwalificeerde verwijzing naar een resource is de volgorde om segmenten van het type en de naam te combineren niet alleen een samenvoeging van de twee. Gebruik in plaats daarvan na de naamruimte een reeks type-/naamparen van minst specifiek naar meest specifiek:

{resource-provider-namespace}/{parent-resource-type}/{parent-resource-name}[/{child-resource-type}/{child-resource-name}]

Voorbeeld:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt is juist Microsoft.Compute/virtualMachines/extensions/myVM/myExt is niet juist

Gebruik de resourceId() functies die in dit document worden beschreven in plaats van de functie om het maken van een concat() resource-id te vereenvoudigen.

Beheerde identiteit ophalen

Beheerde identiteiten voor Azure-resources zijn extensieresourcetypen die impliciet worden gemaakt voor sommige resources. Omdat de beheerde identiteit niet expliciet is gedefinieerd in de sjabloon, moet u verwijzen naar de resource waarop de identiteit is toegepast. Gebruik Full dit om alle eigenschappen op te halen, inclusief de impliciet gemaakte identiteit.

Het patroon is:

"[reference(resourceId(<resource-provider-namespace>, <resource-name>), <API-version>, 'Full').Identity.propertyName]"

Als u bijvoorbeeld de principal-id wilt ophalen voor een beheerde identiteit die wordt toegepast op een virtuele machine, gebruikt u:

"[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')),'2019-12-01', 'Full').identity.principalId]",

Als u de tenant-id wilt ophalen voor een beheerde identiteit die wordt toegepast op een virtuele-machineschaalset, gebruikt u:

"[reference(resourceId('Microsoft.Compute/virtualMachineScaleSets',  variables('vmNodeType0Name')), 2019-12-01, 'Full').Identity.tenantId]"

Referentievoorbeeld

In het volgende voorbeeld wordt een resource geïmplementeerd en wordt naar die resource verwezen.

{
  "$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')]"
    }
  }
}

In het voorgaande voorbeeld worden de twee objecten geretourneerd. Het eigenschappenobject heeft de volgende indeling:

{
   "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
}

Het volledige object heeft de volgende indeling:

{
  "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"
}

De volgende voorbeeldsjabloon verwijst naar een opslagaccount dat niet in deze sjabloon is geïmplementeerd. Het opslagaccount bestaat al binnen hetzelfde abonnement.

{
  "$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')]"
    }
  }
}

Verwijzingen

references(symbolic name of a resource collection, ['Full', 'Properties])

De references functie werkt op dezelfde manier als reference. In plaats van een object te retourneren dat de runtimestatus van een resource presenteert, retourneert de references functie een matrix met objecten die de runtimestatussen van een resourceverzameling vertegenwoordigen. Voor deze functie is de taalversie van 2.0 de ARM-sjabloon vereist en is symbolische naam ingeschakeld:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  ...
}

In Bicep is er geen expliciete references functie. In plaats daarvan wordt het symbolische verzamelingsgebruik rechtstreeks toegepast en tijdens het genereren van code vertaalt Bicep deze naar een ARM-sjabloon die gebruikmaakt van de FUNCTIE ARM-sjabloon references . Zie Referentieresource-/moduleverzamelingen voor meer informatie.

Parameters

Parameter Vereist Type Description
Symbolische naam van een resourceverzameling Ja tekenreeks Symbolische naam van een resourceverzameling die is gedefinieerd in de huidige sjabloon. De references functie biedt geen ondersteuning voor het verwijzen naar resources buiten de huidige sjabloon.
'Volledig', 'Eigenschappen' Nee tekenreeks Waarde die aangeeft of een matrix van de volledige resourceobjecten moet worden geretourneerd. De standaardwaarde is 'Properties'. Als u dit niet opgeeft 'Full', worden alleen de eigenschappenobjecten van de resources geretourneerd. Het volledige object bevat waarden zoals de resource-id en locatie.

Retourwaarde

Een matrix van de resourceverzameling. Elk resourcetype retourneert verschillende eigenschappen voor de reference functie. De geretourneerde waarde verschilt ook op basis van de waarde van het 'Full' argument. Zie de naslaginformatie voor meer informatie.

De uitvoervolgorde van references wordt altijd in oplopende volgorde gerangschikt op basis van de kopieerindex. Daarom wordt de eerste resource in de verzameling met index 0 eerst weergegeven, gevolgd door index 1, enzovoort. Bijvoorbeeld [worker-0, worker-1, worker-2, ...].

Als in het voorgaande voorbeeld worker-0 en worker-2 worden geïmplementeerd terwijl worker-1 niet te wijten is aan een onwaar-voorwaarde, laat de uitvoer van references de niet-geïmplementeerde resource weg en worden de geïmplementeerde resources weergegeven, gesorteerd op hun nummers. De uitvoer references is [worker-0, worker-2, ...]. Als alle resources worden weggelaten, retourneert de functie een lege matrix.

Geldig gebruik

De references functie kan niet worden gebruikt binnen resourcekopielussen of Bicep voor lus. Is bijvoorbeeld references niet toegestaan in het volgende scenario:

{
  resources: {
    "resourceCollection": {
       "copy": { ... },
       "properties": {
         "prop": "[references(...)]"
       }
    }
  }
}

Als u de references functie of een list* functie in de uitvoersectie van een geneste sjabloon wilt gebruiken, moet u de expressionEvaluationOptions functie instellen op het gebruik van evaluatie binnen het bereik of een gekoppelde sjabloon gebruiken in plaats van een geneste sjabloon.

Impliciete afhankelijkheid

Door de references functie te gebruiken, declareert u impliciet dat de ene resource afhankelijk is van een andere resource. U hoeft de dependsOn eigenschap niet ook te gebruiken. De functie wordt pas geëvalueerd als de resource waarnaar wordt verwezen de implementatie heeft voltooid.

Referentievoorbeeld

In het volgende voorbeeld wordt een resourceverzameling geïmplementeerd en wordt verwezen naar die resourceverzameling.

{
  "$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')]"
    }
  }
}

In het voorgaande voorbeeld worden de drie objecten geretourneerd.

"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

Zie de resourceGroup-bereikfunctie.

Gebruik in Bicep de bereikfunctie resourcegroep .

resourceId

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

Retourneert de unieke id van een resource. U gebruikt deze functie wanneer de resourcenaam niet eenduidig is of niet is ingericht binnen dezelfde sjabloon. De indeling van de geretourneerde id is afhankelijk van of de implementatie plaatsvindt binnen het bereik van een resourcegroep, abonnement, beheergroep of tenant.

Gebruik in Bicep de functie resourceId .

Parameters

Parameter Vereist Type Description
subscriptionId Nee tekenreeks (in GUID-indeling) De standaardwaarde is het huidige abonnement. Geef deze waarde op wanneer u een resource in een ander abonnement moet ophalen. Geef deze waarde alleen op bij de implementatie binnen het bereik van een resourcegroep of abonnement.
resourceGroupName Nee tekenreeks De standaardwaarde is de huidige resourcegroep. Geef deze waarde op wanneer u een resource in een andere resourcegroep wilt ophalen. Geef deze waarde alleen op bij de implementatie binnen het bereik van een resourcegroep.
resourceType Ja tekenreeks Type resource, inclusief resourceprovidernaamruimte.
resourceName1 Ja tekenreeks Naam van resource.
resourceName2 Nee tekenreeks Volgend resourcenaamsegment, indien nodig.

Ga door met het toevoegen van resourcenamen als parameters wanneer het resourcetype meer segmenten bevat.

Retourwaarde

De resource-id wordt geretourneerd in verschillende indelingen voor verschillende bereiken:

  • Bereik van resourcegroep:

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

  • Abonnementsbereik:

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

  • Beheergroep of tenantbereik:

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

Om verwarring te voorkomen, wordt u aangeraden niet te gebruiken resourceId bij het werken met resources die zijn geïmplementeerd in het abonnement, de beheergroep of de tenant. Gebruik in plaats daarvan de id-functie die is ontworpen voor het bereik.

  • Gebruik de functie subscriptionResourceId voor resources op abonnementsniveau.
  • Gebruik de functie managementGroupResourceId voor resources op beheergroepsniveau. Gebruik de functie extensionResourceId om te verwijzen naar een resource die is geïmplementeerd als een uitbreiding van een beheergroep. Aangepaste beleidsdefinities die zijn geïmplementeerd in een beheergroep zijn bijvoorbeeld extensies van de beheergroep. Gebruik de functie tenantResourceId om te verwijzen naar resources die zijn geïmplementeerd in de tenant, maar beschikbaar zijn in uw beheergroep. Ingebouwde beleidsdefinities worden bijvoorbeeld geïmplementeerd als resources op tenantniveau.
  • Gebruik de functie tenantResourceId voor resources op tenantniveau. Gebruiken tenantResourceId voor ingebouwde beleidsdefinities, omdat ze op tenantniveau worden geïmplementeerd.

Opmerkingen

Het aantal parameters dat u opgeeft, is afhankelijk van of de resource een bovenliggende of onderliggende resource is en of de resource zich in hetzelfde abonnement of dezelfde resourcegroep bevindt.

Als u de resource-id voor een bovenliggende resource in hetzelfde abonnement en dezelfde resourcegroep wilt ophalen, geeft u het type en de naam van de resource op.

"[resourceId('Microsoft.ServiceBus/namespaces', 'namespace1')]"

Als u de resource-id voor een onderliggende resource wilt ophalen, moet u letten op het aantal segmenten in het resourcetype. Geef een resourcenaam op voor elk segment van het resourcetype. De naam van het segment komt overeen met de resource die voor dat deel van de hiërarchie bestaat.

"[resourceId('Microsoft.ServiceBus/namespaces/queues/authorizationRules', 'namespace1', 'queue1', 'auth1')]"

Als u de resource-id voor een resource in hetzelfde abonnement maar een andere resourcegroep wilt ophalen, geeft u de naam van de resourcegroep op.

"[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts', 'examplestorage')]"

Als u de resource-id voor een resource in een ander abonnement en een andere resourcegroep wilt ophalen, geeft u de abonnements-id en de naam van de resourcegroep op.

"[resourceId('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"

Vaak moet u deze functie gebruiken bij het gebruik van een opslagaccount of virtueel netwerk in een alternatieve resourcegroep. In het volgende voorbeeld ziet u hoe een resource van een externe resourcegroep eenvoudig kan worden gebruikt:

{
  "$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')]"
              }
            }
          }
        ]
      }
    }
  ]
}

Voorbeeld van resource-id

In het volgende voorbeeld wordt de resource-id voor een opslagaccount in de resourcegroep geretourneerd:

{
  "$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')]"
    }
  }
}

De uitvoer uit het voorgaande voorbeeld met de standaardwaarden is:

Name Type Weergegeven als
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-11111-111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutput String /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

abonnement

Zie de functie abonnementsbereik.

Gebruik in Bicep de functie abonnementsbereik .

subscriptionResourceId

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

Retourneert de unieke id voor een resource die is geïmplementeerd op abonnementsniveau.

Gebruik in Bicep de functie subscriptionResourceId .

Parameters

Parameter Vereist Type Description
subscriptionId Nee tekenreeks (in GUID-indeling) De standaardwaarde is het huidige abonnement. Geef deze waarde op wanneer u een resource in een ander abonnement moet ophalen.
resourceType Ja tekenreeks Type resource, inclusief resourceprovidernaamruimte.
resourceName1 Ja tekenreeks Naam van resource.
resourceName2 Nee tekenreeks Volgend resourcenaamsegment, indien nodig.

Ga door met het toevoegen van resourcenamen als parameters wanneer het resourcetype meer segmenten bevat.

Retourwaarde

De id wordt geretourneerd in de volgende indeling:

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

Opmerkingen

U gebruikt deze functie om de resource-id op te halen voor resources die zijn geïmplementeerd in het abonnement in plaats van een resourcegroep. De geretourneerde id verschilt van de waarde die door de resourceId-functie wordt geretourneerd door het niet opnemen van een resourcegroepwaarde.

voorbeeld subscriptionResourceID

Met de volgende sjabloon wordt een ingebouwde rol toegewezen. U kunt deze implementeren in een resourcegroep of abonnement. De functie gebruikt de subscriptionResourceId functie om de resource-id op te halen voor ingebouwde rollen.

{
  "$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], ...)

Retourneert de unieke id voor een resource die is geïmplementeerd op het niveau van de beheergroep.

Gebruik in Bicep de functie managementGroupResourceId .

Parameters

Parameter Vereist Type Description
managementGroupResourceId Nee tekenreeks (in GUID-indeling) De standaardwaarde is de huidige beheergroep. Geef deze waarde op wanneer u een resource in een andere beheergroep moet ophalen.
resourceType Ja tekenreeks Type resource, inclusief resourceprovidernaamruimte.
resourceName1 Ja tekenreeks Naam van resource.
resourceName2 Nee tekenreeks Volgend resourcenaamsegment, indien nodig.

Ga door met het toevoegen van resourcenamen als parameters wanneer het resourcetype meer segmenten bevat.

Retourwaarde

De id wordt geretourneerd in de volgende indeling:

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

Opmerkingen

U gebruikt deze functie om de resource-id op te halen voor resources die zijn geïmplementeerd in de beheergroep in plaats van een resourcegroep. De geretourneerde id verschilt van de waarde die wordt geretourneerd door de resourceId-functie door geen abonnements-id en een resourcegroepwaarde op te geven.

voorbeeld managementGroupResourceID

Met de volgende sjabloon wordt een beleidsdefinitie gemaakt en toegewezen. De functie gebruikt de managementGroupResourceId functie om de resource-id voor beleidsdefinitie op te halen.

{
  "$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], ...)

Retourneert de unieke id voor een resource die is geïmplementeerd op tenantniveau.

Gebruik in Bicep de functie tenantResourceId .

Parameters

Parameter Vereist Type Description
resourceType Ja tekenreeks Type resource, inclusief resourceprovidernaamruimte.
resourceName1 Ja tekenreeks Naam van resource.
resourceName2 Nee tekenreeks Volgend resourcenaamsegment, indien nodig.

Ga door met het toevoegen van resourcenamen als parameters wanneer het resourcetype meer segmenten bevat.

Retourwaarde

De id wordt geretourneerd in de volgende indeling:

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

Opmerkingen

U gebruikt deze functie om de resource-id op te halen voor een resource die in de tenant is geïmplementeerd. De geretourneerde id verschilt van de waarden die worden geretourneerd door andere resource-id-functies door geen resourcegroep- of abonnementswaarden op te geven.

voorbeeld tenantResourceId

Ingebouwde beleidsdefinities zijn resources op tenantniveau. Als u een beleidstoewijzing wilt implementeren die verwijst naar een ingebouwde beleidsdefinitie, gebruikt u de tenantResourceId functie.

{
  "$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'))]"
      }
    }
  ]
}

Volgende stappen