Fonctions de ressource pour les modèles ARM

Article
03/18/2024

Resource Manager fournit les fonctions suivantes pour obtenir des valeurs de ressource dans votre modèle Azure Resource Manager (modèle ARM) :

extensionResourceId
list*
pickZones
providers (déconseillé)
reference
références
resourceId
subscriptionResourceId
managementGroupResourceId
tenantResourceId

Pour obtenir des valeurs de paramètres, de variables ou du déploiement actuel, consultez Fonctions de valeur de déploiement.

Pour obtenir les valeurs d’étendue de déploiement, consultez Fonctions d’étendue.

Conseil

Nous recommandons Bicep, parce qu’il offre les mêmes fonctionnalités que les modèles ARM et que la syntaxe est plus facile d’utilisation. Pour plus d’informations, consultez les fonctions de ressources.

extensionResourceId

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

Renvoie l’ID de ressource d’une ressource d’extension. Une ressource d’extension est un type de ressource qui s’applique à une autre ressource pour y ajouter ses fonctionnalités.

Dans Bicep, utilisez la fonction extensionResourceId.

Paramètres

Paramètre	Obligatoire	Type	Description
baseResourceId	Oui	string	ID de la ressource à laquelle s’applique la ressource d’extension.
resourceType	Oui	string	Type de ressource d’extension, y compris l'espace de noms du fournisseur de ressources.
nom_ressource1	Oui	string	Nom de la ressource d’extension.
nom_ressource2	Non	string	Segment de nom de ressource suivant si nécessaire.

Continuez à ajouter des noms de ressource en paramètres lorsque le type de ressource contient plus de segments.

Valeur retournée

Le format de base de l’ID de ressource retourné par cette fonction est le suivant :

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

Le segment d’étendue varie en fonction de la ressource étendue. Par exemple, l’ID d’un abonnement a des segments différents de l’ID d’un groupe de ressources.

Lorsque la ressource d’extension est appliquée à une ressource, l’ID de la ressource est retourné au format suivant :

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

Lorsque la ressource d’extension est appliquée à un groupe de ressources, le format retourné est le suivant :

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

Un exemple d’utilisation de cette fonction avec un groupe de ressources est présenté dans la section suivante.

Lorsque la ressource d’extension est appliquée à un abonnement, le format retourné est le suivant :

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

Lorsque la ressource d’extension est appliquée à un groupe d’administration, le format retourné est le suivant :

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

Un exemple d’utilisation de cette fonction avec un groupe d'administration est présenté dans la section suivante.

Exemple extensionResourceId

L’exemple suivant retourne l’ID de la ressource pour un verrou de groupe de ressources.

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

Une définition de stratégie personnalisée déployée sur un groupe d’administration est implémentée en tant que ressource d’extension. Pour créer et affecter une stratégie, déployez le modèle suivant dans un groupe d’administration.

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

Les définitions de stratégie intégrées sont des ressources de niveau locataire. Pour obtenir un exemple de déploiement d’une définition de stratégie intégrée, consultez tenantResourceId.

list*

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

La syntaxe de cette fonction varie en fonction du nom des opérations de liste. Chaque implémentation retourne des valeurs pour le type de ressource qui prend en charge une opération de liste. Le nom de l’opération doit commencer par list et peut avoir un suffixe. Voici quelques utilisations courantes : list, listKeys, listKeyValue et listSecrets.

Dans Bicep, utilisez la fonction list*.

Paramètres

Paramètre	Obligatoire	Type	Description
nom_ressource ou identificateur_ressource	Oui	string	Identificateur unique pour la ressource.
apiVersion	Oui	string	Version d'API de l'état d'exécution des ressources. En règle générale, au format, aaaa-mm-jj.
functionValues	Non	object	Objet qui contient les valeurs de la fonction. Fournissez uniquement cet objet pour les fonctions qui prennent en charge la réception d’un objet avec des valeurs de paramètre, comme `listAccountSas` sur un compte de stockage. Un exemple de transmission de valeurs de fonction est illustré dans cet article.

Utilisations valides

Les fonctions de liste peuvent être utilisés dans les propriétés d’une définition de ressource. N’utilisez pas de fonction de liste qui expose des informations sensibles dans la section de sortie d’un modèle. Les valeurs de sortie sont stockées dans l’historique de déploiement et peuvent être récupérées par un utilisateur malveillant.

Quand elles sont utilisées avec une itération de propriété, vous pouvez utiliser les fonctions list pour input, car l’expression est affectée à la propriété de ressource. Vous ne pouvez pas les utiliser avec count, car le nombre doit être déterminé avant que la fonction list ne soit résolue.

Implémentations

Les utilisations possibles de list* sont indiquées dans le tableau suivant.

Type de ressource	Nom de la fonction
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

Pour déterminer les types de ressources qui ont une opération de liste, utilisez les options suivantes :

Affichez les opérations d’API REST pour un fournisseur de ressources et recherchez les opérations de liste. Par exemple, les comptes de stockage présentent l’opération listKeys.
Utilisez la cmdlet PowerShell Get-AzProviderOperation. L’exemple ci-dessous obtient toutes les opérations de liste pour les comptes de stockage :
```
Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
```

Utilisez la commande Azure CLI suivante pour filtrer uniquement les opérations de liste :

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

Valeur retournée

L’objet retourné varie selon la fonction list que vous utilisez. Par exemple, la fonction listKeys pour un compte de stockage retourne le format suivant :

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

D’autres fonctions list ont différents formats de retour. Pour afficher le format d’une fonction, incluez-le dans la section des sorties comme indiqué dans l’exemple de modèle.

Notes

Spécifiez la ressource en utilisant le nom de la ressource ou la fonction resourceId. Lorsque vous utilisez une fonction list dans le modèle qui déploie la ressource référencée, utilisez le nom de la ressource.

Si vous utilisez une fonction list dans une ressource qui est déployée conditionnellement, la fonction est évaluée, même si la ressource n’est pas déployée. Vous obtenez une erreur si la fonction list fait référence à une ressource qui n’existe pas. Utilisez la fonction if pour vous assurer que la fonction est évaluée lors du déploiement de la ressource. Consultez la fonction if pour obtenir un exemple de modèle qui utilise if et list avec une ressource déployée de manière conditionnelle.

Exemple de liste

L’exemple suivant utilise listKeys lors de la définition d’une valeur pour les scripts de déploiement.

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

L’exemple suivant montre une fonction list qui accepte un paramètre. Dans ce cas, la fonction est listAccountSas. Passez un objet pour l’heure d’expiration. L’heure d’expiration doit être dans le futur.

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

Détermine si un type de ressource prend en charge les zones pour l’emplacement ou la région spécifié(e). Cette fonction prend uniquement en charge les ressources zonales. Les services de redondance interzone retournent un tableau vide. Pour plus d’informations, consultez l’article sur les services Azure prenant en charge les zones de disponibilité.

Dans Bicep, utilisez la fonction pickZones.

Paramètres

Paramètre	Obligatoire	Type	Description
espacedenoms_fournisseur	Oui	string	Espace de noms du fournisseur du type de ressource pour lequel la prise en charge des zones doit être vérifiée.
resourceType	Oui	string	Type de ressource pour lequel la prise en charge des zones doit être vérifiée.
location	Oui	string	Région pour laquelle la prise en charge des zones doit être vérifiée.
numberOfZones	Non	entier	Nombre de zones logiques à retourner. La valeur par défaut est 1. Le nombre doit être un entier positif compris entre 1 et 3. Utilisez 1 pour les ressources à une seule zone. Pour les ressources multizones, la valeur doit être inférieure ou égale au nombre de zones prises en charge.
offset	Non	entier	Décalage par rapport à la zone logique de départ. La fonction retourne une erreur si le décalage plus le nombre de zones (numberOfZones) dépasse le nombre de zones prises en charge.

Valeur retournée

Tableau avec les zones prises en charge. Quand les valeurs par défaut pour offset et numberOfZones sont utilisées, un type de ressource et une région qui prend en charge les zones retournent le tableau suivant :

[
    "1"
]

Quand le paramètre numberOfZones est défini sur 3, il retourne :

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

Quand le type de ressource ou la région ne prend pas en charge les zones, un tableau vide est retourné. Un tableau vide est également retourné pour les services redondants dans une zone.

[
]

Remarques

Il existe différentes catégories pour les Zones de disponibilité Azure : zonal et redondant interzone. La fonction pickZones peut être utilisée pour retourner une zone de disponibilité pour une ressource zonale. Pour les services redondants interzone (ZRS), la fonction retourne un tableau vide. Les ressources zonales ont généralement une propriété zones au niveau supérieur de la définition de ressource. Pour déterminer la catégorie de prise en charge des zones de disponibilité, consultez les services Azure qui prennent en charge les zones de disponibilité.

Pour déterminer si une région ou un emplacement Azure donné prend en charge les zones de disponibilité, appelez la fonction pickZones avec un type de ressource zonale tel que Microsoft.Network/publicIPAddresses. Si la réponse n’est pas vide, la région prend en charge les zones de disponibilité.

Exemple de pickZones

Le modèle suivant présente trois résultats pour l’utilisation de la fonction pickZones.

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

La sortie des exemples précédents retourne trois tableaux.

Nom	Type	Valeur
supported	tableau	[ "1" ]
notSupportedRegion	tableau	[]
notSupportedType	tableau	[]

Vous pouvez vous servir de la réponse de pickZones pour déterminer s’il convient de fournir une valeur null pour des zones ou affecter des machines virtuelles à différentes zones. L’exemple suivant définit une valeur pour la zone en fonction de la disponibilité des zones.

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

Azure Cosmos DB n’est pas une ressource zonale, mais vous pouvez utiliser la fonction pickZones pour déterminer s’il faut activer la redondance de zone pour la géoréplication. Avec le type de ressource Microsoft.Storage/storageAccounts déterminez s’il faut activer la redondance de zone.

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

fournisseurs

La fonction de fournisseurs est déconseillée dans les modèles ARM. Nous ne recommandons plus son utilisation. Si vous avez utilisé cette fonction pour obtenir une version d’API pour le fournisseur de ressources, nous vous recommandons de fournir une version d’API spécifique dans votre modèle. L’utilisation d’une version d’API retournée dynamiquement peut rompre votre modèle si les propriétés changent d’une version à l’autre.

Dans Bicep, la fonction providers est déconseillée.

L’opération de fournisseurs est toujours disponible via l’API REST. Cette fonction peut être utilisée en dehors d’un modèle ARM pour obtenir des informations sur un fournisseur de ressources.

reference

Dans les modèles sans noms symboliques :

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

Dans les modèles avec noms symboliques :

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

Renvoie un objet représentant l’état d’exécution d’une ressource. La sortie et le comportement de la fonction reference reposent fortement sur la façon dont chaque fournisseur de ressources (Ressource Provider/RP) implémente ses réponses PUT et GET. Pour renvoyer un tableau d'objets représentant les états d'exécution d'une collection de ressources, consultez les références.

Bicep fournit la fonction de référence, mais dans la plupart des cas, la fonction de référence n’est pas requise. Il est recommandé d’utiliser le nom symbolique de la ressource à la place. Consultez la référence.

Paramètres

Paramètre	Obligatoire	Type	Description
resourceName/resourceIdentifier ou symbolName/resourceIdentifier	Oui	string	Dans les modèles sans noms symboliques, spécifiez le nom ou l’identificateur unique d’une ressource. Lorsque vous référencez une ressource dans le modèle actuel, indiquez uniquement le nom de la ressource en tant que paramètre. Lorsque vous référencez une ressource précédemment déployée, ou lorsque le nom de la ressource est ambigu, fournissez l’ID de la ressource. Dans les modèles avec des noms symboliques, spécifiez le nom symbolique ou l’identificateur unique d’une ressource. Lorsque vous référencez une ressource dans le modèle actuel, indiquez uniquement le nom de la ressource symbolique en tant que paramètre. Lorsque vous référencez une ressource déployée précédemment, fournissez l’ID de ressource.
apiVersion	Non	string	Version d’API de la ressource spécifiée. Ce paramètre est obligatoire lorsque la ressource n’est pas approvisionnée dans le même modèle. En règle générale, au format, aaaa-mm-jj. Pour obtenir les versions d’API valides pour votre ressource, consultez Référence de modèle.
'Full'	Non	string	Valeur qui spécifie si l’objet de ressource complet doit être retourné. Si vous ne spécifiez pas `'Full'`, seul l’objet properties de la ressource est retourné. L’objet complet comprend des valeurs telles que l’ID de ressource et l’emplacement.

Valeur retournée

Chaque type de ressource retourne des propriétés différentes pour la fonction de référence. La fonction ne retourne pas un format prédéfini unique. En outre, la valeur retournée diffère selon la valeur de l’argument 'Full'. Pour afficher les propriétés d’un type de ressource, renvoyez l’objet dans la section des sorties comme indiqué dans l’exemple.

Notes

La fonction de référence récupère l’état d’exécution d’une ressource déployée précédemment ou déployée dans le modèle actuel. Cet article montre des exemples pour les deux scénarios.

En règle générale, vous utilisez la fonction de reference pour renvoyer une valeur particulière d’un objet, telle que l’URI du point de terminaison d’objet blob ou le nom de domaine complet.

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

Utilisez 'Full' quand vous avez besoin de valeurs de ressource qui ne font pas partie du schéma de propriétés. Par exemple, pour définir des stratégies d’accès à des coffres de clés, obtenez les propriétés d’identité d’une machine virtuelle.

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

Utilisations valides

La fonction reference ne peut être utilisée que dans la section des sorties d'un modèle ou d'un déploiement et dans l'objet des propriétés d'une définition de ressource. Elle ne peut pas être utilisée pour les propriétés de ressource telles que type, name, location et d’autres propriétés de niveau supérieur de la définition de ressource. Lorsqu’elle est utilisée avec une itération de propriété, vous pouvez utiliser la fonction reference pour input, car l’expression est affectée à la propriété de ressource.

Vous ne pouvez pas utiliser la fonction reference pour définir la valeur de la propriété count dans une boucle de copie. Vous pouvez l'utiliser pour définir d’autres propriétés de la boucle. La référence est bloquée pour la propriété de nombre car cette propriété doit être déterminée préalablement à la résolution de la fonction reference.

Pour utiliser la fonction reference ou n'importe quelle fonction list* dans la section outputs d'un modèle imbriqué, vous devez définir les expressionEvaluationOptions de manière à utiliser l'évaluation avec portée interne ou utiliser un modèle lié plutôt qu'un modèle imbriqué.

Si vous utilisez une fonction reference dans une ressource qui est déployée conditionnellement, la fonction est évaluée même si la ressource n’est pas déployée. Vous obtenez une erreur si la fonction reference fait référence à une ressource qui n’existe pas. Utilisez la fonction if pour vous assurer que la fonction est évaluée lors du déploiement de la ressource. Consultez la fonction if pour obtenir un exemple de modèle qui utilise if et reference avec une ressource déployée de manière conditionnelle.

Dépendance implicite

En utilisant la fonction reference, vous déclarez de manière implicite qu’une ressource dépend d’une autre ressource si la ressource référencée est configurée dans le même modèle et vous désignez cette ressource par son nom (pas par son ID). Vous n’avez pas besoin d’utiliser également la propriété dependsOn. La fonction n’est pas évaluée tant que le déploiement de la ressource référencée n’est pas terminé.

Nom de la ressource, nom symbolique ou identificateur

Lorsqu'il est fait référence à une ressource déployée dans le même modèle de nom non symbolique, il convient d'indiquer le nom de la ressource.

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

Lorsqu'il est fait référence à une ressource déployée dans le même modèle de nom symbolique, il convient d'indiquer le nom de la ressource symbolique.

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

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

Lorsque vous faites référence à une ressource qui n’est pas déployée dans le même modèle, fournissez l’ID de ressource et apiVersion.

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

Pour éviter toute ambiguïté quant à la ressource à laquelle vous faites référence, vous pouvez fournir un identificateur de ressource complet.

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

Quand vous créez une référence complète à une ressource, l’ordre utilisé pour combiner les segments de type et de nom n’est pas une simple concaténation des deux. Au lieu de cela, utilisez après l’espace de noms une séquence de paires type/nom du moins spécifique au plus spécifique :

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

Par exemple :

Microsoft.Compute/virtualMachines/myVM/extensions/myExt est correct Microsoft.Compute/virtualMachines/extensions/myVM/myExt n’est pas correct

Pour simplifier la création d’un ID de ressource, utilisez les fonctions resourceId() décrites dans ce document au lieu de la fonction concat().

Obtenir une identité managée

Les identités managées pour ressources Azure sont des types de ressources d’extension créés implicitement pour certaines ressources. L’identité managée n’étant pas définie explicitement dans le modèle, vous devez référencer la ressource à laquelle elle est appliquée. Utilisez Full pour obtenir toutes les propriétés, y compris l’identité créée implicitement.

Le modèle est :

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

Par exemple, pour obtenir l'ID de principal d'une identité managée appliquée à une machine virtuelle, utilisez :

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

Ou, pour obtenir l'ID de locataire d'une identité managée appliquée à un groupe de machines virtuelles identiques, utilisez :

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

Exemple de référence

L’exemple de modèle suivant déploie une ressource, puis référence cette ressource.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountName": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "tags": {},
      "properties": {
      }
    }
  ],
  "outputs": {
    "referenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'))]"
    },
    "fullReferenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'), '2022-09-01', 'Full')]"
    }
  }
}

L’exemple précédent retourne les deux objets. L’objet de propriétés retourné présente le format suivant :

{
   "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’objet complet retourné présente le format suivant :

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

L’exemple de modèle suivant référence un compte de stockage qui n’est pas déployé dans ce modèle. Le compte de stockage existe déjà dans le même abonnement.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageResourceGroup": {
      "type": "string"
    },
    "storageAccountName": {
      "type": "string"
    }
  },
  "resources": [],
  "outputs": {
    "ExistingStorage": {
      "type": "object",
      "value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2021-04-01')]"
    }
  }
}

références

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

La fonction references fonctionne de la même façon que reference. Au lieu de renvoyer un objet présentant l'état d'exécution d'une ressource, la fonction references renvoie un tableau d'objets représentant les états d'exécution d'une collection de ressources. Cette fonction nécessite la version 2.0 du langage du modèle ARM et avec le nom symbolique activé :

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

Dans Bicep, il n’existe aucune fonction explicite references. Au lieu de cela, l’utilisation de la collection symbolique est employée directement et, lors de la génération de code, Bicep la traduit en modèle ARM qui utilise la fonction references de modèle ARM. Pour plus d'informations, voir Collections de ressources/modules de référence.

Paramètres

Paramètre	Obligatoire	Type	Description
Nom symbolique d’une collection de ressources	Oui	string	Nom symbolique d’une collection de ressources définie dans le modèle actuel. La fonction `references` ne prend pas en charge le référencement de ressources externes au modèle actuel.
'Complet', 'Propriétés'	Non	string	Valeur qui spécifie si un tableau de l’objet de ressource complet doit être retourné. La valeur par défaut est `'Properties'`. Si vous ne spécifiez pas `'Full'`, seul les objets propriétés de la ressource sont retournés. L’objet complet comprend des valeurs telles que l’ID de ressource et l’emplacement.

Valeur retournée

Tableau de la collection de ressources. Chaque type de ressource retourne des propriétés différentes pour la fonction reference. En outre, la valeur retournée diffère selon la valeur de l’argument 'Full'. Pour plus d’informations, consultez référence.

L’ordre de sortie de references est toujours organisé dans l’ordre croissant en fonction de l’index de copie. Par conséquent, la première ressource de la collection avec l’index 0 s’affiche en premier, suivie de l’index 1, et ainsi de suite. Par exemple, [worker-0, worker-1, worker-2, ...].

Dans l’exemple précédent, si worker-0 et worker-2 sont déployés alors que worker-1 n’est pas dû à une fausse condition, la sortie de references omet la ressource non déployée et affiche les ressources déployées, classées par leur nombre. La sortie de references sera [worker-0, worker-2, ...]. Si toutes les ressources sont omises, la fonction retourne un tableau vide.

Utilisations valides

La fonction references ne peut pas être utilisée dans les boucles de copie de ressources ou Bicep for loop. Par exemple, references n’est pas autorisé dans le scénario suivant :

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

Pour utiliser la fonction references ou n'importe quelle fonction list* dans la section outputs d'un modèle imbriqué, vous devez définir les expressionEvaluationOptions de manière à utiliser l'évaluation avec portée interne ou utiliser un modèle lié plutôt qu'un modèle imbriqué.

Dépendance implicite

En utilisant la fonction references, vous déclarez implicitement qu’une ressource dépend d’une autre. Vous n’avez pas besoin d’utiliser également la propriété dependsOn. La fonction n’est pas évaluée tant que le déploiement de la ressource référencée n’est pas terminé.

Exemple de référence

L’exemple de modèle suivant déploie une collection de ressources, puis référence cette collection de ressources.

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

L’exemple précédent retourne les trois objets.

"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

Consultez la fonction d’étendue resourceGroup.

Dans Bicep, utilisez la fonction d’étendue resourcegroup.

resourceId

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

Retourne l'identificateur unique d'une ressource. Vous utilisez cette fonction lorsque le nom de la ressource est ambigu ou non configuré dans le même modèle. Le format de l’identificateur retourné varie selon que le déploiement se produit à l’échelle d’un groupe de ressources, d’un abonnement, d’un groupe d’administration ou d’un locataire.

Dans Bicep, utilisez la fonction resourceid.

Paramètres

Paramètre	Obligatoire	Type	Description
subscriptionId	Non	string (au format GUID)	La valeur par défaut est l’abonnement actuel. Spécifiez cette valeur lorsque vous devez récupérer une ressource se trouvant dans un autre abonnement. Fournissez cette valeur uniquement lors du déploiement à l’échelle d’un groupe de ressources ou d’un abonnement.
resourceGroupName	Non	string	La valeur par défaut est le groupe de ressources actuel. Spécifiez cette valeur lorsque vous devez récupérer une ressource se trouvant dans un autre groupe de ressources. Fournissez cette valeur uniquement lors du déploiement à l’échelle d’un groupe de ressources.
resourceType	Oui	string	Type de ressource, y compris l'espace de noms du fournisseur de ressources.
nom_ressource1	Oui	string	Nom de la ressource.
nom_ressource2	Non	string	Segment de nom de ressource suivant si nécessaire.

Continuez à ajouter des noms de ressource en paramètres lorsque le type de ressource contient plus de segments.

Valeur retournée

L’ID de ressource est retourné dans différents formats à différentes étendues :

Étendue du groupe de ressources :

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

Étendue d’abonnement :

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

Groupe d’administration ou étendue du locataire :

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

Pour éviter toute confusion, nous vous recommandons de ne pas utiliser la fonction resourceIdlorsque vous travaillez avec des ressources déployées sur l’abonnement, le groupe d’administration ou le locataire. Utilisez plutôt la fonction ID conçue pour l’étendue.

Pour les ressources au niveau de l’abonnement, utilisez la fonction subscriptionResourceId.
Pour les ressources au niveau du groupe d’administration, utilisez la fonction managementGroupResourceId. Utilisez la fonction extensionResourceId pour référencer une ressource qui est implémentée en tant qu’extension d’un groupe d’administration. Par exemple, des définitions de stratégie personnalisée déployées sur un groupe d’administration sont des extensions de celui-ci. Utilisez la fonction tenantResourceId pour référencer les ressources déployées sur le locataire, mais disponibles dans votre groupe d’administration. Par exemple, les définitions de stratégie intégrées sont implémentées en tant que ressources au niveau locataire.
Pour les ressources au niveau locataire, utilisez la fonction tenantResourceId. Utilisez tenantResourceId pour les définitions de stratégie intégrées, car elles sont implémentées au niveau locataire.

Notes

Le nombre de paramètres que vous fournissez varie selon qu’il s'agit d’une ressource parent ou d’une ressource enfant et selon que la ressource fait partie du même abonnement ou du même groupe de ressources.

Pour obtenir l’ID de ressource d’une ressource parent se trouvant dans le même abonnement et le même groupe de ressources, indiquez le type et le nom de la ressource.

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

Pour obtenir l’ID de ressource d’une ressource enfant, faites attention au nombre de segments dans le type de ressource. Indiquez un nom de ressource pour chaque segment du type de ressource. Le nom du segment correspond à la ressource qui existe pour cette partie de la hiérarchie.

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

Pour obtenir l’ID de ressource d’une ressource se trouvant dans le même abonnement mais dans un groupe de ressources différent, indiquez le nom du groupe de ressources.

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

Pour obtenir l’ID de ressource d’une ressource se trouvant dans un abonnement et un groupe de ressources différents, indiquez l’ID d’abonnement et le nom du groupe de ressources.

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

Souvent, vous devez utiliser cette fonction lorsque vous utilisez un compte de stockage ou un réseau virtuel se trouvant dans un autre groupe de ressources. L'exemple suivant montre comment une ressource d'un groupe de ressources externe peut être facilement utilisée :

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

Exemple d’ID de ressource

L’exemple suivant retourne l’ID de ressource pour un compte de stockage dans le groupe de ressources :

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

La sortie de l’exemple précédent avec les valeurs par défaut se présente comme suit :

Nom	Type	Valeur
sameRGOutput	String	/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutput	String	/subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentSubOutput	Chaîne	/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e4e4e4e/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutput	String	/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

subscription

Consultez la fonction d’étendue d’abonnement.

Dans Bicep, utilisez la fonction d’étendue subscription.

subscriptionResourceId

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

Retourne l’identificateur unique d’une ressource déployée au niveau de l’abonnement.

Dans Bicep, utilisez la fonction subscriptionResourceId.

Paramètres

Paramètre	Obligatoire	Type	Description
subscriptionId	Non	string (au format GUID)	La valeur par défaut est l’abonnement actuel. Spécifiez cette valeur lorsque vous devez récupérer une ressource se trouvant dans un autre abonnement.
resourceType	Oui	string	Type de ressource, y compris l'espace de noms du fournisseur de ressources.
nom_ressource1	Oui	string	Nom de la ressource.
nom_ressource2	Non	string	Segment de nom de ressource suivant si nécessaire.

Continuez à ajouter des noms de ressource en paramètres lorsque le type de ressource contient plus de segments.

Valeur retournée

L'identificateur est retourné au format suivant :

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

Notes

Utilisez cette fonction pour récupérer l’ID des ressources déployées dans l’abonnement plutôt qu’un groupe de ressources. L’ID retourné diffère de la valeur retournée par la fonction resourceId en ce qu’il n’inclut pas de valeur de groupe de ressources.

Exemple subscriptionResourceID

Le modèle suivant attribue un rôle intégré. Vous pouvez le déployer soit sur un groupe de ressources, soit sur un abonnement. Il utilise la fonction subscriptionResourceId pour récupérer l’ID de ressource pour les rôles intégrés.

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

Retourne l’identificateur unique d’une ressource déployée au niveau du groupe d’administration.

Dans Bicep, utilisez la fonction managementGroupResourceId.

Paramètres

Paramètre	Obligatoire	Type	Description
managementGroupResourceId	Non	string (au format GUID)	La valeur par défaut est le groupe d'administration actuel. Spécifiez cette valeur lorsque vous devez récupérer une ressource se trouvant dans un autre groupe d’administration.
resourceType	Oui	string	Type de ressource, y compris l'espace de noms du fournisseur de ressources.
nom_ressource1	Oui	string	Nom de la ressource.
nom_ressource2	Non	string	Segment de nom de ressource suivant si nécessaire.

Continuez à ajouter des noms de ressource en paramètres lorsque le type de ressource contient plus de segments.

Valeur retournée

L'identificateur est retourné au format suivant :

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

Notes

Utilisez cette fonction pour récupérer l’ID des ressources déployées dans l’abonnement plutôt qu’un groupe d’administration. L’ID retourné diffère de la valeur retournée par la fonction resourceId en cela qu’il n’inclut pas d’ID d’abonnement et de valeur de groupe de ressources.

managementGroupResourceId

Le modèle suivant crée et attribue une définition de stratégie. Il utilise la fonction managementGroupResourceId pour récupérer l’ID de ressource pour la définition de stratégie.

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

Retourne l’identificateur unique d’une ressource déployée au niveau du tenant.

Dans Bicep, utilisez la fonction tenantResourceId.

Paramètres

Paramètre	Obligatoire	Type	Description
resourceType	Oui	string	Type de ressource, y compris l'espace de noms du fournisseur de ressources.
nom_ressource1	Oui	string	Nom de la ressource.
nom_ressource2	Non	string	Segment de nom de ressource suivant si nécessaire.

Continuez à ajouter des noms de ressource en paramètres lorsque le type de ressource contient plus de segments.

Valeur retournée

L'identificateur est retourné au format suivant :

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

Notes

Cette fonction permet de récupérer l’ID d’une ressource déployée sur le tenant. L’ID retourné diffère des valeurs retournées par d’autres fonctions d’ID de ressource en ce qu’il n’inclut pas de valeurs de groupe de ressources ou d’abonnement.

Exemple tenantResourceId

Les définitions de stratégie intégrées sont des ressources de niveau locataire. Pour déployer une attribution de stratégie qui fait référence à une définition de stratégie intégrée, utilisez la fonction 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'))]"
      }
    }
  ]
}

Étapes suivantes

Pour obtenir une description des sections d’un modèle ARM, consultez Comprendre la structure et la syntaxe des modèles ARM.
Pour fusionner plusieurs modèles, consultez Utilisation de modèles liés et imbriqués lors du déploiement de ressources Azure.
Pour itérer un nombre spécifié lors de la création d’un type de ressource, consultez Itération de ressource dans les modèles ARM.
Pour découvrir comment déployer le modèle que vous avez créé, consultez Déployer des ressources avec des modèles ARM et Azure PowerShell.

Partager via

Fonctions de ressource pour les modèles ARM

extensionResourceId

Paramètres

Valeur retournée

Exemple extensionResourceId

list*

Paramètres

Utilisations valides

Implémentations

Valeur retournée

Notes

Exemple de liste

pickZones

Paramètres

Valeur retournée

Remarques

Exemple de pickZones

fournisseurs

reference

Paramètres

Valeur retournée

Notes

Utilisations valides

Dépendance implicite

Nom de la ressource, nom symbolique ou identificateur

Obtenir une identité managée

Exemple de référence

références

Paramètres

Valeur retournée

Utilisations valides

Dépendance implicite

Exemple de référence

resourceGroup

resourceId

Paramètres

Valeur retournée

Notes

Exemple d’ID de ressource

subscription

subscriptionResourceId

Paramètres

Valeur retournée

Notes

Exemple subscriptionResourceID

managementGroupResourceId

Paramètres

Valeur retournée

Notes

managementGroupResourceId

tenantResourceId

Paramètres

Valeur retournée

Notes

Exemple tenantResourceId

Étapes suivantes

Commentaires

Ressources supplémentaires