Bicep 的範圍函式

  • 發行項

本文描述用來取得範圍值的 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": "00000000-0000-0000-0000-000000000000"
    },
    "type": "/providers/Microsoft.Management/managementGroups"
  }
}

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

targetScope = 'managementGroup'

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

resource newMG 'Microsoft.Management/managementGroups@2020-05-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()

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

Or

傳回使用者的租用戶。

命名空間：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": "00000000-0000-0000-0000-000000000000"
  }
}

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

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

下一步

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