Bicep 的範圍函式

文章
07/11/2024

本文描述用來取得範圍值的 Bicep 函式。

managementGroup

managementGroup()

傳回具有目前部署管理群組屬性的物件。

managementGroup(identifier)

傳回用於將範圍設為管理群組的物件。

命名空間：az。

備註

managementGroup() 僅可用於管理群組部署。此函式會傳回部署作業的目前管理群組。可用於取得範圍物件，或取得目前管理群組的屬性。

managementGroup(identifier) 可用於任何部署範圍，但僅限取得範圍物件時。為擷取管理群組的屬性，您無法傳送管理群組識別碼。

參數

參數	必要	類型	描述
識別碼	No	string	要部署的管理群組唯一識別碼。請勿使用管理群組的顯示名稱。若未提供值，則會傳回目前的管理群組。

傳回值

用於針對模組或延伸模組資源類型設定 scope 屬性的物件。或為具有目前管理群組屬性的物件。

管理群組範例

下列範例會將模組的範圍設為管理群組。

param managementGroupIdentifier string

module  'mgModule.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupIdentifier)
}

下一個範例會傳回目前管理群組的屬性。

targetScope = 'managementGroup'

var mgInfo = managementGroup()

output mgResult object = mgInfo

傳回的會是：

"mgResult": {
  "type": "Object",
  "value": {
    "id": "/providers/Microsoft.Management/managementGroups/examplemg1",
    "name": "examplemg1",
    "properties": {
      "details": {
        "parent": {
          "displayName": "Tenant Root Group",
          "id": "/providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000000",
          "name": "00000000-0000-0000-0000-000000000000"
        },
        "updatedBy": "00000000-0000-0000-0000-000000000000",
        "updatedTime": "2020-07-23T21:05:52.661306Z",
        "version": "1"
      },
      "displayName": "Example MG 1",
      "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    },
    "type": "/providers/Microsoft.Management/managementGroups"
  }
}

下一個範例會建立新的管理群組，並使用此函式來設定父管理群組。

targetScope = 'managementGroup'

param mgName string = 'mg-${uniqueString(newGuid())}'

resource newMG 'Microsoft.Management/managementGroups@2023-04-01' = {
  scope: tenant()
  name: mgName
  properties: {
    details: {
      parent: {
        id: managementGroup().id
      }
    }
  }
}

output newManagementGroup string = mgName

resourceGroup

resourceGroup()

傳回代表目前資源群組的物件。

resourceGroup(resourceGroupName)

且

resourceGroup(subscriptionId, resourceGroupName)

傳回用於將範圍設為資源群組的物件。

命名空間：az。

備註

resourceGroup 函式有兩種不同的用途。其中一個用途是設定模組或延伸模組資源類型的範圍。另一個用途是取得目前資源群組的詳細資料。函式的位置取決於用途。當用於設定 scope 屬性時，便會傳回範圍物件。

resourceGroup() 可用於設定範圍，或取得資源群組的詳細資料。

resourceGroup(resourceGroupName) 和 resourceGroup(subscriptionId, resourceGroupName) 僅可用於設定範圍。

參數

參數	必要	類型	描述
resourceGroupName	No	string	要部署的資源群組名稱。若未提供值，則會傳回目前的資源群組。
subscriptionId	No	string	要部署的訂用帳戶唯一識別碼。若未提供值，則會傳回目前的訂用帳戶。

傳回值

用於設定範圍時，該函式會針對模組或延伸模組資源類型的 scope 屬性傳回有效的物件。

用於取得資源群組的詳細資料時，該函式傳回下列格式：

{
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}",
  "name": "{resourceGroupName}",
  "type":"Microsoft.Resources/resourceGroups",
  "location": "{resourceGroupLocation}",
  "managedBy": "{identifier-of-managing-resource}",
  "tags": {
  },
  "properties": {
    "provisioningState": "{status}"
  }
}

所含的資源由其他服務管理的資源群組，才會傳回 managedBy 屬性。就受控應用程式、Databricks 和 AKS 而言，該屬性的值將是管理端資源的資源識別碼。

資源群組範例

下列範例將模組的範圍設為資源群組。

param resourceGroupName string

module exampleModule 'rgModule.bicep' = {
  name: 'exampleModule'
  scope: resourceGroup(resourceGroupName)
}

下一個範例會傳回資源群組的屬性。

output resourceGroupOutput object = resourceGroup()

函式以下列格式傳回物件：

{
  "id": "/subscriptions/{subscription-id}/resourceGroups/examplegroup",
  "name": "examplegroup",
  "type":"Microsoft.Resources/resourceGroups",
  "location": "southcentralus",
  "properties": {
    "provisioningState": "Succeeded"
  }
}

resourceGroup 函式的常見用法是在和資源群組相同的位置中建立資源。下列範例會使用資源群組位置作為預設參數值。

param location string = resourceGroup().location

您也可以使用 resourceGroup 函式，將資源群組中的標籤套用至資源。如需詳細資訊，請參閱從資源群組套用標籤。

訂用帳戶

subscription()

傳回目前部署的訂用帳戶詳細資料。

subscription(subscriptionId)

傳回用於將範圍設為訂用帳戶的物件。

命名空間：az。

備註

訂用帳戶函式有兩種不同用途。其中一個用途是設定模組或延伸模組資源類型的範圍。另一個用途是取得目前訂用帳戶的詳細資料。函式的位置取決於用途。當用於設定 scope 屬性時，便會傳回範圍物件。

subscription(subscriptionId) 僅可用於設定範圍。

subscription() 可用於設定範圍，或取得訂用帳戶的詳細資料。

參數

參數	必要	類型	描述
subscriptionId	No	string	要部署的訂用帳戶唯一識別碼。若未提供值，則會傳回目前的訂用帳戶。

傳回值

用於設定範圍時，該函式會針對模組或延伸模組資源類型的 scope 屬性傳回有效的物件。

用於取得訂用帳戶的詳細資料時，該函式傳回下列格式：

{
  "id": "/subscriptions/{subscription-id}",
  "subscriptionId": "{subscription-id}",
  "tenantId": "{tenant-id}",
  "displayName": "{name-of-subscription}"
}

訂用帳戶範例

下列範例將模組的範圍設為訂用帳戶。

module exampleModule 'subModule.bicep' = {
  name: 'deployToSub'
  scope: subscription()
}

下一個範例會傳回訂用帳戶的詳細資料。

output subscriptionOutput object = subscription()

tenant

tenant()

傳回用於將範圍設為租用戶的物件。

傳回使用者的租用戶。

命名空間：az。

備註

tenant() 可搭配任何部署範圍使用。此函式一律傳回目前的租用戶。您可使用此函式來設定資源的範圍，或取得目前租用戶的屬性。

傳回值

用於針對模組或延伸模組資源類型設定 scope 屬性的物件。或者，具有目前租用戶相關屬性的物件。

租用戶範例

下列範例顯示部署至租用戶的模組。

module exampleModule 'tenantModule.bicep' = {
  name: 'deployToTenant'
  scope: tenant()
}

下一個範例會傳回租用戶屬性。

var tenantInfo = tenant()

output tenantResult object = tenantInfo

傳回的會是：

"tenantResult": {
  "type": "Object",
  "value": {
    "countryCode": "US",
    "displayName": "Contoso",
    "id": "/tenants/00000000-0000-0000-0000-000000000000",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
  }
}

某些資源需要設定屬性的租用戶識別碼。您可使用租用戶函式來擷取租用戶識別碼，而不是以參數形式傳遞租用戶識別碼。

resource kv 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: 'examplekeyvault'
  location: 'westus'
  properties: {
    tenantId: tenant().tenantId
    ...
  }
}

下一步

若要深入了解部署範圍，請參閱：

資源群組部署 (部分機器翻譯)
訂用帳戶部署
管理群組部署 (部分機器翻譯)
租用戶部署 (部分機器翻譯)

分享方式：

Bicep 的範圍函式

managementGroup

備註

參數

傳回值

管理群組範例

resourceGroup

備註

參數

傳回值

資源群組範例

訂用帳戶

備註

參數

傳回值

訂用帳戶範例

tenant

備註

傳回值

租用戶範例

下一步

意見反映

更多資源