Resursfunktioner för Bicep

Den här artikeln beskriver Bicep funktioner för att hämta resursvärden.

Information om hur du hämtar värden från den aktuella distributionen finns i Funktioner för distributionsvärde.

Namnrymden `this`

Namnrymden this tillhandahåller funktioner för resurstillståndsupptäckt i realtid inom en resursdefinition. Dessa funktioner gör det möjligt för din mall att anpassa sin konfiguration baserat på om en resurs redan finns i miljön.

this.exists(): Returnerar ett bool-värde som anger om resursen för närvarande existerar.
this.existingResource(): Returnerar objektrepresentationen av resursen om den finns, eller null om den inte gör det.

finns

this.exists()

Returnerar ett bool-värde som indikerar om resursen för närvarande finns i Azure. Denna funktion utvärderas under utrullning och är avsedd att användas inom resursegenskapsassigneringar för att hantera villkorlig logik utan att behöva separata befintliga resursdeklarationer.

Namnrymd: detta

Exempel

resource stg 'Microsoft.Storage/storageAccounts@2026-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
  kind:  'StorageV2'
  properties:{
    accessTier: this.exists() ? this.existingResource()!.properties.accessTier : 'Cold'
  }
}

existerandeResurs

this.existingResource()

Returnerar objektrepresentationen av resursen om den existerar, eller null om den inte gör det. Denna funktion parar med this.exists(). Medan exists() returnerar en enkel boolean, existingResource() returnerar det faktiska resursobjektet. Du kan säkert komma åt nästlade egenskaper genom att använda null-förlåtande operatorn (!) eller säker navigationsoperator(.?).

Namnrymd: detta

Exempel

resource stg 'Microsoft.Storage/storageAccounts@2026-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'  }
  kind:  'StorageV2'
  properties:{
    accessTier: this.existingResource().?properties.accessTier ?? 'Cold'
  }
}

extensionResourceId

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

Returnerar resurs-ID för en tilläggsresurs. En extension-resurs är en resurstyp som du applicerar på en annan resurs för att utöka dess kapaciteter.

Namnområde: az.

Du kan använda extensionResourceId funktionen i Bicep-filer, men du behöver den vanligtvis inte. Använd i stället det symboliska namnet för resursen och få åtkomst till id egenskapen.

Det grundläggande formatet för resurs-ID:t som returneras av den här funktionen är:

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

Omfångssegmentet varierar beroende på vilken resurs som utökas.

När du applicerar tilläggsresursen på en resurs returneras resurs-ID:t i följande format:

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

När du applicerar extension-resursen på en resursgrupp är formatet:

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

När du applicerar tilläggsresursen på en prenumeration är formatet:

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

När du tillämpar extension-resursen på en ledningsgrupp är formatet:

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

En anpassad principdefinition som distribueras till en hanteringsgrupp implementeras som en tilläggsresurs. Om du vill skapa och tilldela en princip distribuerar du följande Bicep fil till en hanteringsgrupp.

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@2025-03-01' = {
  name: 'locationRestriction'
  properties: {
    policyType: 'Custom'
    mode: 'All'
    parameters: {}
    policyRule: {
      if: {
        not: {
          field: 'location'
          in: allowedLocations
        }
      }
      then: {
        effect: 'deny'
      }
    }
  }
}

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

Inbyggda principdefinitioner är resurser på klientnivå. Ett exempel på hur du distribuerar en inbyggd principdefinition finns i tenantResourceId.

getSecret

keyVaultName.getSecret(secretName)

Returnerar en hemlighet från en Azure Key Vault. Använd den här funktionen för att skicka en hemlighet till en säker strängparameter för en Bicep modul.

Kommentar

Använd az.getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion) funktionen i .bicepparam filer för att hämta nyckelvalvshemligheter. Mer information finns i getSecret.

Du kan bara använda getSecret funktionen inifrån avsnittet i params en modul. Du kan bara använda den med en Microsoft.KeyVault/vaults resurs.

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

Du får ett felmeddelande om du försöker använda den här funktionen i någon annan del av Bicep-filen. Du får också ett fel om du använder den här funktionen med stränginterpolation, även när den används i params-avsnittet.

Använd funktionen endast med en modulparameter som har dekoratorn @secure() .

Nyckelvalvet måste ha enabledForTemplateDeployment angetts till true. Användaren som distribuerar Bicep-filen måste ha åtkomst till hemligheten. Mer information finns i Använd Azure Key Vault för att skicka säkert parametervärde under Bicep distribution.

En namnområdeskvalificerare behövs inte eftersom funktionen används med en resurstyp.

Parametrar

Parameter	Obligatoriskt	Typ	Beskrivning
hemligtNamn	Ja	sträng	Namnet på hemligheten som lagras i ett nyckelvalv.

Returvärde

Det hemliga värdet för det hemliga namnet.

Exempel

Följande Bicep fil används som en modul. Den har en adminPassword parameter som definierats med dekoratören @secure() .

param sqlServerName string
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2024-11-01-preview' = {
  ...
}

Följande Bicep-fil använder föregående Bicep fil som en modul. Filen Bicep refererar till ett befintligt nyckelvalv och anropar funktionen getSecret för att hämta nyckelvalvshemligheten och skickar sedan värdet som en parameter till modulen.

param sqlServerName string
param adminLogin string

param subscriptionId string
param kvResourceGroup string
param kvName string

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

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

lista*

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

Du kan anropa en listfunktion för valfri resurstyp med en åtgärd som börjar med list. Några vanliga användningar är list, listKeys, listKeyValueoch listSecrets.

Syntaxen för den här funktionen varierar beroende på namnet på liståtgärden. De returnerade värdena varierar också beroende på åtgärd. Bicep stöder för närvarande inte slutföranden och validering för list* funktioner.

Med Bicep CLI version 0.4.X eller senare anropar du listfunktionen med hjälp av operatorn accessor. Exempel: storageAccount.listKeys()

En namnområdeskvalificerare behövs inte eftersom funktionen används med en resurstyp.

Parametrar

Parameter	Obligatoriskt	Typ	Beskrivning
apiVersion	Nej	sträng	Om du inte anger den här parametern används API-versionen för resursen. Ange endast en anpassad API-version när du behöver funktionen för att köras med en viss version. Använd formatet yyyy-mm-dd.
functionValues	Nej	objekt	Ett objekt som har värden för funktionen. Ange endast det här objektet för funktioner som stöder mottagande av ett objekt med parametervärden, till exempel `listAccountSas` på ett lagringskonto. Ett exempel på att skicka funktionsvärden visas i den här artikeln.

Giltiga användningsområden

Använd funktionerna list i egenskaperna för en resursdefinition. Använd inte en list funktion som exponerar känslig information i outputs avsnittet i en Bicep-fil. Utdatavärden lagras i distributionshistoriken och en illvillig användare kan hämta dem.

När du använder en list funktion med en iterativ loop kan du använda den för input eftersom uttrycket är tilldelat resursegenskapen. Du kan inte använda den med count eftersom antalet måste bestämma innan list funktionen löses.

Om du använder en list funktion i en resurs som är villkorligt distribuerad utvärderas funktionen även om resursen inte distribueras. Du får ett fel om list funktionen refererar till en resurs som inte finns. Använd villkorsuttrycket ?: operator för att se till att funktionen endast utvärderas när resursen distribueras.

Linterregeln use-recognized-resource-type flaggar alla refererade resurser som använder en icke-erkänd eller ogiltig resurstyp.

Returvärde

Det returnerade objektet varierar beroende på vilken list funktion du använder. Till exempel returnerar listKeys funktionen för ett lagringskonto följande format:

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

Andra list funktioner har olika returformat. För att se formatet på en funktion, inkludera den i outputs avsnittet som visas i exempelfilen Bicep.

Listexempel

I följande exempel distribueras ett lagringskonto och anropas listKeys sedan på lagringskontot. Nyckeln används när du anger ett värde för distributionsskript.

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-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
    }
    ...
  }
}

I nästa exempel visas en list funktion som tar en parameter. I det här fallet är listAccountSasfunktionen . Skicka ett objekt för förfallotiden. Förfallotiden måste vara i framtiden.

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

Implementeringar

Följande tabell visar möjliga användningsområden för list* funktioner.

Resurstyp	Funktionsnamn
Microsoft. Addons/supportProviders	listsupportplaninfo
Microsoft. AnalysisServices/servrar	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/automationKonton	listKeys
Microsoft. Batch/batchAccounts	listkeys
Microsoft. BatchAI/arbetsytor/experiment/jobb	listoutputfiles
Microsoft. BotService/botServices/kanaler	listChannelWithKeys
Microsoft. Cache/redis	listKeys
Microsoft. CognitiveServices/konton	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/register/uppgifter	listDetails
Microsoft. ContainerService/managedClusters	listClusterAdminCredential
Microsoft. ContainerService/managedClusters	listClusterMonitoringUserCredential
Microsoft. ContainerService/managedClusters	listClusterUserCredential
Microsoft. ContainerService/managedClusters/accessProfiles	listCredential
Microsoft. DataBox/jobb	listCredentials
Microsoft. DataFactory/datafactories/gateways	visa listauthkeys
Microsoft. DataFactory/fabriker/integrationruntimes	visa listauthkeys
Microsoft. DataLakeAnalytics/accounts/storageAccounts/Containers	listSasTokens
Microsoft. DataShare/konton/resurser	listSynkroniseringar
Microsoft. DataShare/accounts/sharePrenumerationer	listSourceShareSynchronizationSettings
Microsoft. DataShare/accounts/sharePrenumerationer	listSynchronizationDetails
Microsoft. DataShare/accounts/sharePrenumerationer	listSynkroniseringar
Microsoft. Enheter/iotHubs	listkeys
Microsoft. Enheter/iotHubs/iotHubKeys	listkeys
Microsoft. Enheter/provisioningTjänster/nycklar	listkeys
Microsoft. Enheter/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. Domänregistrering	listDomainRecommendations
Microsoft. DomainRegistration/topLevelDomains	listAgreements
Microsoft. EventGrid/domäner	listKeys
Microsoft. EventGrid/topics	listKeys
Microsoft. EventHub/namespaces/authorizationRules	listkeys
Microsoft. EventHub/namespaces/disasterRecoveryConfigs/authorizationRules	listkeys
Microsoft. EventHub/namespaces/eventhubs/authorizationRules	listkeys
Microsoft. ImportExport/jobb	listBitLockerKeys
Microsoft. Kusto/Kluster/Databaser	ListPrincipals
Microsoft. LabServices/labs/users	lista
Microsoft. LabServices/labs/virtualMachines	lista
Microsoft. Logic/integrationAccounts/agreements	listContentCallbackUrl
Microsoft. Logic/integrationAccounts/sammansättningar	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. Logik/arbetsflöden	listCallbackUrl
Microsoft. Logik/arbetsflöden	listSwagger
Microsoft. Logik/arbetsflöden/körningar/åtgärder	listExpressionTraces
Microsoft. Logik/arbetsflöden/körningar/åtgärder/upprepningar	listExpressionTraces
Microsoft. Logik/arbetsflöden/utlösare	listCallbackUrl
Microsoft. Logik/arbetsflöden/versioner/utlösare	listCallbackUrl
Microsoft. MachineLearning/webServices	listkeys
Microsoft. MachineLearning/Workspaces	listworkspacekeys
Microsoft. MachineLearningServices/arbetsytor/beräkningar	listKeys
Microsoft. MachineLearningServices/arbetsytor/beräkningar	listNoder
Microsoft. MachineLearningServices/arbetsytor	listKeys
Microsoft. Kartor/konton	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/arbetsytor	lista
Microsoft. OperationalInsights/arbetsytor	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/chefer/enheter	listFailoverSets
Microsoft. StorSimple/chefer/enheter	listFailoverTargets
Microsoft. StorSimple/chefer	listActivationKey
Microsoft. StorSimple/chefer	listPublicEncryptionKey
Microsoft. Synapse/workspaces/integrationRuntimes	listAuthKeys
Microsoft. Webb/anslutningGateways	ListStatus
microsoft.web/connections	listconsentlinks
Microsoft. Webb/customApis	listWsdlInterfaces
microsoft.web/locations	listwsdlinterfaces
microsoft.web/apimanagementaccounts/apis/connections	listconnectionkeys
microsoft.web/apimanagementaccounts/apis/connections	listsecrets
microsoft.web/sites/backups	lista
Microsoft. Webb/webbplatser/konfiguration	lista
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	lista
Microsoft. Web/sites/slots/config	lista
microsoft.web/sites/slots/functions	listsecrets

För att avgöra vilka resurstyper som har en listoperation, använd följande alternativ:

Visa REST API-åtgärderna för en resursprovider och leta efter liståtgärder. Lagringskonton har till exempel åtgärden listKeys.

Använd Cmdleten Get-AzProviderOperation PowerShell. I följande exempel hämtas alla liståtgärder för lagringskonton:

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

Använd följande Azure CLI kommando för att filtrera endast liståtgärderna:

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

managementGroupResourceId

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

Returnerar den unika identifieraren för en resurs som distribueras på hanteringsgruppsnivå.

Namnområde: az.

Funktionen managementGroupResourceId finns tillgänglig i Bicep-filer, men du behöver den vanligtvis inte. Använd i stället det symboliska namnet för resursen och få åtkomst till id egenskapen.

Identifieraren returneras i följande format:

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

Kommentarer

Använd denna funktion för att hämta resurs-ID för resurser som distribueras till hanteringsgruppen istället för en resursgrupp. Det returnerade ID:t skiljer sig från värdet som returneras av funktionen resourceId genom att inte inkludera ett prenumerations-ID och ett resursgruppsvärde.

managementGroupResourceID-exempel

Följande mall skapar och tilldelar en principdefinition. Den använder managementGroupResourceId funktionen för att hämta resurs-ID:t för principdefinitionen.

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@2025-03-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@2025-03-01' = {
  name: 'location-lock'
  properties: {
    scope: mgScope
    policyDefinitionId: managementGroupResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionName)
  }
  dependsOn: [
    policyDefinition
  ]
}

pickZones

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

Avgör om en resurstyp stöder zoner för en region. Den här funktionen stöder endast zonindeliga resurser. Zonredundanta tjänster returnerar en tom matris. Mer information finns i Azure tjänster som stöder tillgänglighetszoner.

Namnområde: az.

Parametrar

Parameter	Obligatoriskt	Typ	Beskrivning
providerNamespace (på engelska)	Ja	sträng	Resursproviderns namnområde för resurstypen för att söka efter zonstöd.
resurstyp	Ja	sträng	Resurstypen för att söka efter zonstöd.
plats	Ja	sträng	Regionen för att söka efter zonstöd.
numberOfZones	Nej	heltal	Antalet logiska zoner som ska returneras. Standardvärdet är 1. Talet måste vara ett positivt heltal från 1 till 3. Använd 1 för resurser med en zon. För resurser med flera zoner måste värdet vara mindre än eller lika med antalet zoner som stöds.
förskjutning	Nej	heltal	Förskjutningen från den logiska startzonen. Funktionen returnerar ett fel om förskjutningen plus numberOfZones överskrider antalet zoner som stöds.

Returvärde

En matris med de zoner som stöds. När du använder standardvärdena för offset och numberOfZones, returnerar en resurstyp och region som stödjer zoner följande array:

[
  "1"
]

När du sätter parametern numberOfZones till 3 returnerar den:

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

När resurstypen eller regionen inte stödjer zoner returnerar funktionen en tom array.

[
]

Kommentarer

Azure Availability Zones faller in i två kategorier – zon- och zon-redundanta. Använd pickZones funktionen för att returnera en tillgänglighetszon för en zonresurs. För zonredundanta tjänster (ZRS) returnerar funktionen en tom matris. Zonindeliga resurser har vanligtvis en zones egenskap på den översta nivån i resursdefinitionen. Information om vilken kategori av stöd som finns för tillgänglighetszoner finns i Azure tjänster som stöder tillgänglighetszoner.

För att avgöra om en viss Azure region eller plats stöder tillgänglighetszoner anropar du funktionen pickZones med en zonindelad resurstyp, till exempel Microsoft.Network/publicIPAddresses. Om svaret inte är tomt stöder regionen tillgänglighetszoner.

pickZones-exempel

Följande Bicep-fil visar tre resultat för att använda funktionen 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')

Utdata från föregående exempel returnerar tre matriser.

Namn	Typ	Värde
stöds	matris	[ "1" ]
notSupportedRegion	matris	[]
notSupportedType	matris	[]

Använd svaret från pickZones för att avgöra om du ska ange null för zoner eller tilldela virtuella maskiner till olika zoner.

Leverantörer

Leverantörens funktion är föråldrad i Bicep. Använd den inte. Om du använde denna funktion för att få en API-version för resursleverantören, ange en specifik API-version i din Bicep-fil. Om du använder en dynamiskt returnerad API-version kan mallen brytas om egenskaperna ändras mellan versionerna.

Provideråtgärden är fortfarande tillgänglig via REST-API:et. Du kan använda det utanför en Bicep-fil för att få information om en resursleverantör.

Namnområde: az.

hänvisning

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

Returnerar ett objekt som representerar en resurss runtime-tillstånd. Funktionens utdata och beteende reference beror starkt på hur varje resursleverantör (RP) implementerar sina PUT- och GET-svar.

Namnområde: az.

Bicep-filer ger tillgång till referensfunktionen, även om du vanligtvis inte behöver den. Använd istället resursens symboliska namn. Du kan bara använda referensfunktionen inom objektet i properties en resurs. Du kan inte använda det för toppnivå-egenskaper som name eller location. Samma regel gäller i allmänhet för referenser som använder det symboliska namnet. Men för egenskaper som name, kan du generera en mall utan att använda referensfunktionen. Du vet tillräckligt om resursnamnet för att direkt kunna ge ut namnet. Dessa är kompileringstidsegenskaper. Bicep verifiering kan identifiera felaktig användning av det symboliska namnet.

I följande exempel distribueras ett lagringskonto. De två första utdata ger samma resultat.

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

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-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

För att hämta en egenskap från en befintlig resurs som du inte distribuerade i mallen, använd nyckelordet existing :

param storageAccountName string

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

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

För att referera till en resurs som är nästlad i en föräldraresurs, använd den nästlade accessorn (::). Du använder bara den här syntaxen när du kommer åt den kapslade resursen utanför den överordnade resursen.

vNet1::subnet1.properties.addressPrefix

Om du försöker referera till en resurs som inte finns får du felet och distributionen NotFound misslyckas. Linterregeln use-recognized-resource-type flaggar alla refererade resurser som använder en icke-erkänd eller ogiltig resurstyp.

resursId

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

Returnerar den unika identifieraren för en resurs.

Namnområde: az.

Funktionen resourceId finns tillgänglig i Bicep-filer, men du behöver den vanligtvis inte. Använd i stället det symboliska namnet för resursen och få åtkomst till id egenskapen.

Använd denna funktion när resursnamnet är tvetydigt eller inte provisionerat inom samma Bicep-fil. Formatet för den returnerade identifieraren varierar beroende på om distributionen sker i omfånget för en resursgrupp, prenumeration, hanteringsgrupp eller klientorganisation.

Till exempel:

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

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

output storageID string = storageAccount.id

Använd det befintliga nyckelordet för att hämta resurs-ID:t för en resurs som inte har distribuerats i filen Bicep.

param storageAccountName string

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

output storageID string = storageAccount.id

Mer information finns i funktionen resourceId för JSON-mall.

rolldefinitioner

roleDefinitions(roleName)

Returnerar information om den angivna rolldefinitionen, inklusive id och roleDefinitionId. Det är en namnbaserad hjälp för Azure RBAC-rolltilldelningar. Istället för att kräva att du hårdkodar GUID:en för en anpassad eller inbyggd rolldefinition (som Contributor, Reader och andra), låter den dig ange den anpassade eller inbyggda rollens visningsnamn, och funktionen löser motsvarande rolldefinitionsinformation vid implementering.

Namnområde: az.

Parametrar

Parameter	Obligatoriskt	Typ	Beskrivning
roleName	Ja	sträng	Rolldefinitionens visningsnamn.

Returvärde

Ett objekt som representerar rolldefinitionen, inklusive id och roleDefinitionId.

Exempel

Följande Bicep-kod skapar en deterministisk Azure RBAC-rolltilldelning som ger en specificerad huvudperson den inbyggda Storage Blob Data Reader-rollen vid distributionsområdet genom att lösa rolldefinitionen med namn vid distributionstillfället.

@description('Specifies the role definition ID used in the role assignment.')
param roleDefinitionName string = 'Storage Blob Data Reader'

@description('Specifies the principal ID assigned to the role.')
param principalId string

var roleAssignmentName= guid(principalId, roleDefinitionName, resourceGroup().id)
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: roleDefinitions(roleDefinitionName).id
    principalId: principalId
  }
}

Mer information finns i funktionen resourceId för JSON-mall.

subscriptionResourceId

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

Returnerar den unika identifieraren för en resurs som distribueras på prenumerationsnivå.

Namnområde: az.

Funktionen subscriptionResourceId är tillgänglig i Bicep filer, men vanligtvis behöver du den inte. Använd i stället det symboliska namnet för resursen och få åtkomst till id egenskapen.

Identifieraren returneras i följande format:

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

Kommentarer

Använd denna funktion för att få resurs-ID för resurser som distribueras till prenumerationen istället för en resursgrupp. Det returnerade ID:t skiljer sig från det värde som returneras av funktionen resourceId genom att inte inkludera ett resursgruppsvärde.

subscriptionResourceId-exempel

Följande Bicep fil tilldelar en inbyggd roll. Du kan distribuera den till antingen en resursgrupp eller prenumeration. Den använder subscriptionResourceId funktionen för att hämta resurs-ID:t för inbyggda roller.

@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], ...)

Returnerar den unika identifieraren för en resurs som distribuerats på klientorganisationsnivå.

Namnområde: az.

Funktionen tenantResourceId är tillgänglig i Bicep filer, men vanligtvis behöver du den inte. Använd i stället det symboliska namnet för resursen och få åtkomst till id egenskapen.

Identifieraren returneras i följande format:

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

Inbyggda principdefinitioner är resurser på klientnivå. Om du vill distribuera en principtilldelning som refererar till en inbyggd principdefinition använder du tenantResourceId funktionen.

@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@2025-03-01' = {
  name: policyAssignmentName
  properties: {
    scope: subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)
    policyDefinitionId: tenantResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionID)
  }
}

toLogicalZone

toLogicalZone(subscriptionId, location, physicalZone)

Returnerar den logiska tillgänglighetszonen (till exempel 1, 2, eller 3) som motsvarar en fysisk tillgänglighetszon för en specificerad prenumeration i en given Azure-region.

Namnområde: az

Parametrar

Parameter	Obligatoriskt	Typ	Beskrivning
prenumerations-ID	Ja	sträng	ID:t för Azure-prenumerationen, såsom `12345678-1234-1234-1234-1234567890ab`.
plats	Ja	sträng	Azure-regionen som stödjer tillgänglighetszoner, såsom `westus2`.
physicalZone	Ja	sträng	Identifieraren för den fysiska tillgänglighetszonen (till exempel en datacenterspecifik identifierare som `westus2-az1`).

Returvärde

En sträng som representerar den logiska tillgänglighetszonen (till exempel 1, 2, eller 3) som motsvarar den angivna fysiska zonen i den angivna regionen och prenumerationen. Om den fysiska zonen är ogiltig eller inte stöds, returnerar funktionen en tom sträng ('').

Kommentarer

Funktionen toLogicalZone hämtar mappningen för den logiska zonen baserat på prenumerationens zonkonfiguration i den angivna regionen.
Logiska zoner är standardiserade identifierare (till exempel 1, 2, 3) som används i resurskonfigurationer för att säkerställa konsekventa zontilldelningar mellan Azure tjänster.
Fysiska zonidentifierare är regionsspecifika och kan variera mellan prenumerationer. toPhysicalZone Använd funktionen för att återställa den här mappningen.
Funktionen kräver att regionen stöder tillgänglighetszoner. En lista över regioner som stöds finns i Azure tjänster som stöder tillgänglighetszoner.
Om den fysiska zonen inte finns eller inte mappas för prenumerationen returnerar funktionen en tom sträng.
Den här funktionen är användbar för att justera fysiska zondistributioner med logiska zonkonfigurationer i mallar, särskilt för scenarier mellan prenumerationer eller flera regioner.

Exempel

I följande exempel hämtas den logiska zonen för en fysisk zon i USA, västra 2 för en specifik prenumeration:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'

output logicalZone string = toLogicalZone(subscriptionId, 'westus2', physicalZone)

Förväntat resultat:

Namn	Typ	Värde
logicalZone	Sträng	`1`

I följande exempel används toLogicalZone för att konfigurera en virtuell dator med rätt logisk zon:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'
param location string = 'westus2'

var logicalZone = toLogicalZone(subscriptionId, location, physicalZone)

resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
  name: 'myVM'
  location: location
  zones: logicalZone != '' ? [logicalZone] : []
  properties: {
    // VM properties
  }
}

output logicalZone string = logicalZone

Förväntat resultat:

Namn	Typ	Värde
logicalZone	Sträng	`1`

toLogicalZones

toLogicalZones(subscriptionId, location, physicalZones)

Returnerar de logiska tillgänglighetszonerna (till exempel 1, 2 eller 3) som motsvarar fysiska tillgänglighetszoner för en angiven prenumeration i en viss Azure region. Om du vill konvertera en enskild fysisk zon använder du toLogicalZone funktionen.

Namnområde: az

Parametrar

Parameter	Obligatoriskt	Typ	Beskrivning
prenumerations-ID	Ja	sträng	ID:t för Azure-prenumerationen, såsom `12345678-1234-1234-1234-1234567890ab`.
plats	Ja	sträng	Azure-regionen som stödjer tillgänglighetszoner, såsom `westus2`.
physicalZones	Ja	matris	En matris med fysiska zonnamn som ska konverteras till logiska zoner (till exempel en datacenterspecifik identifierare som `westus2-az1`, `westus2-az2`, ...).

Returvärde

En matris med logiska zonnamn som motsvarar de angivna fysiska zonerna (till exempel 1, 2eller 3). Om en fysisk zon är ogiltig eller inte stöds, returnerar funktionen en tom sträng ('').

Kommentarer

Funktionen toLogicalZones mappar fysiska zonnamn till deras logiska zonekvivalenter för en angiven Azure prenumeration och region. Denna kartläggning är användbar för att konfigurera eller förfråga resurser baserat på logiska zoner inom en Azure-region. Funktionen kräver ett giltigt prenumerations-ID, en Azure plats som stöds och en matris med fysiska zonnamn. Om en fysisk zon är ogiltig eller inte tillgänglig på den angivna platsen kan funktionen returnera en tom sträng för den zonen eller ge ett fel, beroende på sammanhanget.

Exempel

I följande exempel hämtas de logiska zonerna för en lista över fysiska zoner i USA, västra 2 för en specifik prenumeration:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZones array = ['westus2-az1', 'westus2-az2', 'westus2-az3']

output logicalZones array = toLogicalZones(subscriptionId, 'westus2', physicalZones)

Förväntat resultat:

Namn	Typ	Värde
logicalZone	matris	["1","2","3"]

toPhysicalZone

toPhysicalZone(subscriptionId, location, logicalZone)

Returnerar den fysiska tillgänglighetszonidentifieraren, såsom en datacenterspecifik identifierare som westus2-az1, som motsvarar en logisk tillgänglighetszon för en specificerad prenumeration i en given Azure-region.

Namnområde: az

Parametrar

Parameter	Obligatoriskt	Typ	Beskrivning
prenumerations-ID	Ja	sträng	ID:t för Azure-prenumerationen, såsom `12345678-1234-1234-1234-1234567890ab`.
plats	Ja	sträng	Azure-regionen som stödjer tillgänglighetszoner, såsom `westus2`.
logicalZone	Ja	sträng	Den logiska tillgänglighetszonen, såsom `1`, `2`, eller `3`.

Returvärde

En sträng som representerar den fysiska tillgänglighetszonidentifieraren, såsom westus2-az1, som motsvarar den specificerade logiska zonen i den givna regionen och prenumerationen. Om den logiska zonen är ogiltig eller inte stöds, returnerar funktionen en tom sträng ('').

Kommentarer

Funktionen toPhysicalZone hämtar den fysiska zonmappningen baserat på prenumerationens zonkonfiguration i den angivna regionen.
Fysiska zoner är datacenterspecifika identifierare som kan variera mellan prenumerationer, medan logiska zoner, såsom 1, 2, 3, är standardiserade för resurskonfigurationer.
Använd toLogicalZone funktionen för att vända denna avbildning och konvertera en fysisk zon till dess logiska motsvarighet.
Funktionen kräver att regionen stöder tillgänglighetszoner. En lista över regioner som stöds finns i Azure tjänster som stöder tillgänglighetszoner.
Om den logiska zonen inte finns eller inte är mappad för prenumerationen returnerar funktionen en tom sträng.
Denna funktion är användbar i scenarier som kräver fysiska zonidentifierare, såsom loggning, revision eller zonjustering över prenumerationer i multiregiondistributioner.

Exempel

I följande exempel hämtas den fysiska zonen för en logisk zon i USA, västra 2 för en specifik prenumeration:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'

output physicalZone string = toPhysicalZone(subscriptionId, 'westus2', logicalZone)

Förväntade utdata (förutsatt att logisk zon 1 mappar till westus2-az1):

Namn	Typ	Värde
physicalZone	Sträng	`westus2-az1`

I följande exempel används toPhysicalZone för att logga den fysiska zonen för en distribution av virtuella datorer:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'
param location string = 'westus2'

var physicalZone = toPhysicalZone(subscriptionId, location, logicalZone)

resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
  name: 'myVM'
  location: location
  zones: [logicalZone]
  properties: {
    // VM properties
  }
}

output physicalZone string = physicalZone

Förväntat resultat:

Namn	Typ	Värde
physicalZone	Sträng	`westus2-az1`

toPhysicalZones

toPhysicalZones(subscriptionId, location, logicalZones)

Returnerar identifierare för den fysiska tillgänglighetszonen (till exempel en datacenterspecifik identifierare som westus2-az1) som motsvarar logiska tillgänglighetszoner för en angiven prenumeration i en viss Azure region. Om du vill konvertera en enda logisk zon använder du toPhysicalZone funktionen.

Namnområde: az

Parametrar

Parameter	Obligatoriskt	Typ	Beskrivning
prenumerations-ID	Ja	sträng	ID:t för Azure-prenumerationen, såsom `12345678-1234-1234-1234-1234567890ab`.
plats	Ja	sträng	Azure-regionen som stödjer tillgänglighetszoner, såsom `westus2`.
logicalZone	Ja	sträng[]	De logiska tillgänglighetszonerna (till exempel `1`, `2`eller `3`) för att konvertera till fysiska zoner.

Returvärde

En matris med fysiska zonnamn (till exempel westus2-az1, westus2-az2 ) som motsvarar de angivna logiska zonerna. Om en logisk zon är ogiltig eller inte stöds, returnerar funktionen en tom sträng ('').

Kommentarer

Funktionen toPhysicalZones mappar logiska zonnamn till deras fysiska zonekvivalenter för en angiven Azure prenumeration och region. Denna kartläggning är användbar för att distribuera eller konfigurera resurser i specifika fysiska zoner inom en Azure-region. Funktionen kräver ett giltigt prenumerations-ID, en Azure plats som stöds och en matris med namn på logiska zoner. Om en logisk zon är ogiltig eller otillgänglig på den angivna platsen kan funktionen returnera en tom sträng för den zonen eller ge ett fel, beroende på sammanhanget.

Exempel

I följande exempel hämtas de fysiska zonerna för en lista över logiska zoner i USA, västra 2 för en specifik prenumeration:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZones array = ['1', '2', '3']

output physicalZones array = toPhysicalZones(subscriptionId, 'westus2', logicalZones)

Förväntade utdata (förutsatt att logisk zon 1 mappar till westus2-az1, mappar logisk zon 1 till westus2-az1och logisk zon 3 mappar till westus2-az3):

Namn	Typ	Värde
physicalZone	matris	["westus2-az1","westus2-az2","westus2-az3"]

Nästa steg

Information om hur du hämtar värden från den aktuella distributionen finns i Funktioner för distributionsvärde.
Information om hur du itererar ett angivet antal gånger när du skapar en typ av resurs finns i Iterativa loopar i Bicep.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-06-26

Resursfunktioner för Bicep

Namnrymden this

finns

Exempel

existerandeResurs

Exempel

extensionResourceId

getSecret

Parametrar

Returvärde

Exempel

lista*

Parametrar

Giltiga användningsområden

Returvärde

Listexempel

Implementeringar

managementGroupResourceId

Kommentarer

managementGroupResourceID-exempel

pickZones

Parametrar

Returvärde

Kommentarer

pickZones-exempel

Leverantörer

hänvisning

resursId

rolldefinitioner

Parametrar

Returvärde

Exempel

subscriptionResourceId

Kommentarer

subscriptionResourceId-exempel

tenantResourceId

toLogicalZone

Parametrar

Returvärde

Kommentarer

Exempel

toLogicalZones

Parametrar

Returvärde

Kommentarer

Exempel

toPhysicalZone

Parametrar

Returvärde

Kommentarer

Exempel

toPhysicalZones

Parametrar

Returvärde

Kommentarer

Exempel

Nästa steg

Feedback

Ytterligare resurser

Namnrymden `this`