Definir recursos filho

  • 5 minutos

Faz sentido utilizar alguns recursos apenas no contexto dos seus pais. Esses recursos são chamados de recursos filho. Há muitos tipos de recursos filho no Azure. Eis alguns exemplos:

Nome Tipo de recurso
Sub-redes de rede virtual Microsoft.Network/virtualNetworks/subnets
Configuração do Serviço de Aplicativo Microsoft.Web/sites/config
Bases de Dados SQL Microsoft.Sql/servers/databases
Extensões de máquina virtual Microsoft.Compute/virtualMachines/extensions
Contêineres de blob de armazenamento Microsoft.Storage/storageAccounts/blobServices/containers
Contêineres do Azure Cosmos DB Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers

Por exemplo, vamos considerar um contêiner de blob de armazenamento. Um contêiner de blob deve ser implantado em uma conta de armazenamento e não faz sentido que um contêiner exista fora de uma conta de armazenamento.

Os tipos de recursos filho têm nomes mais longos com várias partes. Um contêiner de blob de armazenamento tem este nome de tipo totalmente qualificado: Microsoft.Storage/storageAccounts/blobServices/containers. A ID do recurso para um contêiner de blob inclui o nome da conta de armazenamento que contém o contêiner e o nome do contêiner.

Nota

Alguns recursos filho podem ter o mesmo nome que outros tipos de recursos filho de pais diferentes. Por exemplo, containers é um tipo filho de contas de armazenamento e bancos de dados do Azure Cosmos DB. Os nomes são os mesmos, mas representam recursos diferentes, e seus nomes de tipo totalmente qualificados são diferentes.

Como são definidos os recursos infantis?

Com o Bicep, você pode declarar recursos filho de várias maneiras diferentes. Cada caminho tem suas próprias vantagens, e cada um é adequado para algumas situações e não para outras. Vejamos cada abordagem.

Gorjeta

Todas as abordagens a seguir resultam nas mesmas atividades de implantação no Azure. Você pode escolher a abordagem que melhor se adapta às suas necessidades sem ter que se preocupar em quebrar algo. E você pode atualizar seu modelo e alterar a abordagem que está usando.

Recursos aninhados

Uma abordagem para definir um recurso filho é aninhar o recurso filho dentro do pai. Aqui está um exemplo de um modelo Bicep que implanta uma máquina virtual e uma extensão de máquina virtual. Uma extensão de máquina virtual é um recurso filho que fornece comportamento extra para uma máquina virtual. Nesse caso, a extensão executa um script personalizado na máquina virtual após a implantação.

resource vm 'Microsoft.Compute/virtualMachines@2024-07-01' = {
  name: vmName
  location: location
  properties: {
    // ...
  }

  resource installCustomScriptExtension 'extensions' = {
    name: 'InstallCustomScript'
    location: location
    properties: {
      // ...
    }
  }
}

Observe que o recurso aninhado tem um tipo de recurso mais simples do que o normal. Embora o nome do tipo totalmente qualificado seja Microsoft.Compute/virtualMachines/extensions, o recurso aninhado herda automaticamente o tipo de recurso pai, portanto, você precisa especificar apenas o tipo de recurso filho, extensions.

Observe também que não há nenhuma versão da API especificada para o recurso aninhado. O Bicep pressupõe que você deseja usar a mesma versão da API que o recurso pai, embora você possa substituir a versão da API se desejar.

Você pode fazer referência a um recurso aninhado usando o :: operador . Por exemplo, você pode criar uma saída que retorna a ID de recurso completa da extensão:

output childResourceId string = vm::installCustomScriptExtension.id

Aninhar recursos é uma maneira simples de declarar um recurso filho. Os recursos de aninhamento também tornam a relação pai-filho óbvia para qualquer pessoa que leia o modelo. No entanto, se você tiver muitos recursos aninhados ou várias camadas de aninhamento, os modelos podem se tornar mais difíceis de ler. Você também pode aninhar recursos apenas até cinco camadas de profundidade.

Propriedade pai

Uma segunda abordagem é declarar o recurso filho sem qualquer aninhamento. Em seguida, use a propriedade para informar o parent Bicep sobre a relação pai-filho:

resource vm 'Microsoft.Compute/virtualMachines@2024-07-01' = {
  name: vmName
  location: location
  properties: {
    // ...
  }
}

resource installCustomScriptExtension 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  parent: vm
  name: 'InstallCustomScript'
  location: location
  properties: {
    // ...
  }
}

Observe que o recurso filho usa a parent propriedade para se referir ao nome simbólico de seu pai.

Essa abordagem para referenciar o pai é outra maneira fácil de declarar um recurso filho. O Bicep entende a relação entre recursos pai e filho, portanto, você não precisa especificar o nome do recurso totalmente qualificado ou configurar uma dependência entre os recursos. A abordagem também evita ter muito aninhamento, que pode se tornar difícil de ler. No entanto, você precisa especificar explicitamente o tipo de recurso completo e a versão da API sempre que definir um recurso filho usando a parent propriedade.

Para se referir a um recurso filho declarado com a parent propriedade, use seu nome simbólico como faria com um recurso pai normal:

output childResourceId string = installCustomScriptExtension.id

Construir o nome do recurso

Há algumas circunstâncias em que você não pode usar recursos aninhados ou a parent palavra-chave. Os exemplos incluem quando você declara recursos filho dentro de um for loop ou quando precisa usar expressões complexas para selecionar dinamicamente um recurso pai para um filho. Nessas situações, você pode implantar um recurso filho construindo manualmente o nome do recurso filho para que ele inclua seu nome de recurso pai, conforme mostrado aqui:

resource vm 'Microsoft.Compute/virtualMachines@2024-07-01' = {
  name: vmName
  location: location
  properties: {
    // ...
  }
}

resource installCustomScriptExtension 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  name: '${vm.name}/InstallCustomScript'
  location: location
  properties: {
    // ...
  }
}

Observe que este exemplo usa interpolação de cadeia de caracteres para acrescentar a propriedade de recurso name de máquina virtual ao nome do recurso filho. O Bíceps entende que há uma dependência entre os recursos do seu filho e dos pais. Você pode declarar o nome do recurso filho usando a vmName variável em vez disso. Se você fizer isso, no entanto, sua implantação poderá falhar porque o Bicep não entenderia que o recurso pai precisa ser implantado antes do recurso filho:

Para resolver essa situação, você pode informar manualmente o Bicep sobre a dependência usando a dependsOn palavra-chave, conforme mostrado aqui:

resource vm 'Microsoft.Compute/virtualMachines@2024-07-01' = {
  name: vmName
  location: location
  properties: {
    // ...
  }
}

resource installCustomScriptExtension 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  name: '${vmName}/InstallCustomScript'
  dependsOn: [
    vm
  ]
  //...
}

Gorjeta

Geralmente, é melhor evitar a construção de nomes de recursos, porque você perde muitos dos benefícios que o Bicep pode fornecer quando entende as relações entre seus recursos. Use essa opção somente quando não puder usar uma das outras abordagens para declarar recursos filho.

IDs de recursos filho

Você começa a criar uma ID de recurso filho incluindo a ID de recurso pai e, em seguida, anexando o tipo de recurso filho e o nome. Por exemplo, vamos considerar uma conta do Azure Cosmos DB chamada toyrnd. O provedor de recursos do Azure Cosmos DB expõe um tipo chamado databaseAccounts, que é o recurso pai que você implanta:

/subscriptions/A123b4567c-1234-1a2b-2b1a-1234abc12345/resourceGroups/ToyDevelopment/providers/Microsoft.DocumentDB/databaseAccounts/toyrnd

Aqui está uma representação visual do mesmo ID de recurso:

ID de recurso para uma conta do Azure Cosmos DB, dividida com o par chave-valor em uma linha separada.

Se adicionarmos um banco de dados a essa conta, poderemos usar o sqlDatabases tipo de recurso filho. Vamos adicionar um banco de dados nomeado FlightTests à nossa conta do Azure Cosmos DB e dar uma olhada na ID do recurso filho:

/subscriptions/A123b4567c-1234-1a2b-2b1a-1234abc12345/resourceGroups/ToyDevelopment/providers/Microsoft.DocumentDB/databaseAccounts/toyrnd/sqlDatabases/FlightTests

Aqui está uma representação visual:

ID de recurso filho para um banco de dados do Azure Cosmos DB, dividido com o par chave-valor em uma linha separada.

Você pode ter vários níveis de recursos filho. Aqui está um exemplo de ID de recurso que mostra uma conta de armazenamento com dois níveis de filhos:

/subscriptions/A123b4567c-1234-1a2b-2b1a-1234abc12345/resourceGroups/ToyDevelopment/providers/Microsoft.Storage/storageAccounts/secrettoys/blobServices/default/containers/glitterspecs

Aqui está uma representação visual do mesmo ID de recurso:

ID de recurso filho para uma conta de armazenamento com contêiner de blob, dividida com o par chave-valor em uma linha separada.

Este ID de recurso tem vários componentes:

  • Tudo até secrettoys é o ID do recurso pai.

  • blobServices Indica que o recurso está dentro de um tipo de recurso filho chamado blobServices.

    Nota

    Você não precisa criar blobServices recursos sozinho. O Microsoft.Storage provedor de recursos cria automaticamente esse recurso para você quando você cria uma conta de armazenamento. Esse tipo de recurso às vezes é chamado de recurso implícito . Eles são bastante incomuns, mas você os encontrará em todo o Azure.

  • default é o nome do blobServices recurso filho.

    Nota

    Às vezes, apenas uma única instância de um recurso filho é permitida. Esse tipo de instância é chamado de singleton, e geralmente recebe o nome default.

  • containers Indica que o recurso está dentro de um tipo de recurso filho chamado containers.

  • glitterspecs é o nome do contêiner de blob.

Quando você trabalha com recursos filho, as IDs de recursos podem ficar longas e parecer complicadas. No entanto, se você dividir um ID de recurso em suas partes componentes, será mais fácil entender como o recurso é estruturado. Um ID de recurso também pode fornecer pistas importantes sobre como o recurso se comporta.