Fungsi sumber daya untuk templat ARM

Resource Manager menyediakan fungsi berikut untuk mendapatkan nilai sumber daya di templat Azure Resource Manager Anda (templat ARM):

Untuk mendapatkan nilai dari parameter, variabel, atau penyebaran saat ini, lihat fungsi nilai penyebaran.

Untuk mendapatkan nilai cakupan penyebaran, lihat fungsi cakupan.

Petunjuk / Saran

Bicep direkomendasikan karena menawarkan kemampuan yang sama dengan templat ARM, dan sintaksnya lebih mudah digunakan. Untuk mempelajari selengkapnya, lihat fungsi Bicep resource.

extensionResourceId

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

Menampilkan ID sumber daya untuk sumber daya ekstensi. Sumber daya ekstensi adalah jenis sumber daya yang diterapkan ke sumber daya lainnya untuk menambah kapabilitasnya.

Argumen pertama harus berupa ID sumber daya yang sepenuhnya memenuhi syarat dari sumber daya yang digunakan oleh sumber daya ekstensi. Persyaratan ini sangat penting ketika Anda menerapkan sumber daya tingkat tenant dari cakupan yang lebih rendah, seperti langganan atau grup sumber daya. Nilai yang terselesaikan pada lingkup tenant dapat gagal ketika penerapan dimulai dari lingkup yang lebih rendah.

Di Bicep, gunakan fungsi extensionResourceId.

Parameter

Pengaturan Wajib Tipe Deskripsi
baseResourceId Ya string ID sumber daya yang memenuhi syarat penuh untuk sumber daya yang menjadi tempat sumber daya ekstensi diterapkan.
tipe sumber daya Ya string Jenis sumber daya ekstensi termasuk namespace penyedia sumber daya.
resourceName1 Ya string Nama sumber daya ekstensi.
resourceName2 Tidak. string Segmen nama sumber daya berikutnya, jika diperlukan.

Terus tambahkan nama sumber daya sebagai parameter ketika jenis sumber daya menyertakan lebih banyak segmen.

Nilai hasil

Format dasar ID sumber daya yang dikembalikan oleh fungsi ini adalah:

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

Segmen cakupan bervariasi menurut sumber daya dasar yang diperluas. Misalnya, ID untuk langganan memiliki segmen yang berbeda dari ID untuk grup sumber daya.

Ketika sumber daya ekstensi diterapkan ke sumber daya, ID sumber daya dikembalikan dalam format berikut:

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

Bila sumber daya ekstensi diterapkan ke grup sumber daya, format yang dikembalikan adalah:

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

Contoh menggunakan fungsi ini dengan grup sumber daya ditampilkan di bagian berikutnya.

Saat sumber daya ekstensi diterapkan ke langganan, format yang dikembalikan adalah:

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

Bila sumber daya ekstensi diterapkan ke grup pengelolaan, format yang dikembalikan adalah:

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

Contoh menggunakan fungsi ini dengan grup manajemen ditampilkan di bagian berikutnya.

Contoh extensionResourceId

Contoh berikut mengembalikan ID sumber daya untuk kunci grup sumber daya:

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

Definisi kebijakan kustom yang disebarkan ke grup manajemen diimplementasikan sebagai sumber daya ekstensi. Untuk membuat dan menetapkan kebijakan, sebarkan templat berikut ini ke grup manajemen.

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

Definisi kebijakan bawaan adalah sumber daya tingkat penyewa. Untuk contoh penyebaran definisi kebijakan bawaan, lihat tenantResourceId.

daftar*

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

Sintaksis untuk fungsi ini bervariasi menurut nama operasi daftar. Setiap implementasi mengembalikan nilai untuk jenis sumber daya yang mendukung operasi daftar. Nama operasi harus dimulai dengan list dan mungkin memiliki akhiran. Beberapa penggunaan umum adalah list, listKeys, listKeyValue, dan listSecrets.

Di Bicep, gunakan fungsi list*.

Parameter

Pengaturan Wajib Tipe Deskripsi
resourceName atau resourceIdentifier Ya string Pengidentifikasi unik untuk sumber daya.
apiVersi Ya string Versi API dari status runtime bahasa umum sumber daya. Biasanya, dalam format, yyyy-mm-dd.
functionValues Tidak. objek Objek yang memiliki nilai untuk fungsi tersebut. Sediakan objek ini hanya untuk fungsi yang mendukung penerimaan objek dengan nilai parameter, seperti listAccountSas pada akun penyimpanan. Contoh nilai fungsi meneruskan ditunjukkan dalam artikel ini.

Penggunaan yang valid

Fungsi daftar dapat digunakan dalam properti definisi sumber daya. Jangan gunakan fungsi daftar yang memaparkan informasi sensitif di bagian output templat. Nilai output disimpan dalam riwayat penyebaran dan dapat diambil oleh pengguna berbahaya.

Saat digunakan dengan properti perulangan, Anda dapat menggunakan fungsi daftar untuk input karena ekspresi ditetapkan ke properti sumber daya. Anda tidak dapat menggunakannya dengan count karena hitungan harus ditentukan sebelum fungsi daftar diselesaikan.

Implementasi

Kemungkinan penggunaan list* ditunjukkan dalam tabel berikut ini.

Jenis Sumber Daya Nama fungsi
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/ruang kerja/eksperimen/pekerjaan 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/pekerjaan 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. Perangkat/iotHubs listKeys
Microsoft. Perangkat/iotHubs/iotHubKeys listKeys
Microsoft. Perangkat/provisioningServices/keys listKeys
Microsoft. Perangkat/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/Kluster/Database ListPrincipals
Microsoft. LabServices/labs/users daftar
Microsoft. LabServices/labs/virtualMachines daftar
Microsoft. Logika/integrasiAccounts/agreements listContentCallbackUrl
Microsoft. Logika/integrasiAccounts/assemblies listContentCallbackUrl
Microsoft. Logika/integrasiAccounts listCallbackUrl
Microsoft. Logika/integrasiAccounts listKeyVaultKeys
Microsoft. Logika/integrasiAccounts/maps listContentCallbackUrl
Microsoft. Logika/integrasiAccounts/partner listContentCallbackUrl
Microsoft. Logika/integrasiAccounts/skema listContentCallbackUrl
Microsoft. Logika/alur kerja listCallbackUrl
Microsoft. Logika/alur kerja listSwagger
Microsoft. Logika/alur kerja/eksekusi/tindakan listExpressionTraces
Microsoft. Logika/alur kerja/eksekusi/tindakan/pengulangan listExpressionTraces
Microsoft. Logika/alur kerja/pemicu listCallbackUrl
Microsoft. Logika/alur kerja/versi/pemicu listCallbackUrl
Microsoft. MachineLearning/webServices listkeys
Microsoft. MachineLearning/Workspaces listworkspacekeys
Microsoft. Peta/akun 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/ruang kerja daftar
Microsoft. OperationalInsights/ruang kerja 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/manajer/perangkat listFailoverSets
Microsoft. StorSimple/manajer/perangkat listFailoverTargets
Microsoft. StorSimple/manajer listActivationKey
Microsoft. StorSimple/manajer listPublicEncryptionKey
Microsoft. Synapse/workspaces/integrationRuntimes listAuthKeys
Microsoft. Web/connectionGateways ListStatus
microsoft.web/connections listconsentlink
Microsoft. Web/customApis listWsdlInterfaces
microsoft.web/locations listwsdlinterfaces
microsoft.web/apimanagementaccounts/apis/connections listconnectionkeys
microsoft.web/apimanagementaccounts/apis/connections listSecrets
microsoft.web/sites/backups daftar
Microsoft. Web/sites/config daftar
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 daftar
Microsoft. Web/sites/slots/config daftar
microsoft.web/sites/slots/functions listSecrets

Untuk menentukan jenis sumber daya mana yang memiliki operasi daftar, Anda memiliki opsi berikut:

  • Lihat operasi REST API untuk penyedia sumber, dan cari operasi daftar. Misalnya, akun penyimpanan memiliki operasi listKeys.

  • Gunakan cmdlet PowerShell Get-​AzProvider​Operation. Contoh berikut ini mendapatkan semua operasi daftar untuk akun penyimpanan:

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

  • Gunakan perintah Azure CLI berikut untuk memfilter hanya operasi daftar:

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

Nilai hasil

Objek yang ditampilkan bervariasi berdasarkan fungsi list yang Anda gunakan. Misalnya, listKeys untuk akun penyimpanan menampilkan format berikut:

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

Fungsi list lainnya memiliki format tampilan yang berbeda. Untuk melihat format fungsi, sertakan dalam bagian output seperti yang ditunjukkan dalam templat contoh.

Keterangan

Tentukan sumber daya dengan menggunakan nama sumber daya atau resourceId fungsi . Saat menggunakan fungsi list dalam templat yang sama yang menyebarkan sumber daya yang direferensikan, gunakan nama sumber daya.

Jika Anda menggunakan list fungsi dalam sumber daya yang disebarkan secara kondisional, fungsi dievaluasi meskipun sumber daya tidak disebarkan. Anda mendapatkan kesalahan jika fungsi list merujuk ke sumber daya yang tidak ada. Gunakan fungsi if untuk memastikan fungsi hanya dievaluasi saat sumber daya sedang disebarkan. if Lihat fungsi untuk templat sampel yang menggunakan if dan list dengan sumber daya yang disebarkan secara kondisional.

Contoh daftar

Contoh berikut menggunakan listKeys saat mengatur nilai skrip penyebaran.

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

Contoh berikutnya memperlihatkan fungsi list yang mengambil parameter. Dalam kasus ini, fungsinya adalah listAccountSas. Teruskan objek untuk waktu kedaluwarsa. Waktu kedaluwarsa harus di masa depan.

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

Menentukan apakah jenis sumber daya mendukung zona untuk lokasi atau wilayah yang ditentukan. Fungsi ini hanya mendukung sumber daya dalam zona. Layanan dengan redundansi zona menampilkan array kosong. Untuk informasi selengkapnya, lihat layanan Azure yang mendukung zona ketersediaan.

Di Bicep, gunakan fungsi pickZones.

Parameter

Pengaturan Wajib Tipe Deskripsi
providerNamespace Ya string Namespace layanan penyedia sumber untuk jenis sumber daya untuk memeriksa dukungan zona.
tipe sumber daya Ya string Jenis sumber daya untuk memeriksa dukungan zona.
lokasi Ya string Wilayah untuk memeriksa dukungan zona.
numberOfZones Tidak. Integer Jumlah zona logika yang dikembalikan. Defaultnya adalah 1. Angka tersebut harus merupakan bilangan bulat positif dari 1 hingga 3. Gunakan 1 untuk sumber daya zona tunggal. Untuk sumber daya multi-zona, nilainya harus kurang dari atau sama dengan jumlah zona yang didukung.
Offset Tidak. Integer Offset dari zona logika awal. Fungsi mengembalikan kesalahan jika offset plus numberOfZones melebihi jumlah zona yang didukung.

Nilai hasil

Array dengan zona yang didukung. Ketika menggunakan nilai default untuk offset dan numberOfZones, jenis dan wilayah sumber daya yang mendukung zona menampilkan array berikut ini:

[
    "1"
]

Saat parameter numberOfZones diatur ke 3, parameter akan mengembalikan:

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

Saat jenis atau wilayah sumber daya tidak mendukung zona, array kosong akan dikembalikan. Array kosong juga dikembalikan untuk layanan zona berlebih.

[
]

Keterangan

Ada berbagai kategori untuk Azure Availability Zones - zonal dan zona-redundan. Fungsi pickZones dapat digunakan untuk menampilkan zona ketersediaan untuk sebuah sumber daya dalam zona. Untuk layanan dengan redundansi zona (ZRS), fungsinya akan menampilkan array kosong. Sumber daya dalam zona biasanya memiliki properti zones di tingkat teratas definisi sumber daya. Untuk menentukan kategori dukungan untuk zona ketersediaan, lihat layanan Azure yang mendukung zona ketersediaan.

Untuk menentukan apakah wilayah atau lokasi Azure tertentu mendukung zona ketersediaan, panggil fungsi pickZones dengan jenis sumber daya zonal, seperti Microsoft.Network/publicIPAddresses. Jika respons tidak kosong, maka wilayah tersebut mendukung zona ketersediaan.

Contoh pickZones

Templat berikut menunjukkan tiga hasil untuk menggunakan pickZones fungsi :

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

Output dari contoh sebelumnya mengembalikan tiga array.

Nama Tipe Nilai
didukung array [ "1" ]
notSupportedRegion array []
notSupportedType array []

Anda dapat menggunakan respons dari pickZones untuk menentukan apakah akan menyediakan null untuk zona atau menetapkan komputer virtual ke zona yang berbeda. Contoh berikut menetapkan nilai untuk zona berdasarkan ketersediaan zona:

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

Azure Cosmos DB bukan sumber daya zonal, tetapi Anda dapat menggunakan fungsi pickZones untuk menentukan apakah akan mengaktifkan redundansi zona untuk georeplikasi. Lewati Microsoft. Penyimpanan/storageAccounts jenis sumber daya untuk menentukan apakah akan mengaktifkan redundansi zona:

"resources": [
  {
    "type": "Microsoft.DocumentDB/databaseAccounts",
    "apiVersion": "2025-05-01-preview",
    "name": "[variables('accountName_var')]",
    "location": "[parameters('location')]",
    "kind": "GlobalDocumentDB",
    "properties": {
      "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
      "locations": [
        {
          "locationName": "[parameters('primaryRegion')]",
          "failoverPriority": 0,
          "isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('primaryRegion'))), bool('false'), bool('true'))]",
        },
        {
          "locationName": "[parameters('secondaryRegion')]",
          "failoverPriority": 1,
          "isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('secondaryRegion'))), bool('false'), bool('true'))]",
        }
      ],
      "databaseAccountOfferType": "Standard",
      "enableAutomaticFailover": "[parameters('automaticFailover')]"
    }
  }
]

penyedia

Fungsi providers tidak digunakan lagi dalam templat ARM. Kami tidak lagi merekomendasikan menggunakannya. Jika Anda menggunakan fungsi ini untuk mendapatkan versi API untuk penyedia sumber daya, kami sarankan Anda memberikan versi API tertentu di template Anda. Menggunakan versi API yang dikembalikan secara dinamis dapat merusak templat Anda jika properti berubah antar versi.

Dalam Bicep, fungsi providers tidak digunakan lagi.

[providers Operasi](/rest/api/resources/providers) masih tersedia melalui REST API. Ini dapat digunakan di luar templat ARM untuk mendapatkan informasi tentang penyedia sumber daya.

referensi

Dalam templat tanpa nama simbolis:

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

Dalam templat dengan nama simbolis:

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

Mengembalikan objek yang mewakili status runtime bahasa umum sumber daya. Output dan perilaku reference fungsi sangat bergantung pada bagaimana setiap penyedia sumber daya (RP) mengimplementasikan respons PUT dan GET-nya. Untuk mengembalikan array objek yang mewakili status runtime kumpulan sumber daya, lihat referensi.

Bicep menyediakan fungsi reference, tetapi dalam kebanyakan kasus, fungsi tidak diperlukan. Sebagai gantinya, gunakan nama simbolis untuk sumber daya. Lihat reference untuk informasi lebih lanjut.

Parameter

Pengaturan Wajib Tipe Deskripsi
resourceName/resourceIdentifier atau symbolicName/resourceIdentifier Ya string Dalam templat tanpa nama simbolis, tentukan nama atau pengidentifikasi unik sumber daya. Saat mereferensikan sumber daya di templat saat ini, hanya berikan nama sumber daya sebagai parameter. Saat merujuk sumber daya yang disebarkan sebelumnya atau ketika nama sumber daya ambigu, berikan ID sumber daya.
Dalam templat dengan nama simbolis, tentukan nama simbolis atau pengidentifikasi unik sumber daya. Saat mereferensikan sumber daya dalam templat saat ini, berikan hanya nama simbolis sumber daya sebagai parameter. Saat mereferensikan sumber daya yang disebarkan sebelumnya, berikan ID sumber daya.
apiVersi Tidak. string Versi API dari sumber daya yang ditentukan. Parameter ini diperlukan saat sumber daya tidak tersedia dalam templat yang sama. Biasanya, dalam format, yyyy-mm-dd. Untuk versi API yang valid untuk sumber daya Anda, lihat referensi template.
'Penuh' Tidak. string Nilai yang menentukan apakah akan mengembalikan objek sumber daya lengkap. Jika Anda tidak menentukan 'Full', hanya objek properti sumber daya yang dikembalikan. Objek lengkap menyertakan nilai seperti ID sumber daya dan lokasi.

Nilai hasil

Setiap jenis sumber daya mengembalikan properti yang berbeda untuk fungsi tersebut reference . Fungsi ini tidak mengembalikan format tunggal, format yang sudah ditentukan sebelumnya. Selain itu, nilai yang dikembalikan berbeda berdasarkan nilai argumen 'Full'. Untuk melihat properti untuk jenis sumber daya, kembalikan objek di bagian output seperti yang diperlihatkan dalam contoh.

Keterangan

Fungsi ini reference mengambil status runtime sumber daya yang disebarkan sebelumnya atau sumber daya yang disebarkan dalam templat saat ini. Artikel ini memperlihatkan contoh untuk kedua skenario.

Biasanya, Anda menggunakan fungsi reference untuk menampilkan nilai tertentu dari objek, seperti URI titik akhir blob atau nama domain yang sepenuhnya memenuhi syarat.

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

Gunakan 'Full' saat Anda memerlukan nilai sumber daya yang bukan bagian dari skema properti. Misalnya, untuk mengatur kebijakan akses brankas kunci, dapatkan properti identitas untuk mesin virtual.

{
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2025-05-01",
  "name": "vaultName",
  "properties": {
    "tenantId": "[subscription().tenantId]",
    "accessPolicies": [
      {
        "tenantId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.tenantId]",
        "objectId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.principalId]",
        "permissions": {
          "keys": [
            "all"
          ],
          "secrets": [
            "all"
          ]
        }
      }
    ],
    ...

Penggunaan yang valid

Fungsi reference hanya dapat digunakan di bagian output templat atau penyebaran dan objek properti definisi sumber daya. Ini tidak dapat digunakan untuk properti sumber daya seperti type, , namelocation, atau properti tingkat atas lainnya dari definisi sumber daya. Saat digunakan dengan properti perulangan, Anda dapat menggunakan fungsi reference untuk input karena ekspresi ditetapkan ke properti sumber daya.

Anda tidak dapat menggunakan fungsi reference untuk mengatur nilai properti count dalam sebuah perulangan salinan. Anda dapat menggunakannya untuk mengatur properti lain dalam loop. Referensi diblokir untuk properti hitungan karena properti tersebut harus ditentukan sebelum fungsi reference diselesaikan.

Untuk menggunakan fungsi reference atau fungsi list* apapun di bagian output templat berlapis, Anda harus mengatur expressionEvaluationOptions untuk menggunakan evaluasi cakupan dalam atau menggunakan ditautkan alih-alih templat berlapis.

Jika Anda menggunakan reference fungsi dalam sumber daya yang disebarkan secara kondisional, fungsi dievaluasi meskipun sumber daya tidak disebarkan. Anda mendapatkan kesalahan jika fungsi reference merujuk ke sumber daya yang tidak ada. Gunakan fungsi if untuk memastikan fungsi hanya dievaluasi saat sumber daya sedang disebarkan. if Lihat fungsi untuk templat sampel yang menggunakan if dan reference dengan sumber daya yang disebarkan secara kondisional.

Dependensi implisit

Dengan menggunakan fungsi reference, Anda secara implisit menyatakan bahwa satu sumber daya bergantung pada sumber daya lain jika sumber daya yang direferensikan tersedia dalam templat yang sama dan Anda merujuk ke sumber daya dengan namanya (bukan ID sumber daya). Anda juga tidak perlu menggunakan properti dependsOn. Fungsi tersebut tidak dievaluasi sampai sumber daya yang direferensikan telah menyelesaikan penyebaran.

Nama sumber daya, Nama simbolis, atau pengidentifikasi

Saat mereferensikan sumber daya yang disebarkan dalam templat nama tidak ada simbolis yang sama, berikan nama sumber daya.

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

Saat mereferensikan sumber daya yang disebarkan dalam templat nama simbolis yang sama, berikan nama simbolis sumber daya.

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

Atau

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

Saat mereferensikan sumber daya yang tidak disebarkan dalam templat yang sama, berikan ID sumber daya dan apiVersion.

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

Untuk menghindari ambiguitas tentang sumber daya mana yang Anda referensikan, Anda dapat menyediakan pengidentifikasi sumber daya yang sepenuhnya memenuhi syarat.

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

Saat membangun referensi yang sepenuhnya memenuhi syarat untuk sumber daya, urutkan untuk menggabungkan segmen dari jenis dan nama bukan hanya perangkaian keduanya. Sebagai gantinya, setelah namespace layanan, gunakan urutan pasangan jenis/nama dari yang paling tidak spesifik hingga yang paling spesifik:

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

Contohnya:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt benar Microsoft.Compute/virtualMachines/extensions/myVM/myExt tidak benar

Untuk menyederhanakan pembuatan ID sumber daya apa pun, gunakan resourceId() fungsi yang dideskripsikan dalam dokumen ini sebagai ganti dari concat() fungsi.

Mendapatkan identitas terkelola

identitas Managed untuk sumber daya Azure adalah jenis sumber daya ekstensi yang dibuat secara implisit untuk beberapa sumber daya. Karena identitas terkelola tidak secara eksplisit ditentukan dalam templat, Anda harus mereferensikan sumber daya yang identitasnya diterapkan. Gunakan Full untuk mendapatkan semua properti, termasuk identitas yang dibuat secara implisit.

Polanya adalah:

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

Misalnya, untuk mendapatkan ID utama untuk identitas terkelola yang diterapkan ke komputer virtual, gunakan:

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

Atau, untuk mendapatkan ID penyewa untuk identitas terkelola yang diterapkan ke set skala komputer virtual, gunakan:

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

Contoh referensi

Contoh berikut menyebarkan sumber daya dan mereferensikannya:

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

Contoh sebelumnya mengembalikan dua objek. Objek propertinya dalam format berikut:

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

Objek lengkapnya dalam format berikut:

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

Contoh templat berikut mereferensikan akun penyimpanan yang tidak disebarkan dalam templat ini. Akun penyimpanan sudah ada dalam langganan yang sama:

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

referensi

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

Fungsi ini references berfungsi sama seperti reference. Alih-alih mengembalikan objek yang menyajikan status runtime sumber daya, references fungsi mengembalikan array objek yang mewakili status runtime kumpulan sumber daya. Fungsi ini memerlukan versi 2.0 bahasa templat ARM dan dengan nama simbolis diaktifkan:

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

Dalam Bicep, tidak ada fungsi references eksplisit. Sebagai gantinya, penggunaan koleksi simbolis digunakan secara langsung, dan selama pembuatan kode, Bicep menerjemahkannya ke templat ARM yang menggunakan templat ARM references fungsi. Untuk informasi selengkapnya, lihat Mereferensikan kumpulan sumber daya/modul.

Parameter

Pengaturan Wajib Tipe Deskripsi
Nama simbolis kumpulan sumber daya Ya string Nama simbolis kumpulan sumber daya yang ditentukan dalam templat saat ini. Fungsi references ini tidak mendukung referensi sumber daya di luar templat saat ini.
'Penuh', 'Properti' Tidak. string Nilai yang menentukan apakah akan mengembalikan array objek sumber daya lengkap. Nilai defaultnya adalah 'Properties'. Jika Anda tidak menentukan 'Full', hanya objek properti sumber daya yang dikembalikan. Objek lengkap menyertakan nilai seperti ID sumber daya dan lokasi.

Nilai hasil

Array koleksi sumber daya. Setiap jenis sumber daya mengembalikan properti yang berbeda untuk fungsi tersebut reference . Selain itu, nilai yang dikembalikan berbeda berdasarkan nilai argumen 'Full'. Untuk informasi selengkapnya, lihat referensi.

Urutan references output selalu diatur dalam urutan naik berdasarkan indeks salin. Oleh karena itu, sumber daya pertama dalam koleksi dengan indeks 0 ditampilkan terlebih dahulu, diikuti oleh indeks 1, dan sebagainya. Misalnya, [worker-0, worker-1, worker-2, ...].

Dalam contoh sebelumnya, jika worker-0 dan worker-2 disebarkan sementara worker-1 bukan karena kondisi palsu, output references akan menghilangkan sumber daya yang tidak terdeployed dan menampilkan yang disebarkan, yang diurutkan berdasarkan angkanya. Output akan references menjadi [worker-0, worker-2, ...]. Jika semua sumber daya dihilangkan, fungsi mengembalikan array kosong.

Penggunaan yang valid

Fungsi references tidak dapat digunakan dalam perulangan salinan resource atau Bicep untuk perulangan. Misalnya, references tidak diizinkan dalam skenario berikut:

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

Untuk menggunakan fungsi references atau fungsi list* apapun di bagian output templat berlapis, Anda harus mengatur expressionEvaluationOptions untuk menggunakan evaluasi cakupan dalam atau menggunakan ditautkan alih-alih templat berlapis.

Dependensi implisit

Dengan menggunakan fungsi , references Anda secara implisit menyatakan bahwa satu sumber daya bergantung pada sumber daya lain. Anda juga tidak perlu menggunakan properti dependsOn. Fungsi tersebut tidak dievaluasi sampai sumber daya yang direferensikan telah menyelesaikan penyebaran.

Contoh referensi

Contoh berikut menyebarkan kumpulan sumber daya dan referensi yang dikumpulkan sumber daya:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "numWorkers": {
      "type": "int",
      "defaultValue": 4,
      "metadata": {
        "description": "The number of workers"
      }
    }
  },
  "resources": {
    "containerWorkers": {
      "copy": {
        "name": "containerWorkers",
        "count": "[length(range(0, parameters('numWorkers')))]"
      },
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2025-09-01",
      "name": "[format('worker-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
      "location": "[parameters('location')]",
      "properties": {
        "containers": [
          {
            "name": "[format('worker-container-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
            "properties": {
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1,
                  "memoryInGB": 2
                }
              }
            }
          }
        ],
        "osType": "Linux",
        "restartPolicy": "Always",
        "ipAddress": {
          "type": "Public",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ]
        }
      }
    },
    "containerController": {
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2025-09-01",
      "name": "controller",
      "location": "[parameters('location')]",
      "properties": {
        "containers": [
          {
            "name": "controller-container",
            "properties": {
              "command": [
                "echo",
                "[format('Worker IPs are {0}', join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ','))]"
              ],
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1,
                  "memoryInGB": 2
                }
              }
            }
          }
        ],
        "osType": "Linux",
        "restartPolicy": "Always",
        "ipAddress": {
          "type": "Public",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ]
        }
      },
      "dependsOn": [
        "containerWorkers"
      ]
    }
  },
  "outputs": {
    "workerIpAddresses": {
      "type": "string",
      "value": "[join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ',')]"
    },
    "containersFull": {
      "type": "array",
      "value": "[references('containerWorkers', 'full')]"
    },
    "container": {
      "type": "array",
      "value": "[references('containerWorkers')]"
    }
  }
}

Contoh sebelumnya mengembalikan tiga objek.

"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

Lihat fungsinya resourceGroup scope .

Di Bicep, gunakan fungsi resourceGroup scope.

ID sumber daya

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

Mengembalikan pengidentifikasi unik sumber daya. Anda menggunakan fungsi ini ketika nama sumber daya ambigu atau tidak tersedia dalam templat yang sama. Format pengidentifikasi yang dikembalikan bervariasi berdasarkan apakah penyebaran terjadi pada cakupan grup sumber daya, langganan, grup manajemen, atau penyewa.

Di Bicep, gunakan fungsi resourceId.

Parameter

Pengaturan Wajib Tipe Deskripsi
ID langganan Tidak. string (Dalam format GUID) Nilai default adalah langganan saat ini. Tentukan nilai ini saat Anda perlu mengambil sumber daya di langganan lain. Hanya berikan nilai ini saat menyebarkan cakupan grup sumber daya atau langganan.
resourceGroupName Tidak. string Nilai default adalah grup sumber daya saat ini. Tentukan nilai ini saat Anda perlu mengambil sumber daya di grup sumber daya lain. Hanya berikan nilai ini saat menyebarkan di cakupan grup sumber daya.
tipe sumber daya Ya string Jenis sumber daya termasuk namespace layanan penyedia sumber.
resourceName1 Ya string Nama sumber daya.
resourceName2 Tidak. string Segmen nama sumber daya berikutnya, jika diperlukan.

Terus tambahkan nama sumber daya sebagai parameter ketika jenis sumber daya menyertakan lebih banyak segmen.

Nilai hasil

ID sumber daya dikembalikan dalam format yang berbeda pada cakupan yang berbeda:

  • Cakupan grup sumber daya:

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

  • Cakupan langganan:

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

  • Cakupan grup manajemen atau penyewa:

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

Untuk menghindari kebingungan, jangan gunakan resourceId saat bekerja dengan sumber daya yang disebarkan ke langganan, grup manajemen, atau penyewa. Sebagai gantinya ...Id , gunakan fungsi yang dirancang untuk cakupan.

Keterangan

Jumlah parameter yang Anda berikan bervariasi berdasarkan apakah sumber daya adalah sumber daya induk atau anak dan jika sumber daya berada dalam grup langganan atau sumber daya yang sama.

Untuk mendapatkan ID sumber daya untuk sumber daya induk dalam langganan dan grup sumber daya yang sama, berikan jenis dan nama sumber daya.

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

Untuk mendapatkan ID sumber daya untuk sumber daya turunan, perhatikan jumlah segmen dalam jenis sumber daya. Berikan nama sumber daya untuk setiap segmen jenis sumber daya. Nama segmen sesuai dengan sumber daya yang ada untuk bagian hierarki tersebut.

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

Untuk mendapatkan ID sumber daya untuk sumber daya dalam langganan yang sama namun dalam grup sumber daya yang berbeda, berikan nama grup sumber daya.

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

Untuk mendapatkan ID sumber daya untuk sumber daya di langganan dan grup sumber daya yang berbeda, berikan ID langganan dan nama grup sumber daya.

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

Seringkali, Anda perlu menggunakan fungsi ini saat menggunakan akun penyimpanan atau jaringan virtual dalam grup sumber daya alternatif. Contoh berikut menunjukkan cara menggunakan sumber daya dari grup sumber daya eksternal:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string"
    },
    "virtualNetworkName": {
      "type": "string"
    },
    "virtualNetworkResourceGroup": {
      "type": "string"
    },
    "subnet1Name": {
      "type": "string"
    },
    "nicName": {
      "type": "string"
    }
  },
  "variables": {
    "subnet1Ref": "[resourceId(parameters('virtualNetworkResourceGroup'), 'Microsoft.Network/virtualNetworks/subnets', parameters('virtualNetworkName'), parameters('subnet1Name'))]"
  },
  "resources": [
    {
      "type": "Microsoft.Network/networkInterfaces",
      "apiVersion": "2025-01-01",
      "name": "[parameters('nicName')]",
      "location": "[parameters('location')]",
      "properties": {
        "ipConfigurations": [
          {
            "name": "ipconfig1",
            "properties": {
              "privateIPAllocationMethod": "Dynamic",
              "subnet": {
                "id": "[variables('subnet1Ref')]"
              }
            }
          }
        ]
      }
    }
  ]
}

Contoh ID sumber daya

Contoh berikut mengembalikan ID sumber daya untuk akun penyimpanan di grup sumber daya:

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

Output nilai default dari contoh sebelumnya adalah:

Nama Tipe Nilai
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 string /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeee4e4e4e4e/resourceGroups/otherResourceGroup/providers/Microsoft. Storage/storageAccounts/examplestorage
nestedResourceOutput string /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft. SQL/servers/serverName/databases/databaseName

roleDefinitions

roleDefinisions(roleName)

Mengembalikan informasi tentang definisi peran yang ditentukan, termasuk id dan roleDefinitionId. Ini adalah pembantu berbasis nama untuk penetapan peran RBAC Azure. Alih-alih mengharuskan Anda untuk hardcode GUID definisi peran bawaan (seperti Kontributor, Pembaca, dan lainnya), ini memungkinkan Anda memberikan nama tampilan peran bawaan, dan fungsi menyelesaikan informasi definisi peran yang sesuai pada waktu penyebaran.

Dalam Bicep, gunakan fungsi roleDefinitions.

Parameter

Pengaturan Wajib Tipe Deskripsi
roleName Ya string Nama tampilan definisi peran.

Nilai hasil

Objek yang mewakili definisi peran, termasuk id dan roleDefinitionId.

Examples

Templat ARM berikut membuat penetapan peran RBAC Azure deterministik yang memberikan prinsipal tertentu Storage Blob Data Reader peran bawaan pada cakupan penyebaran dengan menyelesaikan definisi peran berdasarkan nama pada waktu penyebaran.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "roleDefinitionName": {
      "type": "string",
      "defaultValue": "Storage Blob Data Reader",
      "metadata": {
        "description": "Specifies the role definition ID used in the role assignment."
      }
    },
    "principalId": {
      "type": "string",
      "metadata": {
        "description": "Specifies the principal ID assigned to the role."
      }
    }
  },
  "variables": {
    "roleAssignmentName": "[guid(parameters('principalId'), parameters('roleDefinitionName'), resourceGroup().id)]"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2022-04-01",
      "name": "[variables('roleAssignmentName')]",
      "properties": {
        "roleDefinitionId": "[roleDefinitions(parameters('roleDefinitionName')).id]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

Untuk informasi selengkapnya, lihat fungsi roleDefinition Bicep.

langganan

subscription Lihat fungsi cakupan untuk informasi selengkapnya.

Di Bicep, gunakan cakupan subscription.

subscriptionResourceId

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

Mengembalikan pengidentifikasi unik untuk sumber daya yang disebarkan di tingkat langganan.

Di Bicep, gunakan fungsi subscriptionResourceId.

Parameter

Pengaturan Wajib Tipe Deskripsi
ID langganan Tidak. string (dalam format GUID) Nilai default adalah langganan saat ini. Tentukan nilai ini saat Anda perlu mengambil sumber daya di langganan lain.
tipe sumber daya Ya string Jenis sumber daya termasuk namespace layanan penyedia sumber.
resourceName1 Ya string Nama sumber daya.
resourceName2 Tidak. string Segmen nama sumber daya berikutnya, jika diperlukan.

Terus tambahkan nama sumber daya sebagai parameter ketika jenis sumber daya menyertakan lebih banyak segmen.

Nilai hasil

Pengidentifikasi dikembalikan dalam format berikut:

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

Keterangan

Anda gunakan fungsi ini untuk mendapatkan ID sumber daya untuk sumber daya yang disebarkan ke langganan daripada grup sumber daya. ID yang dikembalikan berbeda dari nilai yang dikembalikan oleh resourceId fungsi karena tidak mengembalikan nilai grup sumber daya.

Contoh subscriptionResourceID

Templat berikut menetapkan peran bawaan. Anda dapat menyebarkannya ke grup sumber daya atau langganan. Ini menggunakan subscriptionResourceId fungsi untuk mendapatkan ID sumber daya untuk peran bawaan:

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

Mengembalikan pengidentifikasi unik untuk sumber daya yang disebarkan di tingkat grup manajemen.

Di Bicep, gunakan fungsi managementGroupResourceId.

Parameter

Pengaturan Wajib Tipe Deskripsi
managementGroupResourceId Tidak. string (dalam format GUID) Nilai default adalah grup manajemen saat ini. Tentukan nilai ini saat Anda perlu mengambil sumber daya di grup manajemen lain.
tipe sumber daya Ya string Jenis sumber daya termasuk namespace layanan penyedia sumber.
resourceName1 Ya string Nama sumber daya.
resourceName2 Tidak. string Segmen nama sumber daya berikutnya, jika diperlukan.

Terus tambahkan nama sumber daya sebagai parameter ketika jenis sumber daya menyertakan lebih banyak segmen.

Nilai hasil

Pengidentifikasi dikembalikan dalam format berikut:

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

Keterangan

Anda menggunakan fungsi ini untuk mendapatkan ID sumber daya untuk sumber daya yang disebarkan ke grup manajemen, bukan grup sumber daya. ID yang dikembalikan berbeda dari nilai yang dikembalikan oleh resourceId fungsi karena tidak menyertakan ID langganan atau nilai grup sumber daya.

contoh managementGroupResourceID

Templat berikut membuat dan menetapkan definisi kebijakan. Ini menggunakan fungsi managementGroupResourceId untuk mendapatkan ID sumber daya untuk definisi kebijakan.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "targetMG": {
      "type": "string",
      "metadata": {
        "description": "Target Management Group"
      }
    },
    "allowedLocations": {
      "type": "array",
      "defaultValue": [
        "australiaeast",
        "australiasoutheast",
        "australiacentral"
      ],
      "metadata": {
        "description": "An array of the allowed locations, all other locations will be denied by the created policy."
      }
    }
  },
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2025-03-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    "location_lock": {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2025-03-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

tenantResourceId

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

Mengembalikan pengidentifikasi unik untuk sumber daya yang disebarkan di tingkat penyewa.

Di Bicep, gunakan fungsi tenantResourceId.

Parameter

Pengaturan Wajib Tipe Deskripsi
tipe sumber daya Ya string Jenis sumber daya termasuk namespace layanan penyedia sumber.
resourceName1 Ya string Nama sumber daya.
resourceName2 Tidak. string Segmen nama sumber daya berikutnya, jika diperlukan.

Terus tambahkan nama sumber daya sebagai parameter ketika jenis sumber daya menyertakan lebih banyak segmen.

Nilai hasil

Pengidentifikasi dikembalikan dalam format berikut:

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

Keterangan

Anda menggunakan fungsi ini untuk mendapatkan ID sumber daya untuk sumber daya yang disebarkan ke penyewa. ID yang dikembalikan berbeda dari nilai yang dikembalikan oleh fungsi ID sumber daya lainnya dengan tidak menyertakan grup sumber daya atau nilai langganan.

Contoh tenantResourceId

Definisi kebijakan bawaan adalah sumber daya tingkat penyewa. Untuk menyebarkan penetapan kebijakan yang mereferensikan definisi kebijakan bawaan, gunakan tenantResourceId fungsi :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "policyDefinitionID": {
      "type": "string",
      "defaultValue": "0a914e76-4921-4c19-b460-a2d36003525a",
      "metadata": {
        "description": "Specifies the ID of the policy definition or policy set definition being assigned."
      }
    },
    "policyAssignmentName": {
      "type": "string",
      "defaultValue": "[guid(parameters('policyDefinitionID'), resourceGroup().name)]",
      "metadata": {
        "description": "Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "name": "[parameters('policyAssignmentName')]",
      "apiVersion": "2025-03-01",
      "properties": {
        "scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
        "policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
      }
    }
  ]
}

Langkah berikutnya

  • Last updated on