Partilhar via

Funções de escopo para Bicep

  • Artigo

Este artigo descreve as funções do Bíceps para obter valores de escopo.

gestãoGrupo

managementGroup()

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

managementGroup(identifier)

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

Espaço de nomes: az.

Observações

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.

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, não é possível passar o identificador do grupo de gerenciamento.

Parâmetros

Parâmetro Necessário Type Description
identificador Não string O identificador exclusivo para o grupo de gerenciamento a ser implantado. Não use o nome para exibição do grupo de gerenciamento. Se você não fornecer um valor, o grupo de gerenciamento atual será retornado.

Valor devolvido

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

Exemplo de grupo de gerenciamento

O exemplo a seguir define o escopo de um módulo como 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

É devolvido:

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

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)

And

resourceGroup(subscriptionId, resourceGroupName)

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

Espaço de nomes: az.

Observações

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. A colocação da função determina o seu uso. Quando usado para definir a scope propriedade, ele 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

Parâmetro Necessário Type Description
resourceGroupName Não string O nome do grupo de recursos para implantar. Se você não fornecer um valor, o grupo de recursos atual será retornado.
subscriptionId Não string O identificador exclusivo da assinatura a ser implantada. Se você não fornecer um valor, a assinatura atual será retornada.

Valor devolvido

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

Quando usada 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 do recurso de gerenciamento.

Exemplo de grupo de recursos

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

param resourceGroupName string

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

O próximo exemplo 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 tags do grupo de recursos a um recurso. Para obter mais informações, consulte Aplicar tags do grupo de recursos.

subscrição

subscription()

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

subscription(subscriptionId)

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

Espaço de nomes: az.

Observações

A função de subscrição tem duas utilizações distintas. 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. A colocação da função determina o seu uso. Quando usado para definir a scope propriedade, ele 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

Parâmetro Necessário Type Description
subscriptionId Não string O identificador exclusivo da assinatura a ser implantada. Se você não fornecer um valor, a assinatura atual será retornada.

Valor devolvido

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

Quando usada 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 subscrição

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

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

O próximo exemplo retorna os detalhes de uma assinatura.

output subscriptionOutput object = subscription()

inquilino

tenant()

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

Ou

Retorna o locatário do usuário.

Espaço de nomes: az.

Observações

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 para obter propriedades para o locatário atual.

Valor devolvido

Um objeto usado para definir a scope propriedade 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 implantado para o 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

É devolvido:

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

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

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

Próximos passos

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