Partager via


Fonctions de ressources pour Bicep

Cet article décrit les fonctions Bicep pour l’obtention des valeurs de ressource.

Pour obtenir les valeurs du déploiement actuel, consultez Fonctions de valeur de déploiement.

extensionResourceId

extensionResourceId(resourceId, 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.

Espace de noms : az.

La fonction extensionResourceId est disponible dans les fichiers Bicep, mais vous n’en avez généralement pas besoin. Utilisez plutôt le nom symbolique de la ressource et accédez à la propriété id.

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.

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 est le suivant :

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

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

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

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

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

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 attribuer une stratégie, déployez le fichier Bicep suivant dans un groupe d’administration.

targetScope = 'managementGroup'

@description('An array of the allowed locations, all other locations will be denied by the created policy.')
param allowedLocations array = [
  'australiaeast'
  'australiasoutheast'
  'australiacentral'
]

resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2023-04-01' = {
  name: 'locationRestriction'
  properties: {
    policyType: 'Custom'
    mode: 'All'
    parameters: {}
    policyRule: {
      if: {
        not: {
          field: 'location'
          in: allowedLocations
        }
      }
      then: {
        effect: 'deny'
      }
    }
  }
}

resource policyAssignment 'Microsoft.Authorization/policyAssignments@2024-04-01' = {
  name: 'locationAssignment'
  properties: {
    policyDefinitionId: policyDefinition.id
  }
}

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.

getSecret

keyVaultName.getSecret(secretName)

Renvoie un secret à partir d’un Azure Key Vault. Utilisez cette fonction pour transmettre un secret à un paramètre de chaîne sécurisée d’un module Bicep.

Remarque

La fonction az.getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion) peut être utilisée dans les fichiers .bicepparam pour récupérer les secrets du coffre-fort de clés. Pour plus d’informations, consultez getSecret.

Vous ne pouvez utiliser la fonction getSecret qu’à partir de la section params d’un module. Vous ne pouvez l’utiliser qu’avec une ressource Microsoft.KeyVault/vaults.

module sql './sql.bicep' = {
  name: 'deploySQL'
  params: {
    adminPassword: keyVault.getSecret('vmAdminPassword')
  }
}

Vous obtenez une erreur si vous essayez d'utiliser cette fonction dans une autre partie du fichier Bicep. Vous obtenez également une erreur si vous utilisez cette fonction avec une interpolation de chaîne, même lorsqu'elle est utilisée dans la section params.

La fonction ne peut être utilisée qu’avec un paramètre de module qui a l’élément décoratif @secure().

Le enabledForTemplateDeployment du coffre de clés doit être défini sur true. L’utilisateur qui déploie le fichier Bicep doit avoir accès au secret. Pour plus d’informations, consultez Utiliser Azure Key Vault pour transmettre une valeur de paramètre sécurisée pendant le déploiement Bicep.

Un qualificateur d’espace de noms n’est pas nécessaire, car la fonction est utilisée avec un type de ressource.

Paramètres

Paramètre Obligatoire Type Description
secretName Oui string Nom du secret stocké dans un coffre de clés.

Valeur retournée

Valeur du secret pour le nom du secret.

Exemple

Le fichier Bicep suivant est utilisé en tant que module. Il est doté d’un paramètre adminPassword défini avec l’élément décoratif @secure().

param sqlServerName string
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = {
  ...
}

Le fichier Bicep suivant utilise le fichier Bicep précédent en tant que module. Le fichier Bicep référence un coffre de clés existant, appelle la fonction getSecret pour récupérer le secret du coffre de clés, puis passe la valeur en tant que paramètre au module.

param sqlServerName string
param adminLogin string

param subscriptionId string
param kvResourceGroup string
param kvName string

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: kvName
  scope: resourceGroup(subscriptionId, kvResourceGroup )
}

module sql './sql.bicep' = {
  name: 'deploySQL'
  params: {
    sqlServerName: sqlServerName
    adminLogin: adminLogin
    adminPassword: keyVault.getSecret('vmAdminPassword')
  }
}

list*

resourceName.list([apiVersion], [functionValues])

Vous pouvez appeler une fonction de liste pour n’importe quel type de ressource avec une opération qui commence par list. Voici quelques utilisations courantes : list, listKeys, listKeyValue et listSecrets.

La syntaxe de cette fonction varie en fonction du nom des opérations de liste. Les valeurs retournées varient également selon l’opération. Bicep ne prend pas actuellement en charge la saisie semi-automatique et la validation des fonctions list*.

Avec Bicep CLI version 0.4X ou ultérieure, vous appelez la fonction de liste avec l’opérateur accesseur. Par exemple : storageAccount.listKeys().

Un qualificateur d’espace de noms n’est pas nécessaire, car la fonction est utilisée avec un type de ressource.

Paramètres

Paramètre Obligatoire Type Description
apiVersion Non string Si vous ne fournissez pas ce paramètre, la version de l’API de la ressource est utilisée. Fournissez une version d’API personnalisée uniquement lorsque vous avez besoin que la fonction soit exécutée avec une version spécifique. Utilisez le 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 list peuvent être utilisés dans les propriétés d’une définition de ressource. N’utilisez pas de fonction list qui expose des informations sensibles dans la section de sortie d’un fichier Bicep. Les valeurs de sortie sont stockées dans l’historique de déploiement et peuvent être récupérées par un utilisateur malveillant.

Lorsqu’elles sont utilisées avec une boucle itérative, 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.

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 l’opérateur d’expression conditionnelle ?: pour vous assurer que la fonction est uniquement évaluée lorsque la ressource est déployée.

Valeur retournée

L’objet retourné varie selon la fonction de liste 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 fichier Bicep.

Exemple de liste

L’exemple suivant déploie un compte de stockage, puis appelle listKeys sur ce compte de stockage. La clé est utilisée pour définir une valeur pour les scripts de déploiement.

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'dscript${uniqueString(resourceGroup().id)}'
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource dScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'scriptWithStorage'
  location: location
  ...
  properties: {
    azCliVersion: '2.0.80'
    storageAccountSettings: {
      storageAccountName: storageAccount.name
      storageAccountKey: storageAccount.listKeys().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.

param accountSasProperties object {
  default: {
    signedServices: 'b'
    signedPermission: 'r'
    signedExpiry: '2020-08-20T11:00:00Z'
    signedResourceTypes: 's'
  }
}
...
sasToken: storageAccount.listAccountSas('2021-04-01', accountSasProperties).accountSasToken

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 listDomainRecommendations
Microsoft.DomainRegistration/topLevelDomains listAgreements
Microsoft.EventGrid/domains listKeys
Microsoft.EventGrid/topics listKeys
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.MachineLearningServices/workspaces/computes listKeys
Microsoft.MachineLearningServices/workspaces/computes listNodes
Microsoft.MachineLearningServices/workspaces listKeys
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/disasterRecoveryConfigs/authorizationRules listkeys
Microsoft.Search/searchServices listAdminKeys
Microsoft.Search/searchServices listQueryKeys
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-​AzProvider​Operation. 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')]"
    

managementGroupResourceId

managementGroupResourceId(resourceType, resourceName1, [resourceName2], ...)

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

Espace de noms : az.

La fonction managementGroupResourceId est disponible dans les fichiers Bicep, mais vous n’en avez généralement pas besoin. Utilisez plutôt le nom symbolique de la ressource et accédez à la propriété id.

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.

targetScope = 'managementGroup'

@description('Target Management Group')
param targetMG string

@description('An array of the allowed locations, all other locations will be denied by the created policy.')
param allowedLocations array = [
  'australiaeast'
  'australiasoutheast'
  'australiacentral'
]

var mgScope = tenantResourceId('Microsoft.Management/managementGroups', targetMG)
var policyDefinitionName = 'LocationRestriction'

resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2023-04-01' = {
  name: policyDefinitionName
  properties: {
    policyType: 'Custom'
    mode: 'All'
    parameters: {}
    policyRule: {
      if: {
        not: {
          field: 'location'
          in: allowedLocations
        }
      }
      then: {
        effect: 'deny'
      }
    }
  }
}

resource location_lock 'Microsoft.Authorization/policyAssignments@2024-04-01' = {
  name: 'location-lock'
  properties: {
    scope: mgScope
    policyDefinitionId: managementGroupResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionName)
  }
  dependsOn: [
    policyDefinition
  ]
}

pickZones

pickZones(providerNamespace, resourceType, location, [numberOfZones], [offset])

Détermine si un type de ressource prend en charge les zones pour une région. Cette fonction prend uniquement en charge les ressources zonales. Les services de redondance interzone retournent un tableau vide. Pour plus d’informations, consultez Services Azure prenant en charge les Zones de disponibilité.

Espace de noms : az.

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

[
]

Notes

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 Services Azure prenant 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 fichier Bicep suivant présente trois résultats pour l’utilisation de la fonction pickZones.

output supported array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')
output notSupportedRegion array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus')
output notSupportedType array = 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.

fournisseurs

La fonction de fournisseurs est déconseillée dans Bicep. 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 fichier Bicep. 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.

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

Espace de noms : az.

reference

reference(resourceName 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.

Espace de noms : az.

Les fichiers Bicep permettent d’accéder à la fonction de référence, bien qu’elle soit généralement inutile. Au lieu de cela, nous recommandons d’utiliser le nom symbolique de la ressource. Vous pouvez utiliser la fonction de référence uniquement dans l’objet properties d’une ressource et vous ne pouvez pas l’utiliser pour des propriétés de niveau supérieur telles que name ou location. Il en va de même pour les références utilisant le nom symbolique. Toutefois, pour des propriétés telles que name, vous avez la possibilité générer un modèle sans utiliser la fonction de référence. Suffisamment d’informations sur le nom de la ressource sont connues pour émettre directement le nom. C’est ce qu’on appelle les propriétés au moment de la compilation. La validation Bicep peut identifier toute utilisation incorrecte du nom symbolique.

L’exemple suivant déploie un compte de stockage. Les deux premières sorties vous offrent les mêmes résultats.

param storageAccountName string = uniqueString(resourceGroup().id)
param location string = resourceGroup().location

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountName
  location: location
  kind: 'Storage'
  sku: {
    name: 'Standard_LRS'
  }
}

output storageObjectSymbolic object = storageAccount.properties
output storageObjectReference object = reference('storageAccount')
output storageName string = storageAccount.name
output storageLocation string = storageAccount.location

Pour obtenir une propriété de ressource existante non déployée dans le modèle, utilisez le mot clé existing :

param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' existing = {
  name: storageAccountName
}

// use later in template as often as needed
output blobAddress string = storageAccount.properties.primaryEndpoints.blob

Pour référencer une ressource imbriquée dans une ressource parente, utilisez l’accesseur imbriqué (::). Vous n’utilisez cette syntaxe que lorsque vous accédez à la ressource imbriquée en dehors de la ressource parente.

vNet1::subnet1.properties.addressPrefix

Si vous tentez de référencer une ressource qui n’existe pas, vous recevez l’erreur NotFound et votre déploiement échoue.

resourceId

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

Retourne l'identificateur unique d'une ressource.

Espace de noms : az.

La fonction resourceId est disponible dans les fichiers Bicep, mais vous n’en avez généralement pas besoin. Utilisez plutôt le nom symbolique de la ressource et accédez à la propriété id.

Vous utilisez cette fonction lorsque le nom de la ressource est ambigu ou n’est pas approvisionné dans le même fichier Bicep. 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.

Par exemple :

param storageAccountName string
param location string = resourceGroup().location

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountName
  location: location
  kind: 'Storage'
  sku: {
    name: 'Standard_LRS'
  }
}

output storageID string = storageAccount.id

Pour obtenir l’ID d’une ressource non déployée dans le fichier Bicep, utilisez le mot clé existant.

param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' existing = {
  name: storageAccountName
}

output storageID string = storageAccount.id

Pour obtenir plus d'informations, consultez la fonction resourceId du modèle JSON.

subscriptionResourceId

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

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

Espace de noms : az.

La fonction subscriptionResourceId est disponible dans les fichiers Bicep, mais vous n’en avez généralement pas besoin. Utilisez plutôt le nom symbolique de la ressource et accédez à la propriété id.

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

@description('Principal Id')
param principalId string

@allowed([
  'Owner'
  'Contributor'
  'Reader'
])
@description('Built-in role to assign')
param builtInRoleType string

var roleDefinitionId = {
  Owner: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')
  }
  Contributor: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
  }
  Reader: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')
  }
}

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(resourceGroup().id, principalId, roleDefinitionId[builtInRoleType].id)
  properties: {
    roleDefinitionId: roleDefinitionId[builtInRoleType].id
    principalId: principalId
  }
}

tenantResourceId

tenantResourceId(resourceType, resourceName1, [resourceName2], ...)

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

Espace de noms : az.

La fonction tenantResourceId est disponible dans les fichiers Bicep, mais vous n’en avez généralement pas besoin. Utilisez plutôt le nom symbolique de la ressource et accédez à la propriété id.

L'identificateur est retourné au format suivant :

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

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.

@description('Specifies the ID of the policy definition or policy set definition being assigned.')
param policyDefinitionID string = '0a914e76-4921-4c19-b460-a2d36003525a'

@description('Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides.')
param policyAssignmentName string = guid(policyDefinitionID, resourceGroup().name)

resource policyAssignment 'Microsoft.Authorization/policyAssignments@2024-04-01' = {
  name: policyAssignmentName
  properties: {
    scope: subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)
    policyDefinitionId: tenantResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionID)
  }
}

Étapes suivantes