ARM 範本的資源函數

Resource Manager 提供下列函數,以在 AZURE Resource Manager 範本中取得資源值 (ARM 範本) :

若要從參數、變數或目前的部署取得值,請參閱 部署值函數

若要取得部署範圍值,請參閱 範圍函數

extensionResourceId

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

會返回擴充資源 的資源識別碼。 擴充資源是一種資源類型,會用於另一個資源,以新增到其功能。

參數

參數 必填 類型 描述
baseResourceId 是的 字串 延伸資源所適用之資源的資源識別碼。
resourceType 是的 字串 擴展資源的類型,包括資源提供者命名空間。
resourceName1 是的 字串 擴充資源的名稱。
resourceName2 字串 下一個資源名稱區段 ,如果需要的話。

當資源類型包含更多區段時,繼續新增資源名稱做為參數。

Return 值

此函數所返回的資源識別碼基本格式為:

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

範圍區段會依據要延伸的基礎資源而不同。 例如,訂閱的識別碼的區段與資源群組的識別碼不同。

將擴充資源當做為資源 ,會以下列格式返回資源識別碼:

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

當擴充資源適用于資源群組 時,所返回的格式為:

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

下一節顯示使用此函數與資源群組的範例。

當擴充資源適用于訂閱 ,所返回的格式為:

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

當擴充資源適用于管理 群組時,所返回的格式為:

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

下一節顯示使用此函數與管理群組的範例。

extensionResourceId 範例

下列範例會返回資源組鎖定的資源識別碼。

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

部署至管理群組的自訂策略定義會以擴充資源方式實現。 若要建立和指派策略,請部署下列範本至管理群組。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.4.1.14562",
      "templateHash": "2350252618174097128"
    }
  },
  "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."
      }
    }
  },
  "functions": [],
  "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": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

內建的策略定義是租使用者層級資源。 有關部署內建策略定義的範例,請參閱 tenantResourceId

清單*

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

此函數的語法會依清單作業的名稱而不同。 每個實現會針對支援清單作業的資源類型,會傳回值。 作業名稱必須以為起點, list 而且可能具有尾碼。 一些常見的用法有 listlistKeyslistKeyValuelistSecrets

參數

參數 必填 類型 描述
resourceName 或 resourceIdentifier 是的 字串 資源的唯一識別碼。
apiVersion 是的 字串 資源執行時間狀態 API 版本。 一般來說,格式為 yyyy-mm-dd
functionValues 物件 具有函數值的物件。 僅針對支援接收具有參數值的物件的函數提供此物件,例如儲存 listAccountSas 空間帳戶。 本文顯示傳遞函數值的範例。

有效的使用

清單函數可用於資源定義的屬性。 請勿使用清單函數來公開範本輸出區段的敏感性資訊。 輸出值會儲存在部署歷程記錄中,而且可能會由惡意使用者所取取。

當與 屬性反覆運算一起使用時,您可以使用 清單函數,因為 運算式會指派給資源屬性。 由於必須先決定計數,清單函數才能解決,因此無法 count 使用它們。

實現

可能的用途 list* 如下表所示。

資源類型 函數名稱
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.自動化/自動化Accounts listKeys
Microsoft.Batch/batchAccounts 清單鍵
Microsoft.BatchAI/workspaces/實驗/jobs listoutputfiles
Microsoft.Blockchain/4000000 listApiKeys
Microsoft.隊員/分項/transactionNodes listApiKeys
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/datafactory/gateways listauthkeys
Microsoft.DataFactory/工廠/integrationruntimes listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokens
Microsoft.DataShare/accounts/share listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions listSourceShareSynchronizationSettings
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizationDetails
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizations
Microsoft.Devices/iotHubs 清單鍵
Microsoft.Devices/iotHubs/iotHubKeys 清單鍵
Microsoft.Devices/provisioningServices/keys 清單鍵
Microsoft.Devices/provisioningServices 清單鍵
Microsoft.DevTestLab/labs ListVhds
Microsoft.DevTestLab/labs/schedules ListAppable
Microsoft.DevTestLab/labs/users/serviceFabrics ListAppableSchedules
Microsoft.DevTestLab/labs/virtualMachines ListAppableSchedules
Microsoft.DocumentDB/databaseAccounts listConnectionStrings
Microsoft.DocumentDB/databaseAccounts listKeys
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces listConnectionInfo
Microsoft.DomainRegistration listDomainRecommendations
Microsoft.DomainRegistration/topLevelDomains listAgreements
Microsoft.EventGrid/domains listKeys
Microsoft.EventGrid/topics listKeys
Microsoft.EventHub/命名空間/授權規則 清單鍵
Microsoft.EventHub/命名空間/disasterRecoveryConfigs/authorizationRules 清單鍵
Microsoft.EventHub/命名空間/eventhubs/authorizationRules 清單鍵
Microsoft.ImportExport/jobs listBitLockerKeys
Microsoft.Kusto/Clusters/Databases ListPrincipals
Microsoft.LabServices/users ListEnvironments
Microsoft.LabServices/users ListLabs
Microsoft.Logic/integrationAccounts/agreements listContentCallbackUrl
Microsoft.Logic/integrationAccounts/程式集 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/工作流程 listCallbackUrl
Microsoft.Logic/工作流程 listSwagger
Microsoft.Logic/工作流程/執行/動作 listExpressionTraces
Microsoft.Logic/工作流程/執行/動作/重複 listExpressionTraces
Microsoft.Logic/workflows/triggers listCallbackUrl
Microsoft.Logic/workflows/versions/triggers listCallbackUrl
Microsoft.MachineLearning/webServices 清單鍵
Microsoft.MachineLearning/Workspaces listworkspacekeys
Microsoft.MachineLearningServices/workspaces/computes listKeys
Microsoft.MachineLearningServices/workspaces/computes listNodes
Microsoft.MachineLearningServices/workspaces listKeys
微軟。地圖/帳戶 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/命名空間/授權規則 清單鍵
Microsoft.NotificationHubs/命名空間/NotificationHubs/authorizationRules 清單鍵
Microsoft.OperationalInsights/workspaces 清單
Microsoft.OperationalInsights/workspaces listKeys
Microsoft.PolicyInsights/remediations listDeployments
Microsoft.RedHatOpenShift/openShiftClusters listCredentials
Microsoft.Relay/命名空間/授權規則 清單鍵
Microsoft.Relay/命名空間/disasterRecoveryConfigs/authorizationRules 清單鍵
Microsoft.Relay/命名空間/HybridConnections/authorizationRules 清單鍵
Microsoft.Relay/命名空間/WcfRelays/authorizationRules 清單鍵
Microsoft.Search/searchServices listAdminKeys
Microsoft.Search/searchServices listQueryKeys
Microsoft.ServiceBus/命名空間/授權規則 清單鍵
Microsoft.ServiceBus/命名空間/disasterRecoveryConfigs/authorizationRules 清單鍵
Microsoft.ServiceBus/命名空間/佇列/授權規則 清單鍵
Microsoft.ServiceBus/命名空間/主題/授權規則 清單鍵
Microsoft.SignalRService/SignalR 清單鍵
微軟。儲存體/storageAccounts listAccountSas
微軟。儲存體/storageAccounts 清單鍵
微軟。儲存體/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 清單
Microsoft.Web/sites/config 清單
microsoft.web/sites/functions 清單鍵
microsoft.web/sites/functions listSecrets
microsoft.web/sites/hybridconnectionnamespaces/relays 清單鍵
microsoft.web/sites listsyncfunctiontriggerstatus
microsoft.web/sites/slots/functions listSecrets
microsoft.web/sites/slots/backups 清單
Microsoft.Web/sites/slots/config 清單
microsoft.web/sites/slots/functions listSecrets

若要判斷哪些資源類型具有清單作業,您具有下列選項:

  • 查看 資源提供者的 REST API 作業,並尋找清單作業。 例如,儲存空間帳戶有 listKeys 運算

  • 使用 Get-AzProviderOperation PowerShell Cmdlet。 下列範例會針對儲存空間帳戶執行所有清單作業:

    Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
    
  • 使用下列 Azure CLI 命令只篩選清單作業:

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

Return 值

返回的物件會依據 list 您使用的函數而不同。 例如, listKeys 儲存空間帳戶的 會返回下列格式:

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

其他 list 函數具有不同的退貨格式。 若要查看函數的格式,請如範例範本所示,將函數納入輸出區段。

言論

使用資源名稱或 resourceId 函數來指定資源。 在部署參照資源的同一個範本中使用函數時, list 請使用資源名稱。

如果您在條件式部署的資源中使用函數,即使尚未部署資源,系統也一樣會評估 list 函數。 如果函數參照了不存在的資源 list ,您收到錯誤。 使用 if 函數來確認只有在資源部署時,才評估函數。 查看 使用且 具有條件式部署資源之範例範本的 if list 函數。

清單範例

下列範例用於 listKeys 設定部署腳本 listKeys

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

下一個範例顯示 list 採用參數的函數。 在此案例中,函數為 listAccountSas 。 將物件傳遞為到期時間。 到期日必須在未來。

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

決定資源類型是否支援指定位置或區域的區域。 此函數 僅支援分區資源。 區域重複服務會返回空白陣列。 詳細資訊,請參閱 支援可用性區的 Azure Services

參數

參數 必填 類型 描述
providerNamespace 是的 字串 資源類型的資源提供者命名空間,以檢查區域支援。
resourceType 是的 字串 要檢查區域支援的資源類型。
位置 是的 字串 要檢查區域支援的區域。
numberOfZones 整數 要返回的邏輯區域數目。 預設值為 1。 數位必須是 1 到 3 的正整數。 針對單一區域資源使用 1。 對於多區域資源,該值必須小於或等於支援的區域數目。
抵消 整數 起始邏輯區域中的位移。 如果 offset 加上 numberOfZones 超過支援區域的數量,函數會返回錯誤。

Return 值

包含支援區域之陣列。 使用 offset 和 的預設值 numberOfZones 時,支援區域的資源類型和區域會返回下列陣列:

[
    "1"
]

參數 numberOfZones 設為 3 時,會返回:

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

當資源類型或區域不支援區域時,會返回空白陣列。 區域冗余服務也會返回空白陣列。

[
]

言論

Azure 可用性區域有不同類別 -分區和區域-冗余。 pickZones此函數可用來返回分區資源的可用性區域。 針對 ZRS (區域) ,函數會返回空白陣列。 分區資源通常會在資源定義的頂層 zones 有一個屬性。 若要判斷可用性區域的支援類別,請參閱支援可用性區的 Azure Services

若要判斷指定 Azure 區域或位置是否支援可用性區域,請撥打分區資源類型的函數,例如 pickZonesMicrosoft.Network/publicIPAddresses 。 如果回應不是空白,則區域支援可用性區域。

pickZones 範例

下列範本顯示使用函數的三個 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')]"
    }
  }
}

上述範例的輸出會返回三個數組。

名字 類型 價值
支援 陣 列 [ "1" ]
notSupportedRegion 陣 列 []
notSupportedType 陣 列 []

您可以使用回應來判斷是否要為區域提供 Null,或將虛擬機器 pickZones 指派給不同的區域。 下列範例會根據區域的可用性,為區域設定值。

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

下列範例顯示如何使用函數為 DB 啟用區域 pickZones Cosmos。

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

供應商

提供者函數已被棄用。 我們不再建議您使用它。 如果您使用此函數取得資源提供者的 API 版本,建議您在範本中提供特定的 API 版本。 如果屬性在版本之間變更,使用動態返回的 API 版本可能會中斷您的範本。

參考

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

會返回代表資源執行時間狀態的物件。

參數

參數 必填 類型 描述
resourceName 或 resourceIdentifier 是的 字串 資源的名稱或唯一識別碼。 參照目前範本中的資源時,請只提供資源名稱做為參數。 參照先前部署的資源或資源名稱不明確時,請提供資源識別碼。
apiVersion 字串 指定資源的 API 版本。 當資源未在同一個範本中設定時,必須使用此參數。 一般來說,格式為 yyyy-mm-dd。 有關資源的有效 API 版本,請參閱 範本參照
'完整' 字串 指定是否要返回完整資源物件的值。 如果您未指定,只會 'Full' 返回資源的屬性物件。 完整物件包含資源識別碼和位置等值。

Return 值

每個資源類型都會為參照函數返回不同的屬性。 函數不會返回單一預先定義的格式。 此外,根據引數的值,所返回 'Full' 的值也會有所不同。 若要查看資源類型的屬性,請如範例所示,在輸出區段返回物件。

言論

參照函數會取回先前部署的資源或目前範本中部署的資源的執行時間狀態。 本文將說明這兩種案例的範例。

一般來說,您可以使用函數從物件 ,例如 Blob 端點 URI 或完整功能變數名稱,來 reference 返回特定值。

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

當您 'Full' 需要的資源值不是屬性架構的一部分時,請使用。 例如,若要設定金鑰庫存取策略,請取得虛擬機器的身分識別屬性。

{
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2019-09-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"
          ]
        }
      }
    ],
    ...

有效的使用

函數只能用於資源定義的屬性,以及範本或部署的輸出 reference 區段。 當用於 屬性反覆運算時,您可以使用 函數,因為 input 運算式會指派給資源屬性。

在複製迴圈中,您無法使用此函數來 referencecount 設定屬性的值。 您可以在迴圈中設定其他屬性。 count 屬性的參照會封鎖,因為必須先決定該屬性,才能 reference 解析函數。

若要在巢式範本的輸出區段使用函數或任何函數,您必須設定為使用內部範圍評估,或使用 referencelist* 連結而非 expressionEvaluationOptions 巢式範本。 reference

如果您在條件式部署的資源中使用該函數,即使尚未部署資源,系統也一樣會評估 reference 函數。 如果函數參照了不存在的資源 reference ,您收到錯誤。 使用 if 函數來確認只有在資源部署時,才評估函數。 查看 使用且 具有條件式部署資源之範例範本的 if reference 函數。

隱含相依性

使用函數時,如果參照的資源是在同一個範本中置備,而您參照的是資源名稱,而不是資源識別碼 (隱含宣告另一個資源取決於另一個 reference) 。 您也不需要使用 dependsOn 屬性。 在參照的資源完成部署之前,不會評估函數。

資源名稱或識別碼

參照部署在同一個範本中的資源時,請提供資源的名稱。

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

參照未部署在同一個範本中的資源時,請提供資源識別碼和 apiVersion

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

為了避免您參照的資源不明確,您可以提供完全合格的資源識別碼。

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

當建構資源完全限定參照時,從類型和名稱合併區段的順序並不只是兩者之間的串聯。 而是在命名空間之後,使用從最不特定到最特定之類型 / 名稱對的順序:

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

例如:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt 正確 Microsoft.Compute/virtualMachines/extensions/myVM/myExt 不正確

若要簡化任何資源識別碼的建立,請使用本檔所述的函數 resourceId() ,而不是 concat() 函數。

取得受管理身分識別

Azure 資源的受管理身分標識隱含 為某些資源所建立擴充資源類型。 由於範本中未明確定義受管理身分識別,因此您必須參照該身分識別所適用于的資源。 用於 Full 取得所有屬性,包括隱含建立身分識別。

模式為:

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

例如,若要取得適用于虛擬機器的受管理身分識別的主要識別碼,請使用:

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

或者,若要取得套用至虛擬機器縮放集的受管理身分識別的租使用者識別碼,請使用:

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

參照範例

下列範例會部署資源,並參照該資源。

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

上一個範例會返回這兩個物件。 屬性物件的格式如下:

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

完整物件的格式如下:

{
  "apiVersion":"2021-04-01",
  "location":"southcentralus",
  "sku": {
    "name":"Standard_LRS",
    "tier":"Standard"
  },
  "tags":{},
  "kind":"Storage",
  "properties": {
    "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
  },
  "subscriptionId":"<subscription-id>",
  "resourceGroupName":"functionexamplegroup",
  "resourceId":"Microsoft.Storage/storageAccounts/examplestorage",
  "referenceApiVersion":"2021-04-01",
  "condition":true,
  "isConditionTrue":true,
  "isTemplateResource":false,
  "isAction":false,
  "provisioningOperation":"Read"
}

下列範例範本參照未部署在此範本中的儲存空間帳戶。 儲存空間帳戶已存在在同一個訂閱中。

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

resourceGroup

請參閱 resourceGroup 範圍函數

resourceId

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

會返回資源的唯一識別碼。 當資源名稱不明確或未在同一個範本中置備時,您可以使用此函數。 根據部署是否發生在資源群組、訂閱、管理群組或租使用者範圍內,所返回識別碼的格式會有所不同。

參數

參數 必填 類型 描述
subscriptionId 字串 (GUID 格式) 預設值為目前的訂閱。 當您需要在另一個訂閱中取回資源時,請指定此值。 只有在資源組或訂閱範圍內部署時,才能提供此值。
resourceGroupName 字串 預設值為目前的資源群組。 當您需要從另一個資源群組中取回資源時,請指定此值。 只有在資源組範圍內部署時,才能提供此值。
resourceType 是的 字串 資源類型,包括資源提供者命名空間。
resourceName1 是的 字串 資源名稱。
resourceName2 字串 下一個資源名稱區段 ,如果需要的話。

當資源類型包含更多區段時,繼續新增資源名稱做為參數。

Return 值

在資源組範圍內部署範本時,會以下列格式返回資源識別碼:

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

您可以在其他 resourceId 部署範圍使用函數,但識別碼的格式會變更。

如果您在部署 resourceId 至訂閱時使用,資源識別碼會以下列格式返回:

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

如果您在部署至管理群組或租使用者時使用, resourceId 資源識別碼會以下列格式返回:

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

為了避免混淆,建議您在使用部署至訂閱、管理群組或租使用者的資源時 resourceId ,不要使用。 請改為使用專為範圍設計的識別碼函數。

針對 訂閱層級資源,請使用 subscriptionResourceId 函數。

針對 管理群組層級資源,請使用 extensionResourceId 函數來參照已作為管理群組擴充功能所實現的資源。 例如,部署至管理群組的自訂策略定義是管理群組的擴充功能。 使用 tenantResourceId 函數來參照部署至租使用者但管理群組中可用的資源。 例如,內建的策略定義會以租使用者層級資源方式實現。

對於 租使用者層級資源,請使用 tenantResourceId 函數。 用於 tenantResourceId 內建的策略定義,因為它們在租使用者層級上已實現。

言論

您提供的參數數目會依據資源是父資源或子資源,以及資源是否位於相同的訂閱或資源群組中而不同。

若要在同一個訂閱和資源群組中取得父資源的資源識別碼,請提供資源的類型和名稱。

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

若要取得子資源的資源識別碼,請注意資源類型中的區段數目。 為資源類型的每個區段提供資源名稱。 區段名稱會對應至階層中該部分存在的資源。

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

若要取得相同訂閱中但不同資源群組中資源的資源識別碼,請提供資源組名稱。

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

若要取得不同訂閱和資源群組中資源的資源識別碼,請提供訂閱識別碼和資源組名。

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

當您在替代資源群組中使用儲存空間帳戶或虛擬網路時,通常需要使用此函數。 下列範例顯示外部資源群組中的資源如何輕鬆使用:

{
  "$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": "2021-02-01",
      "name": "[parameters('nicName')]",
      "location": "[parameters('location')]",
      "properties": {
        "ipConfigurations": [
          {
            "name": "ipconfig1",
            "properties": {
              "privateIPAllocationMethod": "Dynamic",
              "subnet": {
                "id": "[variables('subnet1Ref')]"
              }
            }
          }
        ]
      }
    }
  ]
}

資源識別碼範例

下列範例會返回資源群組中儲存帳戶的資源識別碼:

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

上述範例中預設值的輸出為:

名字 類型 價值
sameRGOutput 字串 /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft。儲存體/storageAccounts/examplestorage
differentRGOutput 字串 /subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft。儲存體/storageAccounts/examplestorage
differentSubOutput 字串 /subscriptions/11111111-1111-1111-1111-1111111111/resourceGroups/otherResourceGroup/providers/Microsoft。儲存體/storageAccounts/examplestorage
nestedResourceOutput 字串 /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft。SQL/server/serverName/database/databaseName

訂閱

請參閱 訂閱範圍函數

subscriptionResourceId

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

會針對部署在訂閱層級的資源,返回唯一識別碼。

參數

參數 必填 類型 描述
subscriptionId 字串 (GUID 格式) 預設值為目前的訂閱。 當您需要在另一個訂閱中取回資源時,請指定此值。
resourceType 是的 字串 資源類型,包括資源提供者命名空間。
resourceName1 是的 字串 資源名稱。
resourceName2 字串 下一個資源名稱區段 ,如果需要的話。

當資源類型包含更多區段時,繼續新增資源名稱做為參數。

Return 值

會以下列格式返回識別碼:

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

言論

您可以使用此函數取得部署至訂閱的資源 ,而非資源群組的資源識別碼。 所返回的識別碼與 resourceId 函數所返回的值不同,因為不包括資源組值。

subscriptionResourceID 範例

下列範本會指派內建角色。 您可以將它部署到資源群組或訂閱。 它使用 subscriptionResourceId 函數來取得內建角色的資源識別碼。

{
  "$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": "2020-10-01-preview",
      "name": "[parameters('roleNameGuid')]",
      "properties": {
        "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

tenantResourceId

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

會針對部署在租使用者層級的資源,返回唯一識別碼。

參數

參數 必填 類型 描述
resourceType 是的 字串 資源類型,包括資源提供者命名空間。
resourceName1 是的 字串 資源名稱。
resourceName2 字串 下一個資源名稱區段 ,如果需要的話。

當資源類型包含更多區段時,繼續新增資源名稱做為參數。

Return 值

會以下列格式返回識別碼:

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

言論

您可以使用此函數取得部署至租使用者之資源的資源識別碼。 所退回的識別碼與由其他資源識別碼函數所返回的值不同,因為不包括資源群組或訂閱值。

tenantResourceId 範例

內建的策略定義是租使用者層級資源。 若要部署參照內建策略定義的策略指派,請使用 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": "2020-09-01",
      "properties": {
        "scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
        "policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
      }
    }
  ]
}

下一個步驟

  • 有關 ARM 範本中各節的描述,請參閱瞭解 ARM 範本的結構 和語法
  • 若要合併多個範本,請參閱部署 Azure 資源時使用連結範本 和巢式範本
  • 若要在建立資源類型時反覆運算指定次數,請參閱 ARM 範本 中的資源反覆運算
  • 若要瞭解如何部署您建立範本,請參閱使用 ARM 範本部署資源及Azure PowerShell。