Definir escopo para recursos de extensão no Bicep

Um recurso de extensão é um recurso que modifica outro recurso. Por exemplo, você pode atribuir uma função a um recurso. A atribuição de função é um tipo de recurso de extensão.

Para obter uma lista completa dos tipos de recursos de extensão, consulte os tipos de recursos que estendem os recursos de outros recursos.

Este artigo mostra como definir o escopo de um tipo de recurso de extensão implantado com um arquivo Bicep. Ele descreve a propriedade de escopo que está disponível para recursos de extensão ao ser aplicada a um recurso.

Aplicar no escopo da implantação

Para aplicar um tipo de recurso de extensão no escopo de implantação de destino, adicione o recurso ao modelo como faria com qualquer outro tipo de recurso. Os escopos disponíveis são grupo de recursos, assinatura, grupo de gerenciamento e locatário. O escopo de implantação deve dar suporte ao tipo de recurso.

Quando implantado em um grupo de recursos, o modelo a seguir adiciona um bloqueio a esse grupo de recursos.

resource createRgLock 'Microsoft.Authorization/locks@2020-05-01' = {
  name: 'rgLock'
  properties: {
    level: 'CanNotDelete'
    notes: 'Resource group should not be deleted.'
  }
}

O próximo exemplo atribui uma função à assinatura na qual está implantada.

targetScope = 'subscription'

@description('The principal to assign the role to')
param principalId string

@allowed([
  'Owner'
  'Contributor'
  'Reader'
])
@description('Built-in role to assign')
param builtInRoleType string

var role = {
  Owner: '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635'
  Contributor: '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c'
  Reader: '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7'
}

resource roleAssignSub 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(subscription().id, principalId, role[builtInRoleType])
  properties: {
    roleDefinitionId: role[builtInRoleType]
    principalId: principalId
  }
}

Aplicar ao recurso

Para aplicar um recurso de extensão a um recurso, use a scope propriedade. Na propriedade de escopo, faça referência ao recurso ao qual você está adicionando a extensão. Você faz referência ao recurso fornecendo o nome simbólico para o recurso. A propriedade de escopo é uma propriedade raiz para o tipo de recurso de extensão.

O exemplo a seguir cria uma conta de armazenamento e aplica uma função a ela.

@description('The principal to assign the role to')
param principalId string

@allowed([
  'Owner'
  'Contributor'
  'Reader'
])
@description('Built-in role to assign')
param builtInRoleType string

param location string = resourceGroup().location

var role = {
  Owner: '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635'
  Contributor: '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c'
  Reader: '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7'
}
var uniqueStorageName = 'storage${uniqueString(resourceGroup().id)}'

resource demoStorageAcct 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'Storage'
  properties: {}
}

resource roleAssignStorage 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(demoStorageAcct.id, principalId, role[builtInRoleType])
  properties: {
    roleDefinitionId: role[builtInRoleType]
    principalId: principalId
  }
  scope: demoStorageAcct
}

Você pode aplicar um recurso de extensão a um recurso existente. O exemplo a seguir adiciona um bloqueio a uma conta de armazenamento existente.

resource demoStorageAcct 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: 'examplestore'
}

resource createStorageLock 'Microsoft.Authorization/locks@2020-05-01' = {
  name: 'storeLock'
  scope: demoStorageAcct
  properties: {
    level: 'CanNotDelete'
    notes: 'Storage account should not be deleted.'
  }
}

Você também pode aplicar um recurso de extensão a outro recurso de extensão definindo a scope propriedade como o nome simbólico desse recurso de extensão. O exemplo a seguir aplica um bloqueio a uma atribuição de função existente.

resource existingRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' existing = {
  name: '00000000-0000-0000-0000-000000000000'
}

resource roleAssignmentLock 'Microsoft.Authorization/locks@2020-05-01' = {
  name: 'roleAssignmentLock'
  scope: existingRoleAssignment
  properties: {
    level: 'CanNotDelete'
    notes: 'Role assignment should not be deleted.'
  }
}

Quando qualquer recurso utiliza a scope propriedade, o Bicep gera o ID de recurso totalmente qualificado para o escopo. Isso garante que o template compilado do ARM resolva corretamente o escopo ao chamar extensionResourceId, que requer um ID de recurso totalmente qualificado como seu primeiro argumento. Esse comportamento se aplica a recursos de extensão e a qualquer outro tipo de recurso que use a scope propriedade. Também possibilita cenários de implantação que antes não eram suportados, como a implantação de recursos em nível de locatário de um escopo de implantação menor, como uma assinatura ou grupo de recursos.

Os mesmos requisitos se aplicam aos recursos de extensão assim como a outros recursos quando se direciona um escopo diferente do escopo de destino da implantação. Para saber mais sobre a implantação em mais de um escopo, confira:

• Implantações do grupo de recursos
• Implantações de subscrição
• Implantações de grupo de gerenciamento
• Implantações de locatário

As propriedades resourceGroup e subscription só são permitidas em módulos. Essas propriedades não são permitidas nos recursos individuais. Use módulos se quiser implantar um recurso de extensão com o escopo definido para um recurso em um grupo de recursos diferente.

O exemplo a seguir mostra como aplicar um bloqueio em uma conta de armazenamento que reside em um grupo de recursos diferente.

• main.bicep:

  param resourceGroup2Name string
  param storageAccountName string
  
  module applyStoreLock './storageLock.bicep' = {
    name: 'addStorageLock'
    scope: resourceGroup(resourceGroup2Name)
    params: {
      storageAccountName: storageAccountName
    }
  }
  

• storageLock.bicep:

  param storageAccountName string
  
  resource storage 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
    name: storageAccountName
  }
  
  resource storeLock 'Microsoft.Authorization/locks@2020-05-01' = {
    scope: storage
    name: 'storeLock'
    properties: {
      level: 'CanNotDelete'
      notes: 'Storage account should not be deleted.'
    }
  }
  

Próximas etapas

Para obter uma lista completa dos tipos de recursos de extensão, consulte os tipos de recursos que estendem os recursos de outros recursos.