Funzioni delle risorse per i modelli di Azure Resource Manager

Articolo
03/18/2024

Resource Manager offre le funzioni seguenti per ottenere i valori delle risorse nel modello di Azure Resource Manager (modello di Resource Manager):

extensionResourceId
list*
pickZones
provider (deprecato)
reference
references
resourceId
subscriptionResourceId
managementGroupResourceId
tenantResourceId

Per ottenere valori dai parametri, dalle variabili o dalla distribuzione corrente, vedere Funzioni dei valori della distribuzione.

Per ottenere i valori dell'ambito di distribuzione, vedere Funzioni di ambito.

Suggerimento

È consigliabile Bicep perché offre le stesse funzionalità dei modelli di ARM e la sintassi è più semplice da usare. Per altre informazioni, vedere Funzioni delle risorse .

extensionResourceId

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

Restituisce l'ID risorsa per una risorsa di estensione. Una risorsa di estensione è un tipo di risorsa applicato a un'altra risorsa da aggiungere alle relative funzionalità.

In Bicep usare la funzione extensionResourceId .

Parametri

Parametro	Richiesto	Type	Descrizione
baseResourceId	Sì	string	L'ID della risorsa a cui la risorsa di estensione è applicata.
resourceType	Sì	string	Tipo della risorsa di estensione, incluso lo spazio dei nomi del provider di risorse.
resourceName1	Sì	string	Nome della risorsa di estensione.
resourceName2	No	string	Segmento successivo del nome della risorsa, se necessario.

Continuare ad aggiungere i nomi di risorsa come parametri quando il tipo di risorsa include più segmenti.

Valore restituito

Il formato di base dell'ID della risorsa restituito da questa funzione è:

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

Il segmento di ambito varia in base alla risorsa di base estesa. Ad esempio, l'ID di una sottoscrizione ha segmenti diversi rispetto all'ID per un gruppo di risorse.

Quando la risorsa di estensione viene applicata a una risorsa, l'ID della risorsa viene restituito nel formato seguente:

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

Quando la risorsa di estensione viene applicata a un gruppo di risorse, il formato restituito è:

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

Un esempio di utilizzo di questa funzione con un gruppo di risorse è illustrato nella sezione successiva.

Quando la risorsa di estensione viene applicata a una sottoscrizione, il formato restituito è:

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

Quando la risorsa di estensione viene applicata a un gruppo di gestione, il formato restituito è:

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

Un esempio di utilizzo di questa funzione con un gruppo di gestione è illustrato nella sezione successiva.

Esempio di funzione extensionResourceId

L'esempio seguente restituisce l'ID della risorsa per un blocco del gruppo di risorse.

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

Una definizione di criteri personalizzata distribuita in un gruppo di gestione viene implementata come risorsa di estensione. Per creare e assegnare un criterio, distribuire il modello seguente in un gruppo di gestione.

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

Le definizioni di criteri predefinite sono risorse a livello di tenant. Per un esempio di distribuzione di una definizione di criteri predefinita, vedere tenantResourceId.

list*

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

La sintassi per questa funzione varia in base al nome delle operazioni list. Ogni implementazione restituisce i valori per il tipo di risorsa che supporta un'operazione list. Il nome dell'operazione deve iniziare con list e può avere un suffisso. Tra gli usi comuni vi sono list, listKeys, listKeyValue e listSecrets.

In Bicep usare la funzione list* .

Parametri

Parametro	Richiesto	Type	Descrizione
resourceName o resourceIdentifier	Sì	string	Identificatore univoco della risorsa.
apiVersion	Sì	string	Versione dell'API dello stato di runtime della risorsa. In genere il formato è aaaa-mm-gg.
functionValues	No	oggetto	Oggetto che contiene valori per la funzione. Specificare solo questo oggetto per le funzioni che supportano la ricezione di un oggetto con valori di parametro, ad esempio `listAccountSas` per un account di archiviazione. Questo articolo illustra un esempio di passaggio dei valori di funzione.

Usi validi

Le funzioni elenco possono essere usate nelle proprietà di una definizione di risorsa. Non usare una funzione elenco che espone informazioni riservate nella sezione output di un modello. I valori di output vengono archiviati nella cronologia di distribuzione e possono essere recuperati da un utente malintenzionato.

Quando usate con iterazione proprietà, è possibile usare le funzioni list per input in quanto l'espressione viene assegnata alla proprietà della risorsa. Non è possibile usarle con count perché è necessario determinare il numero prima che la funzione list venga risolta.

Implementazioni

Gli utilizzi possibili di list* sono visualizzati nella tabella seguente.

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

Per determinare quali tipi di risorse dispongono di un'operazione list, usare le opzioni seguenti:

Visualizzare le operazioni dell'API REST di un provider di risorse e individuare le operazioni list. Gli account di archiviazione, ad esempio, dispongono dell'operazione listKeys.
Usare get -AzProviderCmdlet di PowerShell per l'operazione . L'esempio seguente ottiene tutte le operazioni list degli account di archiviazione:
```
Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
```

Usare il comando seguente dell'interfaccia della riga di comando di Azure per filtrare solo le operazioni list:

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

Valore restituito

L'oggetto restituito varia in base alla list funzione usata. La funzione listKeys per un account di archiviazione restituisce, ad esempio, il seguente formato:

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

Altre funzioni list possono avere formati di restituzione diversi. Per visualizzare il formato di una funzione, includerlo nella sezione outputs, come mostrato nel modello di esempio.

Osservazioni:

Specificare la risorsa usando il nome della risorsa stessa o la funzione resourceId. Quando si usa una list funzione nello stesso modello che distribuisce la risorsa a cui si fa riferimento, usare il nome della risorsa.

Se si usa una funzione list in una risorsa distribuita in modo condizionale, la funzione viene valutata anche se la risorsa non viene distribuita. Se la funzione list fa riferimento a una risorsa che non esiste, viene visualizzato un errore. Usare la if funzione per assicurarsi che la funzione venga valutata solo quando la risorsa viene distribuita. Vedi la funzione if per un modello di esempio che usa if e list con una risorsa distribuita in modo condizionale.

Esempio di funzione list

Nell'esempio seguente viene listKeys usato quando si imposta un valore per gli script di distribuzione.

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

Nell'esempio seguente viene illustrata una funzione list che accetta un parametro. In questo caso, la funzione è listAccountSas. Passare un oggetto per l'ora di scadenza. L'ora di scadenza deve essere futura.

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

Determina se un tipo di risorsa supporta le zone per la posizione o l'area specificata. Questa funzione supporta solo le risorse di zona. I servizi con ridondanza della zona restituiscono una matrice vuota. Per altre informazioni, vedere Servizi di Azure che supportano le zonedi disponibilità.

In Bicep usare la funzione pickZones .

Parametri

Parametro	Richiesto	Type	Descrizione
providerNamespace	Sì	string	Spazio dei nomi del provider di risorse per il tipo di risorsa da verificare per il supporto della zona.
resourceType	Sì	string	Tipo di risorsa da verificare per il supporto della zona.
posizione	Sì	string	Area in cui verificare il supporto della zona.
numberOfZones	No	integer	Numero di zone logiche da restituire. Il valore predefinito è 1. Il numero deve essere un numero intero positivo compreso tra 1 e 3. Usare 1 per le risorse a zona singola. Per le risorse con più zone, il valore deve essere minore o uguale al numero di zone supportate.
offset	No	integer	Scostamento dalla zona logica iniziale. La funzione restituisce un errore se scostamento più numberOfZones supera il numero di zone supportate.

Valore restituito

Matrice con le zone supportate. Quando si usano i valori predefiniti per scostamento e numberOfZones, un tipo di risorsa e un'area che supporta le zone restituisce la matrice seguente:

[
    "1"
]

Quando il parametro numberOfZones è impostato su 3, restituisce:

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

Quando il tipo di risorsa o l'area non supporta le zone, viene restituita una matrice vuota. Viene restituita anche una matrice vuota per i servizi con ridondanza della zona.

[
]

Osservazioni:

Esistono diverse categorie per le zone di disponibilità di Azure: zona e ridondanza della zona. La funzione pickZones può essere usata per restituire una zona di disponibilità per una risorsa di zona. Per i servizi con ridondanza della zona (ZRS, archiviazione con ridondanza della zona), la funzione restituisce una matrice vuota. Le risorse di zona in genere hanno una proprietà zones al livello superiore della definizione della risorsa. Per determinare la categoria di supporto per le zone di disponibilità, vedere Servizi di Azure che supportano le zone di disponibilità.

Per determinare se un'area o una località di Azure specifica supporta le zone di disponibilità, chiamare la funzione pickZones con un tipo di risorsa di zona, ad esempio Microsoft.Network/publicIPAddresses. Se la risposta non è vuota, l'area supporta le zone di disponibilità.

Esempio di pickZones

Il modello seguente mostra tre risultati per l'uso della pickZones funzione .

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

L'output degli esempi precedenti restituisce tre matrici.

Nome	Type	Valore
supportato	array	[ "1" ]
notSupportedRegion	array	[]
notSupportedType	array	[]

È possibile usare la risposta da pickZones per determinare se specificare null per le zone o assegnare macchine virtuali a zone diverse. Nell'esempio seguente viene impostato un valore per la zona in base alla disponibilità delle zone.

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

Azure Cosmos DB non è una risorsa di zona, ma è possibile usare la funzione per determinare se abilitare la pickZones ridondanza della zona per la georeplicazione. Passare microsoft.Archiviazione Tipo di risorsa /storageAccounts per determinare se abilitare la ridondanza della zona.

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

provider

La funzione provider è stata deprecata nei modelli di Resource Manager. Il suo utilizzo non è più consigliato. Se è stata usata questa funzione per ottenere una versione API per il provider di risorse, è consigliabile fornire una versione API specifica nel modello. L'uso di una versione API restituita dinamicamente può interrompere il modello se le proprietà cambiano tra le versioni.

In Bicep la funzione providers è deprecata.

L'operazione dei provider è ancora disponibile tramite l'API REST. Può essere usato all'esterno di un modello di Resource Manager per ottenere informazioni su un provider di risorse.

reference

Nei modelli senza nomi simbolici:

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

Nei modelli con nomi simbolici:

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

Restituisce un oggetto che rappresenta lo stato di runtime di una risorsa. L'output e il comportamento della reference funzione si basano molto sul modo in cui ogni provider di risorse implementa le risposte PUT e GET. Per restituire una matrice di oggetti che rappresentano gli stati di runtime di un insieme di risorse, vedere riferimenti.

Bicep fornisce la funzione di riferimento, ma nella maggior parte dei casi la funzione di riferimento non è necessaria. È consigliabile usare invece il nome simbolico per la risorsa. Vedi le informazioni di riferimento.

Parametri

Parametro	Richiesto	Type	Descrizione
resourceName/resourceIdentifier o symbolicName/resourceIdentifier	Sì	string	Nei modelli senza nomi simbolici specificare il nome o l'identificatore univoco di una risorsa. Quando si fa riferimento a una risorsa nel modello corrente, specificare solo il nome della risorsa come parametro. Quando si fa riferimento a una risorsa distribuita in precedenza o quando il nome della stessa è ambiguo, fornire l'ID della risorsa. Nei modelli con nomi simbolici specificare il nome simbolico o l'identificatore univoco di una risorsa. Quando si fa riferimento a una risorsa nel modello corrente, specificare solo il nome simbolico della risorsa come parametro. Quando si fa riferimento a una risorsa distribuita in precedenza, specificare l'ID risorsa.
apiVersion	No	string	Versione dell'API della risorsa specificata. Questo parametro è obbligatorio quando non viene eseguito il provisioning della risorsa nello stesso modello. In genere il formato è aaaa-mm-gg. Per le versioni delle API valide per la risorsa, vedere la documentazione di riferimento per il modello.
'Full'	No	string	Valore che specifica se restituire l'oggetto risorsa completo. Se non si specifica `'Full'`, viene restituito solo l'oggetto proprietà della risorsa. L'oggetto completo include valori quali l'ID e la posizione della risorsa.

Valore restituito

Ogni tipo di risorsa restituisce proprietà diverse per la funzione di riferimento. La funzione non restituisce un singolo formato predefinito. Il valore restituito è inoltre diverso in base al valore dell'argomento 'Full'. Per visualizzare le proprietà per un tipo di risorsa, restituire l'oggetto nella sezione output, come illustrato nell'esempio.

Osservazioni:

La funzione reference recupera lo stato di runtime di una risorsa distribuita in precedenza o di una risorsa distribuita nel modello corrente. Questo articolo contiene esempi relativi a entrambi gli scenari.

In genere, si usa la reference funzione per restituire un determinato valore da un oggetto, ad esempio l'URI dell'endpoint BLOB o il nome di dominio completo.

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

Usare 'Full' se sono necessari valori della risorsa che non fanno parte dello schema delle proprietà. Per impostare criteri di accesso all'insieme di credenziali delle chiavi, ad esempio, ottenere le proprietà di identità per una macchina virtuale.

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

Usi validi

La reference funzione può essere usata solo nella sezione output di un modello o di un oggetto distribuzione e proprietà di una definizione di risorsa. Non può essere usato per le proprietà delle risorse, ad typeesempio , namelocation e altre proprietà di primo livello della definizione della risorsa. Se usato con l'iterazione delle proprietà, è possibile usare la reference funzione per input perché l'espressione viene assegnata alla proprietà della risorsa.

Non è possibile usare la reference funzione per impostare il valore della count proprietà in un ciclo di copia. Può essere usata per impostare altre proprietà nel ciclo. Il riferimento è bloccato per la proprietà count perché tale proprietà deve essere determinata prima che la reference funzione venga risolta.

Per usare la funzione o qualsiasi list* funzione nella sezione outputs di un modello annidato, è necessario impostare per usare la reference valutazione dell'ambito expressionEvaluationOptions interno o usare un modello collegato anziché un modello annidato.

Se si usa la reference funzione in una risorsa distribuita in modo condizionale, la funzione viene valutata anche se la risorsa non viene distribuita. Se la funzione reference fa riferimento a una risorsa che non esiste, viene visualizzato un errore. Usare la if funzione per assicurarsi che la funzione venga valutata solo quando la risorsa viene distribuita. Vedi la funzione if per un modello di esempio che usa if e reference con una risorsa distribuita in modo condizionale.

Dipendenza implicita

Usando la reference funzione , si dichiara in modo implicito che una risorsa dipende da un'altra risorsa se viene effettuato il provisioning della risorsa a cui si fa riferimento nello stesso modello e si fa riferimento alla risorsa in base al nome (non all'ID risorsa). Non è necessario usare anche la dependsOn proprietà . La funzione non viene valutata fino a quando la risorsa cui si fa riferimento ha completato la distribuzione.

Nome risorsa, nome simbolico o identificatore

Quando si fa riferimento a una risorsa distribuita nello stesso modello di nome non simbolico, specificare il nome della risorsa.

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

Quando si fa riferimento a una risorsa distribuita nello stesso modello di nome simbolico, specificare il nome simbolico della risorsa.

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

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

Quando si fa riferimento a una risorsa che non è distribuita nello stesso modello, fornire l'ID della risorsa e apiVersion.

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

Per evitare ambiguità sulla risorsa a cui fare riferimento è possibile fornire un identificatore completo della risorsa.

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

Quando si crea un riferimento completo a una risorsa, l'ordine di combinazione dei segmenti dal tipo e dal nome non è semplicemente una concatenazione dei due elementi. Dopo lo spazio dei nomi, usare invece una sequenza di coppie tipo/nome dal meno specifico al più specifico:

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

Ad esempio:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt è corretto Microsoft.Compute/virtualMachines/extensions/myVM/myExt non è corretto

Per semplificare la creazione di un ID della risorsa, usare le funzioni resourceId() descritte in questo documento invece della funzione concat().

Ottenere l'identità gestita

Le identità gestite per le risorse di Azure sono tipi di risorse di estensione create in modo implicito per alcune risorse. Poiché l'identità gestita non è definita in modo esplicito nel modello, è necessario fare riferimento alla risorsa a cui viene applicata l'identità. Usare Full per ottenere tutte le proprietà, inclusa l'identità creata in modo implicito.

Il modello è:

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

Ad esempio, per ottenere l'ID entità per un'identità gestita applicata a una macchina virtuale, usare:

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

In alternativa, per ottenere l'ID tenant per un'identità gestita applicata a un set di scalabilità di macchine virtuali, usare:

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

Esempio della funzione reference

Nell'esempio seguente viene distribuita una risorsa e viene fatto riferimento a tale risorsa.

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

L'esempio precedente restituisce i due oggetti. L'oggetto proprietà è nel formato seguente:

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

L'oggetto completo è nel formato seguente:

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

Il modello di esempio seguente fa riferimento a un account di archiviazione non distribuito in questo modello. L'account di archiviazione esiste già nella stessa sottoscrizione.

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

references

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

La references funzione funziona in modo analogo a reference. Anziché restituire un oggetto che presenta lo stato di runtime di una risorsa, la references funzione restituisce una matrice di oggetti che rappresentano gli stati di runtime di una raccolta di risorse. Questa funzione richiede la versione 2.0 del linguaggio del modello arm e con il nome simbolico abilitato:

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

In Bicep non esiste alcuna funzione esplicita references . L'utilizzo della raccolta simbolica viene invece usato direttamente e, durante la generazione del codice, Bicep lo converte in un modello di Resource Manager che usa la funzione del modello references di Resource Manager. Per altre informazioni, vedere Raccolte di risorse/moduli di riferimento.

Parametri

Parametro	Richiesto	Type	Descrizione
Nome simbolico di una raccolta di risorse	Sì	string	Nome simbolico di una raccolta di risorse definita nel modello corrente. La `references` funzione non supporta il riferimento alle risorse esterne al modello corrente.
'Full', 'Properties'	No	string	Valore che specifica se restituire una matrice degli oggetti risorsa completi. Il valore predefinito è `'Properties'`. Se non si specifica `'Full'`, vengono restituiti solo gli oggetti proprietà delle risorse. L'oggetto completo include valori quali l'ID e la posizione della risorsa.

Valore restituito

Matrice della raccolta di risorse. Ogni tipo di risorsa restituisce proprietà diverse per la reference funzione. Il valore restituito è inoltre diverso in base al valore dell'argomento 'Full'. Per altre informazioni, vedere informazioni di riferimento.

L'ordine di output di references viene sempre disposto in ordine crescente in base all'indice di copia. Pertanto, la prima risorsa nella raccolta con indice 0 viene visualizzata per prima, seguita dall'indice 1 e così via. Ad esempio, [worker-0, worker-1, worker-2, ...].

Nell'esempio precedente, se worker-0 e worker-2 vengono distribuiti mentre worker-1 non è dovuto a una condizione falsa, l'output di references ometterà la risorsa non distribuita e visualizzerà quelli distribuiti, ordinati in base ai numeri. L'output di references sarà [worker-0, worker-2, ...]. Se tutte le risorse vengono omesse, la funzione restituisce una matrice vuota.

Usi validi

La references funzione non può essere usata all'interno dei cicli di copia delle risorse o del ciclo Bicep for. Ad esempio, references non è consentito nello scenario seguente:

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

Per usare la funzione o qualsiasi list* funzione nella sezione outputs di un modello annidato, è necessario impostare per usare la references valutazione dell'ambito expressionEvaluationOptions interno o usare un modello collegato anziché un modello annidato.

Dipendenza implicita

Usando la references funzione, si dichiara in modo implicito che una risorsa dipende da un'altra risorsa. Non è necessario usare anche la dependsOn proprietà . La funzione non viene valutata fino a quando la risorsa cui si fa riferimento ha completato la distribuzione.

Esempio della funzione reference

Nell'esempio seguente viene distribuita una raccolta di risorse e viene fatto riferimento alla raccolta di risorse.

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

Nell'esempio precedente vengono restituiti i tre oggetti .

"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

Vedere la funzione di ambito resourceGroup.

In Bicep usare la funzione ambito resourcegroup .

resourceId

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

Restituisce l'identificatore univoco di una risorsa. Questa funzione viene usata quando il nome della risorsa è ambiguo o non è stato sottoposto a provisioning all'interno dello stesso modello. Il formato dell'identificatore restituito varia a seconda che la distribuzione venga eseguita nell'ambito di un gruppo di risorse, di una sottoscrizione, di un gruppo di gestione o di un tenant.

In Bicep usare la funzione resourceId .

Parametri

Parametro	Richiesto	Type	Descrizione
subscriptionId	No	Stringa (in formato GUID)	Il valore predefinito è la sottoscrizione corrente. Specificare questo valore quando si vuole recuperare una risorsa in un'altra sottoscrizione. Fornire questo valore solo quando si distribuisce nell'ambito di un gruppo di risorse o di una sottoscrizione.
resourceGroupName	No	string	Il valore predefinito è il gruppo di risorse corrente. Specificare questo valore quando si vuole recuperare una risorsa in un altro gruppo di risorse. Fornire questo valore solo quando si distribuisce nell'ambito di un gruppo di risorse.
resourceType	Sì	string	Tipo di risorsa, incluso lo spazio dei nomi del provider di risorse.
resourceName1	Sì	string	Nome della risorsa.
resourceName2	No	string	Segmento successivo del nome della risorsa, se necessario.

Continuare ad aggiungere i nomi di risorsa come parametri quando il tipo di risorsa include più segmenti.

Valore restituito

L'ID risorsa viene restituito in formati diversi in ambiti diversi:

Ambito del gruppo di risorse:

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

Ambito sottoscrizione:

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

Ambito del gruppo di gestione o del tenant:

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

Per evitare confusione, è consigliabile non usare quando si usano resourceId le risorse distribuite nella sottoscrizione, nel gruppo di gestione o nel tenant. Usare invece la funzione ID progettata per l'ambito.

Per le risorse a livello di sottoscrizione, usare la funzione subscriptionResourceId .
Per le risorse a livello di gruppo di gestione, usare la funzione managementGroupResourceId . Usare la funzione extensionResourceId per fare riferimento a una risorsa implementata come estensione di un gruppo di gestione. Ad esempio, le definizioni di criteri personalizzate distribuite in un gruppo di gestione sono estensioni del gruppo di gestione. Usare la funzione tenantResourceId per fare riferimento alle risorse distribuite nel tenant, ma disponibili nel gruppo di gestione. Ad esempio, le definizioni di criteri predefinite vengono implementate come risorse a livello di tenant.
Per le risorse a livello di tenant, usare la funzione tenantResourceId . Usare tenantResourceId per le definizioni di criteri predefinite perché vengono implementate a livello di tenant.

Osservazioni:

Il numero di parametri forniti varia a seconda che la risorsa sia una risorsa padre o figlio e che si trovi nella stessa sottoscrizione o gruppo di risorse.

Per ottenere l'ID della risorsa per una risorsa padre nella stessa sottoscrizione e nello stesso gruppo di risorse, specificare il tipo e il nome della risorsa.

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

Per ottenere l'ID della risorsa per una risorsa figlio, prestare attenzione al numero di segmenti nel tipo di risorsa. Specificare un nome di risorsa per ogni segmento del tipo di risorsa. Il nome del segmento corrisponde alla risorsa esistente per quella parte della gerarchia.

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

Per ottenere l'ID di una risorsa nella stessa sottoscrizione ma in un diverso gruppo di risorse, fornire il nome del gruppo di risorse.

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

Per ottenere l'ID di una risorsa in una diversa sottoscrizione e in un diverso gruppo di risorse, fornire l'ID della sottoscrizione e il nome del gruppo di risorse.

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

Spesso è necessario usare questa funzione quando si usa un account di archiviazione o una rete virtuale in un gruppo di risorse alternative. L'esempio seguente mostra come usare facilmente una risorsa di un gruppo di risorse esterno:

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

Esempio di ID della risorsa

L'esempio seguente restituisce l'ID della risorsa per un account di archiviazione nel gruppo di risorse:

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

L'output dell'esempio precedente con i valori predefiniti è il seguente:

Nome	Type	Valore
sameRGOutput	String	/subscriptions/{id-sott-corrente}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutput	String	/subscriptions/{id-sott-corrente}/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/{id-sott-corrente}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

sottoscrizione

Vedere la funzione di ambito della sottoscrizione.

In Bicep, usa la funzione di ambito sottoscrizione .

subscriptionResourceId

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

Restituisce l'identificatore univoco per una risorsa distribuita a livello di sottoscrizione.

In Bicep usare la funzione subscriptionResourceId .

Parametri

Parametro	Richiesto	Type	Descrizione
subscriptionId	No	stringa (in formato GUID)	Il valore predefinito è la sottoscrizione corrente. Specificare questo valore quando si vuole recuperare una risorsa in un'altra sottoscrizione.
resourceType	Sì	string	Tipo di risorsa, incluso lo spazio dei nomi del provider di risorse.
resourceName1	Sì	string	Nome della risorsa.
resourceName2	No	string	Segmento successivo del nome della risorsa, se necessario.

Continuare ad aggiungere i nomi di risorsa come parametri quando il tipo di risorsa include più segmenti.

Valore restituito

L'identificatore viene restituito nel formato seguente:

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

Osservazioni:

Usare questa funzione per ottenere l'ID della risorsa per le risorse distribuite nella sottoscrizione anziché in un gruppo di risorse. L'ID restituito è diverso dal valore restituito dalla funzione resourceId dal momento che non include il valore di un gruppo di risorse.

Esempio di subscriptionResourceID

Il modello seguente assegna un ruolo predefinito. È possibile distribuirlo in un gruppo di risorse o in una sottoscrizione. Usa la funzione subscriptionResourceId per ottenere l'ID risorsa per i ruoli predefiniti.

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

Restituisce l'identificatore univoco per una risorsa distribuita a livello di gruppo di gestione.

In Bicep usare la funzione managementGroupResourceId .

Parametri

Parametro	Richiesto	Type	Descrizione
managementGroupResourceId	No	stringa (in formato GUID)	Il valore predefinito è il gruppo di gestione corrente. Specificare questo valore quando è necessario recuperare una risorsa in un altro gruppo di gestione.
resourceType	Sì	string	Tipo di risorsa, incluso lo spazio dei nomi del provider di risorse.
resourceName1	Sì	string	Nome della risorsa.
resourceName2	No	string	Segmento successivo del nome della risorsa, se necessario.

Continuare ad aggiungere i nomi di risorsa come parametri quando il tipo di risorsa include più segmenti.

Valore restituito

L'identificatore viene restituito nel formato seguente:

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

Osservazioni:

Usare questa funzione per ottenere l'ID della risorsa per le risorse distribuite al gruppo di gestione anziché in un gruppo di risorse. L'ID restituito è diverso dal valore restituito dalla funzione resourceId dal momento che non include l’ID della sottoscrizione e un valore di un gruppo di risorse.

Esempio di managementGroupResourceID

Il modello seguente crea e assegna una definizione di criteri. Usa la funzione managementGroupResourceId per ottenere l'ID risorsa per la definizione dei criteri.

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

Restituisce l'identificatore univoco per una risorsa distribuita a livello di tenant.

In Bicep usare la funzione tenantResourceId .

Parametri

Parametro	Richiesto	Type	Descrizione
resourceType	Sì	string	Tipo di risorsa, incluso lo spazio dei nomi del provider di risorse.
resourceName1	Sì	string	Nome della risorsa.
resourceName2	No	string	Segmento successivo del nome della risorsa, se necessario.

Continuare ad aggiungere i nomi di risorsa come parametri quando il tipo di risorsa include più segmenti.

Valore restituito

L'identificatore viene restituito nel formato seguente:

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

Osservazioni:

Usare questa funzione per ottenere l'ID della risorsa di una risorsa distribuita nel tenant. L'ID restituito è diverso dai valori restituiti da altre funzioni dell'ID della risorsa in quanto non include i valori del gruppo di risorse o della sottoscrizione.

Esempio di tenantResourceId

Le definizioni di criteri predefinite sono risorse a livello di tenant. Per distribuire un'assegnazione di criteri che fa riferimento a una definizione di criteri predefinita, usare la funzione tenantResourceId.

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

Passaggi successivi

Per una descrizione delle sezioni in un modello di ARM, vedi Comprendere la struttura e la sintassi dei modelli di ARM.
Per unire più modelli, vedi Uso di modelli collegati e annidati nella distribuzione di risorse di Azure.
Per eseguire l'iterazione un numero specificato di volte durante la creazione di un tipo di risorsa, vedi Iterazione delle risorse nei modelli di ARM.
Per informazioni su come distribuire il modello creato, vedi Distribuire le risorse con i modelli di ARM e Azure PowerShell.

Funzioni delle risorse per i modelli di Azure Resource Manager

extensionResourceId

Parametri

Valore restituito

Esempio di funzione extensionResourceId

list*

Parametri

Usi validi

Implementazioni

Valore restituito

Osservazioni:

Esempio di funzione list

pickZones

Parametri

Valore restituito

Osservazioni:

Esempio di pickZones

provider

reference

Parametri

Valore restituito

Osservazioni:

Usi validi

Dipendenza implicita

Nome risorsa, nome simbolico o identificatore

Ottenere l'identità gestita

Esempio della funzione reference

references

Parametri

Valore restituito

Usi validi

Dipendenza implicita

Esempio della funzione reference

resourceGroup

resourceId

Parametri

Valore restituito

Osservazioni:

Esempio di ID della risorsa

sottoscrizione

subscriptionResourceId

Parametri

Valore restituito

Osservazioni:

Esempio di subscriptionResourceID

managementGroupResourceId

Parametri

Valore restituito

Osservazioni:

Esempio di managementGroupResourceID

tenantResourceId

Parametri

Valore restituito

Osservazioni:

Esempio di tenantResourceId

Passaggi successivi

Risorse aggiuntive