Funzioni delle risorse per i modelli di Azure Resource Manager

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

• extensionResourceId
• lista*
• pickZones
• provider (deprecato)
• riferimento
• referenze
• resourceId
• subscriptionResourceId
• managementGroupResourceId
• tenantResourceId

Per ottenere valori da parametri, variabili o dalla distribuzione corrente, vedere Funzioni dei valori di distribuzione.

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

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 extensionResourceId funzione .

Parametri

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 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.

lista*

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 potrebbe avere un suffisso. Tra gli usi comuni vi sono list, listKeys, listKeyValue e listSecrets.

In Bicep usare la list* funzione .

Parametri

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.

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 -AzProvider​Cmdlet 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 o la resourceId funzione. 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 list funzione 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. Vedere la if funzione 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 zone di disponibilità.

In Bicep usare la pickZones funzione .

Parametri

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.

È 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 ridondanza della zona per la pickZones replica geografica. Passare il tipo di risorsa Microsoft.Storage/storageAccounts per determinare se abilitare la ridondanza della zona:

"resources": [
  {
    "type": "Microsoft.DocumentDB/databaseAccounts",
    "apiVersion": "2025-05-01-preview",
    "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 providers funzione è 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 providers funzione è deprecata.

L'operazione [providers ](/rest/api/resources/providers) è 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.

riferimento

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 reference funzione, ma nella maggior parte dei casi la funzione non è necessaria. Usare invece il nome simbolico per la risorsa. Per altre informazioni, vedere reference.

Parametri

Valore restituito

Ogni tipo di risorsa restituisce proprietà diverse per la reference funzione. 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 reference funzione 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": "2025-05-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, typead esempio , name, locationo 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 reference funzione nella sezione outputs di un modello annidato, è necessario impostare per usare la list* 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. Vedere la if funzione 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]"

O

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

Quando si fa riferimento a una risorsa non distribuita nello stesso modello, specificare l'ID 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

L'esempio seguente distribuisce una risorsa e vi fa riferimento:

{
  "$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": "2025-06-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à all'interno della 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')]"
    }
  }
}

referenze

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

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à quelle distribuite, ordinate 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 references funzione nella sezione outputs di un modello annidato, è necessario impostare per usare la list* 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

L'esempio seguente distribuisce una raccolta di risorse e fa 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": "2025-09-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": "2025-09-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"
      },
      ...
    ]
  }
}

gruppo di risorse

Vedere la resourceGroup scope funzione .

In Bicep usare la resourceGroup scope funzione .

ID della risorsa

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 si verifichi nell'ambito di un gruppo di risorse, una sottoscrizione, un gruppo di gestione o un tenant.

In Bicep usare la resourceId funzione .

Parametri

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, non usare resourceId quando si usano risorse distribuite nella sottoscrizione, nel gruppo di gestione o nel tenant. Usare invece la ...Id funzione progettata per l'ambito.

• Per le risorse a livello di sottoscrizione, usare la subscriptionResourceId funzione .
• Per le risorse a livello di gruppo di gestione, usare la managementGroupResourceId funzione . Usare la extensionResourceId funzione 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 tenantResourceId funzione 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 tenantResourceId funzione . Usare tenantResourceId per le definizioni di criteri predefinite perché vengono implementate a livello di tenant.

Osservazioni:

Il numero di parametri forniti varia in base a se la risorsa è una risorsa padre o figlio e se la risorsa si trova 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 illustra come usare una risorsa da 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": "2025-01-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 dei valori predefiniti dell'esempio precedente è:

sottoscrizione

Per altre informazioni, vedere la subscription funzione di ambito .

In Bicep usare la subscription funzione di ambito .

subscriptionResourceId

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

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

In Bicep usare la subscriptionResourceId funzione .

Parametri

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 resourceId funzione perché non restituisce un valore del 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 subscriptionResourceId funzione 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 managementGroupResourceId funzione .

Parametri

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 resourceId funzione perché non include un ID sottoscrizione o un valore del 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": "2025-03-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": "2025-03-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 tenantResourceId funzione .

Parametri

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:

Questa funzione viene usata per ottenere l'ID risorsa per 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 tenantResourceId funzione :

{
  "$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": "2025-03-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.