Fungsi sumber daya untuk templat ARM
Resource Manager menyediakan fungsi berikut untuk mendapatkan nilai sumber daya di templat Azure Resource Manager (templat ARM):
- extensionResourceId
- list*
- pickZones
- penyedia (tidak digunakan lagi)
- referensi
- Referensi
- resourceId
- subscriptionResourceId
- managementGroupResourceId
- tenantResourceId
Untuk mendapatkan nilai dari parameter, variabel, atau penyebaran saat ini, lihat Fungsi nilai penyebaran.
Untuk mendapatkan nilai cakupan penyebaran, lihat Fungsi cakupan.
Tip
Kami merekomendasikan Bicep karena menawarkan kemampuan yang sama dengan templat ARM dan sintaksnya lebih mudah digunakan. Untuk mempelajari selengkapnya, lihat fungsi sumber daya.
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.
Pada Bicep, gunakan fungsi extensionResourceId.
Parameter
Parameter | Wajib | Tipe | Deskripsi |
---|---|---|---|
baseResourceId | Ya | string | ID sumber daya untuk sumber daya yang sumber daya ekstensinya diterapkan. |
resourceType | Ya | string | Jenis sumber daya ekstensi termasuk namespace penyedia sumber daya. |
resourceName1 | Ya | string | Nama sumber daya ekstensi. |
resourceName2 | No | 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 boleh memiliki akhiran. Beberapa penggunaan umum adalah list
, listKeys
, listKeyValue
, dan listSecrets
.
Pada Bicep, gunakan fungsi list*.
Parameter
Parameter | Wajib | Tipe | Deskripsi |
---|---|---|---|
resourceName atau resourceIdentifier | Ya | string | Pengidentifikasi unik untuk sumber daya. |
apiVersion | Ya | string | Versi API dari status runtime bahasa umum sumber daya. Biasanya, dalam format, yyyy-mm-dd. |
functionValues | No | object | 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/workspaces/experiments/jobs | listoutputfiles |
Microsoft.BotService/botServices/channels | listChannelWithKeys |
Microsoft.Cache/redis | listKeys |
Microsoft.CognitiveServices/accounts | listKeys |
Microsoft.ContainerRegistry/registries | listCredentials |
Microsoft.ContainerRegistry/registries | listUsages |
Microsoft.ContainerRegistry/registries/agentpools | listQueueStatus |
Microsoft.ContainerRegistry/registries/buildTasks | listSourceRepositoryProperties |
Microsoft.ContainerRegistry/registries/buildTasks/steps | listBuildArguments |
Microsoft.ContainerRegistry/registries/taskruns | listDetails |
Microsoft.ContainerRegistry/registries/webhooks | listEvents |
Microsoft.ContainerRegistry/registries/runs | listLogSasUrl |
Microsoft.ContainerRegistry/registries/tasks | listDetails |
Microsoft.ContainerService/managedClusters | listClusterAdminCredential |
Microsoft.ContainerService/managedClusters | listClusterMonitoringUserCredential |
Microsoft.ContainerService/managedClusters | listClusterUserCredential |
Microsoft.ContainerService/managedClusters/accessProfiles | listCredential |
Microsoft.DataBox/jobs | listCredentials |
Microsoft.DataFactory/datafactories/gateways | listauthkeys |
Microsoft.DataFactory/factories/integrationruntimes | listauthkeys |
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers | listSasTokens |
Microsoft.DataShare/accounts/shares | listSynchronizations |
Microsoft.DataShare/accounts/shareSubscriptions | listSourceShareSynchronizationSettings |
Microsoft.DataShare/accounts/shareSubscriptions | listSynchronizationDetails |
Microsoft.DataShare/accounts/shareSubscriptions | listSynchronizations |
Microsoft.Devices/iotHubs | listKeys |
Microsoft.Devices/iotHubs/iotHubKeys | listKeys |
Microsoft.Devices/provisioningServices/keys | listKeys |
Microsoft.Devices/provisioningServices | listKeys |
Microsoft.DevTestLab/labs | ListVhds |
Microsoft.DevTestLab/labs/schedules | ListApplicable |
Microsoft.DevTestLab/labs/users/serviceFabrics | ListApplicableSchedules |
Microsoft.DevTestLab/labs/virtualMachines | ListApplicableSchedules |
Microsoft.DocumentDB/databaseAccounts | listKeys |
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces | listConnectionInfo |
Microsoft.DomainRegistration/topLevelDomains | listAgreements |
Microsoft.EventHub/namespaces/authorizationRules | listKeys |
Microsoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRules | listKeys |
Microsoft.EventHub/namespaces/eventhubs/authorizationRules | listKeys |
Microsoft.ImportExport/jobs | listBitLockerKeys |
Microsoft.Kusto/Clusters/Databases | ListPrincipals |
Microsoft.LabServices/labs/users | daftar |
Microsoft.LabServices/labs/virtualMachines | daftar |
Microsoft.Logic/integrationAccounts/agreements | listContentCallbackUrl |
Microsoft.Logic/integrationAccounts/assemblies | listContentCallbackUrl |
Microsoft.Logic/integrationAccounts | listCallbackUrl |
Microsoft.Logic/integrationAccounts | listKeyVaultKeys |
Microsoft.Logic/integrationAccounts/maps | listContentCallbackUrl |
Microsoft.Logic/integrationAccounts/partners | listContentCallbackUrl |
Microsoft.Logic/integrationAccounts/schemas | listContentCallbackUrl |
Microsoft.Logic/workflows | listCallbackUrl |
Microsoft.Logic/workflows | listSwagger |
Microsoft.Logic/workflows/runs/actions | listExpressionTraces |
Microsoft.Logic/workflows/runs/actions/repetitions | listExpressionTraces |
Microsoft.Logic/workflows/triggers | listCallbackUrl |
Microsoft.Logic/workflows/versions/triggers | listCallbackUrl |
Microsoft.MachineLearning/webServices | listkeys |
Microsoft.MachineLearning/Workspaces | listworkspacekeys |
Microsoft.Maps/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/workspaces | daftar |
Microsoft.OperationalInsights/workspaces | listKeys |
Microsoft.PolicyInsights/remediations | listDeployments |
Microsoft.RedHatOpenShift/openShiftClusters | listCredentials |
Microsoft.Relay/namespaces/authorizationRules | listKeys |
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules | listKeys |
Microsoft.Relay/namespaces/HybridConnections/authorizationRules | listKeys |
Microsoft.Relay/namespaces/WcfRelays/authorizationRules | listkeys |
Microsoft.Search/searchServices | listAdminKeys |
Microsoft.Search/searchServices | listQueryKeys |
Microsoft.ServiceBus/namespaces/authorizationRules | listKeys |
Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules | listKeys |
Microsoft.ServiceBus/namespaces/queues/authorizationRules | listKeys |
Microsoft.SignalRService/SignalR | listKeys |
Microsoft.Storage/storageAccounts | listAccountSas |
Microsoft.Storage/storageAccounts | listKeys |
Microsoft.Storage/storageAccounts | listServiceSas |
Microsoft.StorSimple/managers/devices | listFailoverSets |
Microsoft.StorSimple/managers/devices | listFailoverTargets |
Microsoft.StorSimple/managers | listActivationKey |
Microsoft.StorSimple/managers | listPublicEncryptionKey |
Microsoft.Synapse/workspaces/integrationRuntimes | listAuthKeys |
Microsoft.Web/connectionGateways | ListStatus |
microsoft.web/connections | listconsentlinks |
Microsoft.Web/customApis | listWsdlInterfaces |
microsoft.web/locations | listwsdlinterfaces |
microsoft.web/apimanagementaccounts/apis/connections | listconnectionkeys |
microsoft.web/apimanagementaccounts/apis/connections | listSecrets |
microsoft.web/sites/backups | 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-AzProviderOperation. 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 ini 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 fungsi resourceId. Saat menggunakan fungsi list
dalam templat yang sama yang menyebarkan sumber daya yang direferensikan, gunakan nama sumber daya.
Jika Anda menggunakan ungsi list
di sumber daya yang disebarkan secara kondisional, fungsi tersebut 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. Lihat fungsi if 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 Azure Services yang mendukung Zona Ketersediaan.
Pada Bicep, gunakan fungsi pickZones.
Parameter
Parameter | Wajib | Tipe | Deskripsi |
---|---|---|---|
providerNamespace | Ya | string | Namespace layanan penyedia sumber untuk jenis sumber daya untuk memeriksa dukungan zona. |
resourceType | Ya | string | Jenis sumber daya untuk memeriksa dukungan zona. |
lokasi | Ya | string | Wilayah untuk memeriksa dukungan zona. |
numberOfZones | No | 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 | No | 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 beberapa kategori yang berbeda untuk Azure Availability Zones - zonal dan zona-berlebih. 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, gunakan fungsi pickZones
dengan jenis sumber daya dalam zona, misalnya Microsoft.Network/publicIPAddresses
. Jika respons tidak kosong, maka wilayah tersebut mendukung zona ketersediaan.
Contoh pickZones
Templat berikut ini menunjukkan tiga hasil saat menggunakan fungsi pickZones
.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {},
"functions": [],
"variables": {},
"resources": [],
"outputs": {
"supported": {
"type": "array",
"value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')]"
},
"notSupportedRegion": {
"type": "array",
"value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'westus')]"
},
"notSupportedType": {
"type": "array",
"value": "[pickZones('Microsoft.Cdn', 'profiles', 'westus2')]"
}
}
}
Output dari contoh sebelumnya mengembalikan tiga array.
Nama | Jenis | Nilai |
---|---|---|
didukung | array | [ "1" ] |
notSupportedRegion | array | [] |
notSupportedType | array | [] |
Anda dapat menggunakan respons dari pickZones
untuk menentukan apakah akan menyediakan null untuk zona atau menetapkan mesin virtual ke zona yang berbeda. Contoh berikut mengatur 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 pickZones
fungsi untuk menentukan apakah akan mengaktifkan redundansi zona untuk georeplikasi. Berikan jenis sumber daya Microsoft.Storage/storageAccounts untuk menentukan apakah akan mengaktifkan redundansi zona.
"resources": [
{
"type": "Microsoft.DocumentDB/databaseAccounts",
"apiVersion": "2021-04-15",
"name": "[variables('accountName_var')]",
"location": "[parameters('location')]",
"kind": "GlobalDocumentDB",
"properties": {
"consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
"locations": [
{
"locationName": "[parameters('primaryRegion')]",
"failoverPriority": 0,
"isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('primaryRegion'))), bool('false'), bool('true'))]",
},
{
"locationName": "[parameters('secondaryRegion')]",
"failoverPriority": 1,
"isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('secondaryRegion'))), bool('false'), bool('true'))]",
}
],
"databaseAccountOfferType": "Standard",
"enableAutomaticFailover": "[parameters('automaticFailover')]"
}
}
]
penyedia
Fungsi penyedia tidak digunakan lagi di 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.
Pada Bicep, fungsi penyedia tidak digunakan lagi.
Operasi penyedia 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 referensi, tetapi dalam kebanyakan kasus, fungsi referensi tidak diperlukan. Disarankan untuk menggunakan nama simbolis untuk sumber daya sebagai gantinya. Lihat referensi.
Parameter
Parameter | 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. |
apiVersion | No | 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. |
'Full' | No | 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 referensi. 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 referensi mengambil status runtime bahasa umum sumber daya yang sebelumnya disebarkan 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": "2022-07-01",
"name": "vaultName",
"properties": {
"tenantId": "[subscription().tenantId]",
"accessPolicies": [
{
"tenantId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.tenantId]",
"objectId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.principalId]",
"permissions": {
"keys": [
"all"
],
"secrets": [
"all"
]
}
}
],
...
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
, name
, location
dan 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 fungsi reference
di sumber daya yang disebarkan secara kondisional, maka fungsi tersebut 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. Lihat fungsi if 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 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
adalah benar Microsoft.Compute/virtualMachines/extensions/myVM/myExt
adalah 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 terkelola 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 mesin virtual, gunakan:
"[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')),'2019-12-01', 'Full').identity.principalId]",
Misalnya, untuk mendapatkan ID utama untuk identitas terkelola yang diterapkan ke mesin virtual, gunakan:
"[reference(resourceId('Microsoft.Compute/virtualMachineScaleSets', variables('vmNodeType0Name')), 2019-12-01, 'Full').Identity.tenantId]"
Contoh referensi
Contoh berikut menyebarkan sumber daya, dan mereferensikan sumber daya tersebut.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"storageAccountName": {
"type": "string"
},
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]"
}
},
"resources": [
{
"type": "Microsoft.Storage/storageAccounts",
"apiVersion": "2022-09-01",
"name": "[parameters('storageAccountName')]",
"location": "[parameters('location')]",
"sku": {
"name": "Standard_LRS"
},
"kind": "Storage",
"tags": {},
"properties": {
}
}
],
"outputs": {
"referenceOutput": {
"type": "object",
"value": "[reference(parameters('storageAccountName'))]"
},
"fullReferenceOutput": {
"type": "object",
"value": "[reference(parameters('storageAccountName'), '2022-09-01', 'Full')]"
}
}
}
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",
...
}
Di Bicep, tidak ada fungsi eksplisit references
. Sebagai gantinya, penggunaan koleksi simbolis digunakan secara langsung, dan selama pembuatan kode, Bicep menerjemahkannya ke templat ARM yang menggunakan fungsi templat references
ARM. Untuk informasi selengkapnya, lihat Mereferensikan kumpulan sumber daya/modul.
Parameter
Parameter | 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 eksternal ke templat saat ini. |
'Penuh', 'Properti' | No | 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 disebarkan 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 sumber daya 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 mereferensikan kumpulan sumber daya tersebut.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"languageVersion": "2.0",
"contentVersion": "1.0.0.0",
"parameters": {
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]",
"metadata": {
"description": "Location for all resources."
}
},
"numWorkers": {
"type": "int",
"defaultValue": 4,
"metadata": {
"description": "The number of workers"
}
}
},
"resources": {
"containerWorkers": {
"copy": {
"name": "containerWorkers",
"count": "[length(range(0, parameters('numWorkers')))]"
},
"type": "Microsoft.ContainerInstance/containerGroups",
"apiVersion": "2023-05-01",
"name": "[format('worker-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
"location": "[parameters('location')]",
"properties": {
"containers": [
{
"name": "[format('worker-container-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
"properties": {
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
],
"resources": {
"requests": {
"cpu": 1,
"memoryInGB": 2
}
}
}
}
],
"osType": "Linux",
"restartPolicy": "Always",
"ipAddress": {
"type": "Public",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
]
}
}
},
"containerController": {
"type": "Microsoft.ContainerInstance/containerGroups",
"apiVersion": "2023-05-01",
"name": "controller",
"location": "[parameters('location')]",
"properties": {
"containers": [
{
"name": "controller-container",
"properties": {
"command": [
"echo",
"[format('Worker IPs are {0}', join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ','))]"
],
"image": "mcr.microsoft.com/azuredocs/aci-helloworld",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
],
"resources": {
"requests": {
"cpu": 1,
"memoryInGB": 2
}
}
}
}
],
"osType": "Linux",
"restartPolicy": "Always",
"ipAddress": {
"type": "Public",
"ports": [
{
"port": 80,
"protocol": "TCP"
}
]
}
},
"dependsOn": [
"containerWorkers"
]
}
},
"outputs": {
"workerIpAddresses": {
"type": "string",
"value": "[join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ',')]"
},
"containersFull": {
"type": "array",
"value": "[references('containerWorkers', 'full')]"
},
"container": {
"type": "array",
"value": "[references('containerWorkers')]"
}
}
}
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 fungsi cakupan resourceGroup.
Pada Bicep, gunakan fungsi cakupan resourcegroup.
resourceId
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 di cakupan grup sumber daya, langganan, grup manajemen, atau penyewa.
Pada Bicep, gunakan fungsi resourceId.
Parameter
Parameter | Wajib | Tipe | Deskripsi |
---|---|---|---|
subscriptionId | No | 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 | No | 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. |
resourceType | Ya | string | Jenis sumber daya termasuk namespace layanan penyedia sumber. |
resourceName1 | Ya | string | Nama sumber daya. |
resourceName2 | No | 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, kami merekomendasikan agar Anda tidak menggunakan resourceId
saat berkerja dengan penyebaran sumber daya ke langganan, grup manajemen, atau penyewa. Sebagai gantinya, gunakan fungsi ID yang didesain untuk cakupan.
- Untuk sumber daya tingkat langganan, gunakan fungsi subscriptionResourceId.
- Untuk sumber daya tingkat grup manajemen, gunakan fungsi managementGroupResourceId. Gunakan fungsi extensionResourceId untuk mereferensikan sumber daya yang diterapkan sebagai ekstensi grup manajemen. Misalnya, definisi kebijakan kustom yang disebarkan ke grup manajemen adalah ekstensi dari grup manajemen. Gunakan fungsi tenantResourceId untuk mereferensikan sumber daya yang disebarkan ke penyewa tetapi tersedia di grup manajemen Anda. Misalnya, definisi kebijakan bawaan diimplementasikan sebagai sumber daya tingkat penyewa.
- Untuk sumber daya tingkat penyewa, gunakan fungsi tenantResourceId. Gunakan
tenantResourceId
untuk definisi kebijakan bawaan karena definisi tersebut diimplementasikan di tingkat penyewa.
Keterangan
Jumlah parameter yang Anda berikan bervariasi berdasarkan apakah sumber daya adalah sumber daya induk atau turunan, dan apakah sumber daya berada dalam langganan atau grup 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 bagaimana sumber daya dari grup sumber daya eksternal dapat dengan mudah digunakan:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"location": {
"type": "string"
},
"virtualNetworkName": {
"type": "string"
},
"virtualNetworkResourceGroup": {
"type": "string"
},
"subnet1Name": {
"type": "string"
},
"nicName": {
"type": "string"
}
},
"variables": {
"subnet1Ref": "[resourceId(parameters('virtualNetworkResourceGroup'), 'Microsoft.Network/virtualNetworks/subnets', parameters('virtualNetworkName'), parameters('subnet1Name'))]"
},
"resources": [
{
"type": "Microsoft.Network/networkInterfaces",
"apiVersion": "2022-11-01",
"name": "[parameters('nicName')]",
"location": "[parameters('location')]",
"properties": {
"ipConfigurations": [
{
"name": "ipconfig1",
"properties": {
"privateIPAllocationMethod": "Dynamic",
"subnet": {
"id": "[variables('subnet1Ref')]"
}
}
}
]
}
}
]
}
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 dari contoh sebelumnya dengan nilai default adalah:
Nama | Jenis | 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/11111111-1111-1111-1111-111111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage |
nestedResourceOutput | String | /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName |
langganan
Lihat fungsi cakupan langganan.
Pada Bicep, gunakan fungsi cakupan langganan.
subscriptionResourceId
subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)
Mengembalikan pengidentifikasi unik untuk sumber daya yang disebarkan di tingkat langganan.
Pada Bicep, gunakan fungsi subscriptionResourceId.
Parameter
Parameter | Wajib | Tipe | Deskripsi |
---|---|---|---|
subscriptionId | No | string (dalam format GUID) | Nilai default adalah langganan saat ini. Tentukan nilai ini saat Anda perlu mengambil sumber daya di langganan lain. |
resourceType | Ya | string | Jenis sumber daya termasuk namespace layanan penyedia sumber. |
resourceName1 | Ya | string | Nama sumber daya. |
resourceName2 | No | 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 fungsi resourceId dengan tidak menyertakan nilai grup sumber daya.
Contoh subscriptionResourceID
Templat berikut menetapkan peran bawaan. Anda dapat menyebarkannya ke grup sumber daya atau langganan. Ini menggunakan fungsi subscriptionResourceId
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 digunakan di tingkat grup manajemen.
Di Bicep, gunakan fungsi managementGroups ResourceId.
Parameter
Parameter | Wajib | Tipe | Deskripsi |
---|---|---|---|
managementGroupResourceId | No | string (dalam format GUID) | Nilai default adalah grup manajemen saat ini. Tentukan nilai ini saat Anda perlu mengambil sumber daya di grup manajemen lain. |
resourceType | Ya | string | Jenis sumber daya termasuk namespace layanan penyedia sumber. |
resourceName1 | Ya | string | Nama sumber daya. |
resourceName2 | No | 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 fungsi resourceId dengan tidak menyertakan ID langganan dan 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": "2021-06-01",
"name": "[variables('policyDefinitionName')]",
"properties": {
"policyType": "Custom",
"mode": "All",
"parameters": {},
"policyRule": {
"if": {
"not": {
"field": "location",
"in": "[parameters('allowedLocations')]"
}
},
"then": {
"effect": "deny"
}
}
}
},
"location_lock": {
"type": "Microsoft.Authorization/policyAssignments",
"apiVersion": "2022-06-01",
"name": "location-lock",
"properties": {
"scope": "[variables('mgScope')]",
"policyDefinitionId": "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
},
"dependsOn": [
"[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
]
}
]
}
tenantResourceId
tenantResourceId(resourceType, resourceName1, [resourceName2], ...)
Mengembalikan pengidentifikasi unik untuk sumber daya yang disebarkan di tingkat penyewa.
Pada Bicep, gunakan fungsi tenantResourceId.
Parameter
Parameter | Wajib | Tipe | Deskripsi |
---|---|---|---|
resourceType | Ya | string | Jenis sumber daya termasuk namespace layanan penyedia sumber. |
resourceName1 | Ya | string | Nama sumber daya. |
resourceName2 | No | 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 gunakan 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 fungsi tenantResourceId
.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"policyDefinitionID": {
"type": "string",
"defaultValue": "0a914e76-4921-4c19-b460-a2d36003525a",
"metadata": {
"description": "Specifies the ID of the policy definition or policy set definition being assigned."
}
},
"policyAssignmentName": {
"type": "string",
"defaultValue": "[guid(parameters('policyDefinitionID'), resourceGroup().name)]",
"metadata": {
"description": "Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides."
}
}
},
"resources": [
{
"type": "Microsoft.Authorization/policyAssignments",
"name": "[parameters('policyAssignmentName')]",
"apiVersion": "2022-06-01",
"properties": {
"scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
"policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
}
}
]
}
Langkah berikutnya
- Untuk deskripsi bagian-bagian dalam templat ARM, lihat Memahami struktur dan sintaksis templat ARM.
- Untuk menggabungkan beberapa templat, lihat Menggunakan templat yang ditautkan dan templat berlapis saat menyebarkan sumber daya Azure.
- Untuk mengulang jumlah waktu yang ditentukan saat membuat jenis sumber daya, lihat Perulangan sumber daya di templat ARM.
- Untuk melihat cara menyebarkan templat yang telah Anda buat, lihat Menyebarkan sumber daya dengan templat ARM dan Azure PowerShell.