Fungsi sumber daya untuk templat ARM

  • Artikel

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

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 listBuildSourceUploadUrl
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-​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 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 listdi 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.

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