Funções de escopo para Bicep

Este artigo descreve as funções do Bicep para obter valores de escopo.

managementGroup

managementGroup()

Retorna um objeto com propriedades do grupo de gerenciamento na implantação atual.

managementGroup(identifier)

Retorna um objeto usado para definir o escopo de um grupo de gerenciamento.

Namespace: az.

Comentários

managementGroup() só pode ser usado em implantações de grupo de gerenciamento. Ele retorna o grupo de gerenciamento atual para a operação de implantação. Use ao obter um objeto de escopo ou obter propriedades para o grupo de gerenciamento atual.

O managementGroup(identifier) pode ser usado para qualquer escopo de implantação, mas somente ao obter o objeto de escopo. Para recuperar as propriedades de um grupo de gerenciamento, você não poderá passar o identificador do grupo de gerenciamento.

Parâmetros

Valor retornado

Um objeto usado para definir a propriedade scope em um módulo ou tipo de recurso de extensão. Ou um objeto com as propriedades do grupo de gerenciamento atual.

Exemplo de grupo de gerenciamento

O exemplo a seguir define o escopo de um módulo para um grupo de gerenciamento.

param managementGroupIdentifier string

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

O próximo exemplo retorna propriedades para o grupo de gerenciamento atual.

targetScope = 'managementGroup'

var mgInfo = managementGroup()

output mgResult object = mgInfo

Isso retorna:

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

O próximo exemplo cria um novo grupo de gerenciamento e usa essa função para definir o grupo de gerenciamento pai.

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()

Retorna um objeto que representa o grupo de recursos atual.

resourceGroup(resourceGroupName)

E

resourceGroup(subscriptionId, resourceGroupName)

Retorna um objeto usado para definir o escopo de um grupo de recursos.

Namespace: az.

Comentários

A função resourceGroup tem dois usos distintos. Um uso é para definir o escopo em um módulo ou tipo de recurso de extensão. O outro uso é para obter detalhes sobre o grupo de recursos atual. O posicionamento da função determina o uso dela. Quando usada para definir a propriedade scope, ela retorna um objeto de escopo.

resourceGroup() pode ser usado para definir o escopo ou obter detalhes sobre o grupo de recursos.

resourceGroup(resourceGroupName) e resourceGroup(subscriptionId, resourceGroupName) só pode ser usado para definir o escopo.

Parâmetros

Valor retornado

Quando usado para definir o escopo, a função retorna um objeto que é válido para a propriedade scope em um módulo ou tipo de recurso de extensão.

Quando usado para obter detalhes sobre o grupo de recursos, a função retorna o seguinte formato:

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

A propriedade managedBy é retornada somente para grupos de recursos que contêm recursos gerenciados por outro serviço. Para aplicativos gerenciados, databricks e AKS, o valor da propriedade é a ID de recurso do recurso de gerenciamento.

Exemplo de grupo de recursos

O exemplo a seguir tem como escopo um módulo para um grupo de recursos.

param resourceGroupName string

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

O exemplo a seguir retorna as propriedades do grupo de recursos.

output resourceGroupOutput object = resourceGroup()

Ele retorna um objeto no seguinte formato:

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

Um uso comum da função resourceGroup é criar recursos no mesmo local que o grupo de recursos. O exemplo a seguir usa o local do grupo de recursos para um valor de parâmetro padrão.

param location string = resourceGroup().location

Você também pode usar a função resourceGroup para aplicar marcas do grupo de recursos a um recurso. Para obter mais informações, confira Aplicar marcas do grupo de recursos.

subscription

subscription()

Retorna detalhes sobre a assinatura da implantação atual.

subscription(subscriptionId)

Retorna um objeto usado para definir o escopo de uma assinatura.

Namespace: az.

Comentários

A função de assinatura tem dois usos distintos. Um uso é para definir o escopo em um módulo ou tipo de recurso de extensão. O outro uso é para obter detalhes sobre a assinatura atual. O posicionamento da função determina o uso dela. Quando usada para definir a propriedade scope, ela retorna um objeto de escopo.

subscription(subscriptionId) só pode ser usado para definir o escopo.

subscription() pode ser usado para definir o escopo ou obter detalhes sobre a assinatura.

Parâmetros

Valor retornado

Quando usado para definir o escopo, a função retorna um objeto que é válido para a propriedade scope em um módulo ou tipo de recurso de extensão.

Quando usado para obter detalhes sobre a assinatura, a função retorna o seguinte formato:

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

Exemplo de assinatura

O exemplo a seguir tem como escopo um módulo para a assinatura.

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

O exemplo a seguir retorna os detalhes de uma assinatura.

output subscriptionOutput object = subscription()

locatário

tenant()

Retorna um objeto usado para definir o escopo do locatário.

Ou

Retorna o locatário do usuário.

Namespace: az.

Comentários

tenant() pode ser usado com qualquer escopo de implantação. Ele sempre retorna o locatário atual. Você pode usar essa função para definir o escopo de um recurso ou obter propriedades para o locatário atual.

Valor retornado

Um objeto usado para definir a propriedade scope em um módulo ou tipo de recurso de extensão. Ou um objeto com propriedades sobre o locatário atual.

Exemplo de locatário

O exemplo a seguir mostra um módulo que é implantado no locatário.

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

O próximo exemplo retorna as propriedades de um locatário.

var tenantInfo = tenant()

output tenantResult object = tenantInfo

Isso retorna:

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

Alguns recursos exigem a definição da ID de locatário para uma propriedade. Em vez de passar a ID de locatário como um parâmetro, você poderá recuperá-la com a função de locatário.

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

Próximas etapas

Para saber mais sobre os escopos de implantação, confira:

• Implantações do grupo de recursos
• Implantações da assinatura
• Implantações do grupo de gerenciamento
• Implantações de locatário