Funções de âmbito para Bicep

  • Artigo

Este artigo descreve as funções bicep para obter valores de âmbito.

managementGroup

managementGroup()

Devolve um objeto com propriedades do grupo de gestão na implementação atual.

managementGroup(identifier)

Devolve um objeto utilizado para definir o âmbito para um grupo de gestão.

Espaço de nomes: az.

Observações

managementGroup() só pode ser utilizado em implementações de grupos de gestão. Devolve o grupo de gestão atual para a operação de implementação. Utilize quando obter um objeto de âmbito ou obter propriedades para o grupo de gestão atual.

managementGroup(identifier) pode ser utilizado para qualquer âmbito de implementação, mas apenas para obter o objeto de âmbito. Para obter as propriedades de um grupo de gestão, não pode transmitir o identificador do grupo de gestão.

Parâmetros

Parâmetro Necessário Tipo Description
identificador No string O identificador exclusivo para o grupo de gestão para o qual implementar. Não utilize o nome a apresentar para o grupo de gestão. Se não fornecer um valor, é devolvido o grupo de gestão atual.

Valor devolvido

Um objeto utilizado para definir a scope propriedade num módulo ou tipo de recurso de extensão. Em alternativa, um objeto com as propriedades do grupo de gestão atual.

Exemplo de grupo de gestão

O exemplo seguinte define o âmbito de um módulo para um grupo de gestão.

param managementGroupIdentifier string

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

O exemplo seguinte devolve propriedades para o grupo de gestão 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 exemplo seguinte cria um novo grupo de gestão e utiliza esta função para definir o grupo de gestão principal.

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

Devolve um objeto que representa o grupo de recursos atual.

resourceGroup(resourceGroupName)

E

resourceGroup(subscriptionId, resourceGroupName)

Devolver um objeto utilizado para definir o âmbito para um grupo de recursos.

Espaço de nomes: az.

Observações

A função resourceGroup tem duas utilizações distintas. Uma utilização é para definir o âmbito num módulo ou tipo de recurso de extensão. A outra utilização é para obter detalhes sobre o grupo de recursos atual. O posicionamento da função determina a respetiva utilização. Quando utilizado para definir a scope propriedade, devolve um objeto de âmbito.

resourceGroup() pode ser utilizado para definir o âmbito ou obter detalhes sobre o grupo de recursos.

resourceGroup(resourceGroupName) e resourceGroup(subscriptionId, resourceGroupName) só podem ser utilizados para definir o âmbito.

Parâmetros

Parâmetro Necessário Tipo Description
resourceGroupName No string O nome do grupo de recursos no qual implementar. Se não fornecer um valor, é devolvido o grupo de recursos atual.
subscriptionId No string O identificador exclusivo para a subscrição a implementar. Se não fornecer um valor, a subscrição atual é devolvida.

Valor devolvido

Quando utilizada para definir o âmbito, a função devolve um objeto válido para a scope propriedade num módulo ou tipo de recurso de extensão.

Quando utilizada para obter detalhes sobre o grupo de recursos, a função devolve 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 é devolvida apenas para grupos de recursos que contêm recursos que são geridos por outro serviço. Para Aplicações Geridas, Databricks e AKS, o valor da propriedade é o ID de recurso do recurso de gestão.

Exemplo de grupo de recursos

O exemplo seguinte define o âmbito de um módulo para um grupo de recursos.

param resourceGroupName string

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

O exemplo seguinte devolve as propriedades do grupo de recursos.

output resourceGroupOutput object = resourceGroup()

Devolve um objeto no seguinte formato:

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

Uma utilização comum da função resourceGroup é criar recursos na mesma localização que o grupo de recursos. O exemplo seguinte utiliza a localização do grupo de recursos para um valor de parâmetro predefinido.

param location string = resourceGroup().location

Também pode utilizar a função resourceGroup para aplicar etiquetas do grupo de recursos a um recurso. Para obter mais informações, veja Aplicar etiquetas do grupo de recursos.

subscrição

subscription()

Devolve detalhes sobre a subscrição da implementação atual.

subscription(subscriptionId)

Devolve um objeto utilizado para definir o âmbito para uma subscrição.

Espaço de nomes: az.

Observações

A função de subscrição tem duas utilizações distintas. Uma utilização é para definir o âmbito num módulo ou tipo de recurso de extensão. A outra utilização é para obter detalhes sobre a subscrição atual. O posicionamento da função determina a respetiva utilização. Quando utilizado para definir a scope propriedade, devolve um objeto de âmbito.

subscription(subscriptionId) só pode ser utilizado para definir o âmbito.

subscription() pode ser utilizado para definir o âmbito ou obter detalhes sobre a subscrição.

Parâmetros

Parâmetro Necessário Tipo Description
subscriptionId No string O identificador exclusivo para a subscrição a implementar. Se não fornecer um valor, a subscrição atual é devolvida.

Valor devolvido

Quando utilizada para definir o âmbito, a função devolve um objeto válido para a scope propriedade num módulo ou tipo de recurso de extensão.

Quando utilizada para obter detalhes sobre a subscrição, a função devolve o seguinte formato:

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

Exemplo de subscrição

O exemplo seguinte define o âmbito de um módulo para a subscrição.

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

O exemplo seguinte devolve os detalhes de uma subscrição.

output subscriptionOutput object = subscription()

inquilino

tenant()

Devolve um objeto utilizado para definir o âmbito para o inquilino.

Ou

Devolve o inquilino do utilizador.

Espaço de nomes: az.

Observações

tenant() pode ser utilizado com qualquer âmbito de implementação. Devolve sempre o inquilino atual. Pode utilizar esta função para definir o âmbito de um recurso ou para obter propriedades para o inquilino atual.

Valor devolvido

Um objeto utilizado para definir a scope propriedade num módulo ou tipo de recurso de extensão. Em alternativa, um objeto com propriedades sobre o inquilino atual.

Exemplo de inquilino

O exemplo seguinte mostra um módulo implementado no inquilino.

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

O exemplo seguinte devolve as propriedades de um inquilino.

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 requerem a definição do ID de inquilino de uma propriedade. Em vez de transmitir o ID do inquilino como um parâmetro, pode obtê-lo com a função de inquilino.

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

Passos seguintes

Para saber mais sobre os âmbitos de implementação, veja: