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
| Parâmetro | Obrigatório | Type | Descrição |
|---|---|---|---|
| identificador | Não | string | O identificador exclusivo para o grupo de gerenciamento a ser implantado. Não use o nome de exibição para o grupo de gerenciamento. Se você não fornecer um valor, o grupo de gerenciamento atual será retornado. |
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
| Parâmetro | Obrigatório | Type | Descrição |
|---|---|---|---|
| resourceGroupName | Não | string | O nome do grupo de recursos para o qual implantar. Se você não fornecer um valor, o grupo de recursos atual será retornado. |
| subscriptionId | Não | string | O identificador exclusivo para o qual a assinatura implantar a assinatura. Se você não fornecer um valor, a assinatura atual será retornada. |
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
| Parâmetro | Obrigatório | Type | Descrição |
|---|---|---|---|
| subscriptionId | Não | string | O identificador exclusivo para o qual a assinatura implantar a assinatura. Se você não fornecer um valor, a assinatura atual será retornada. |
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: