Definire le risorse figlio

5 minuti

È opportuno distribuire alcune risorse solo all'interno del contesto dell'elemento padre. Queste risorse sono denominate risorse figlio. In Azure sono disponibili molti tipi di risorse figlio. Ecco alcuni esempi:

Nome	Tipo di risorsa
Subnet della rete virtuale	`Microsoft.Network/virtualNetworks/subnets`
Configurazione del servizio app	`Microsoft.Web/sites/config`
Database SQL	`Microsoft.Sql/servers/databases`
Estensioni macchina virtuale	`Microsoft.Compute/virtualMachines/extensions`
Contenitori BLOB di archiviazione	`Microsoft.Storage/storageAccounts/blobServices/containers`
Contenitore Azure Cosmos DB	`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers`

Si consideri ad esempio un contenitore BLOB di archiviazione. Un contenitore BLOB deve essere distribuito in un account di archiviazione. Un contenitore non può trovarsi all'esterno di un account di archiviazione.

I tipi di risorse figlio hanno nomi più lunghi con più parti. Un contenitore BLOB di archiviazione ha questo nome di tipo completo: Microsoft.Storage/storageAccounts/blobServices/containers. L'ID risorsa per un contenitore BLOB include il nome dell'account di archiviazione che contiene il contenitore e il nome del contenitore.

Nota

Alcune risorse figlio potrebbero avere lo stesso nome di altri tipi di risorse figlio di elementi padre diversi. Ad esempio, containers è un tipo figlio degli account di archiviazione e dei database Azure Cosmos DB. I nomi sono gli stessi, ma rappresentano risorse diverse e i relativi nomi di tipo completi sono diversi.

Come vengono definite le risorse figlio?

Con Bicep è possibile dichiarare le risorse figlio in diversi modi. Ogni modo offre vantaggi specifici, ognuno dei quali è adatto per alcune situazioni e non per altre. Esaminiamo ogni approccio.

Suggerimento

Tutti gli approcci seguenti comportano le stesse attività di distribuzione in Azure. È possibile scegliere l'approccio più adatto alle proprie esigenze senza doversi preoccupare delle conseguenze. È anche possibile aggiornare il modello e modificare l'approccio in uso.

Risorse annidate

Un approccio di definizione di una risorsa figlio consiste nell'annidare la risorsa figlio all'interno della risorsa padre. Di seguito è riportato un esempio di modello Bicep che distribuisce una macchina virtuale e un'estensione macchina virtuale. Un'estensione macchina virtuale è una risorsa figlio che offre un comportamento aggiuntivo per una macchina virtuale. In questo caso, l'estensione esegue uno script personalizzato nella macchina virtuale dopo la distribuzione.

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

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

Si noti che la risorsa annidata ha un tipo di risorsa più semplice del normale. Anche se il nome completo del tipo è Microsoft.Compute/virtualMachines/extensions, la risorsa annidata eredita automaticamente il tipo di risorsa della risorsa padre ed è quindi necessario specificare solo il tipo di risorsa figlio, extensions.

Si noti anche che non è stata specificata alcuna versione dell'API per la risorsa annidata. Bicep presuppone che si voglia usare la stessa versione dell'API della risorsa padre, anche se è possibile sostituire la versione dell'API.

È possibile fare riferimento a una risorsa annidata usando l'operatore ::. Ad esempio, è possibile creare un output che restituisce l'ID risorsa completo dell'estensione:

output childResourceId string = vm::installCustomScriptExtension.id

L'annidamento delle risorse è un modo semplice per dichiarare una risorsa figlio. L'annidamento delle risorse rende anche evidente la relazione padre-figlio a chiunque legga il modello. Tuttavia, se si hanno molte risorse annidate o più livelli di annidamento, i modelli possono diventare più difficili da leggere. L'annidamento delle risorse può avere un massimo di cinque livelli.

Proprietà padre

Un secondo approccio consiste nel dichiarare la risorsa figlio senza annidamento. Usare quindi la parent proprietà per indicare a Bicep la relazione padre-figlio:

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: {
    // ...
  }
}

Si noti che la risorsa figlio usa la proprietà parent per fare riferimento al nome simbolico della risorsa padre.

Questo approccio di riferimento alla risorsa padre è un altro modo semplice per dichiarare una risorsa figlio. Poiché Bicep individua la relazione tra le risorse padre e figlio, non è necessario specificare il nome completo della risorsa o configurare una dipendenza tra le risorse. L'approccio evita anche un eccessivo annidamento che può diventare difficile da leggere. Tuttavia, è necessario specificare in modo esplicito il tipo di risorsa completo e la versione dell'API ogni volta che si definisce una risorsa figlio usando la proprietà parent.

Per fare riferimento a una risorsa figlio dichiarata con la proprietà , usare il parent nome simbolico come si farebbe con una normale risorsa padre:

output childResourceId string = installCustomScriptExtension.id

Costruire il nome della risorsa

In alcune circostanze non è possibile usare risorse annidate o la parola chiave parent. Ad esempio, quando si dichiarano risorse figlio all'interno di un ciclo for o quando è necessario usare espressioni complesse per selezionare dinamicamente una risorsa padre per una risorsa figlio. In queste situazioni, è possibile distribuire una risorsa figlio creando manualmente il nome della risorsa figlio in modo che includa il nome della risorsa padre, come illustrato di seguito:

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: {
    // ...
  }
}

Si noti che questo esempio usa l'interpolazione di stringhe per aggiungere la proprietà name della risorsa macchina virtuale al nome della risorsa figlio. Bicep considera la presenza di una dipendenza tra le risorse figlio e padre. È possibile dichiarare il nome della risorsa figlio usando invece la variabile vmName. In questo caso, tuttavia, la distribuzione potrebbe non riuscire perché Bicep non riconosce che la risorsa padre deve essere distribuita prima della risorsa figlio:

Per risolvere questa situazione, è possibile indicare manualmente a Bicep la dipendenza usando la dependsOn parola chiave , come illustrato di seguito:

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
  ]
  //...
}

Suggerimento

È in genere consigliabile evitare di costruire nomi di risorse, perché si perdono molti dei vantaggi che Bicep può offrire quando individua le relazioni tra le risorse. Usare questa opzione solo quando non è possibile usare uno degli altri approcci per dichiarare le risorse figlio.

ID delle risorse figlio

Si inizia a creare un ID risorsa figlio includendo l'ID della risorsa padre e quindi aggiungendo il tipo e il nome della risorsa figlio. Si consideri ad esempio un account Azure Cosmos DB denominato toyrnd. Il provider di risorse Azure Cosmos DB espone un tipo denominato databaseAccounts, che è la risorsa padre distribuita:

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

Di seguito è riportata una rappresentazione visiva dello stesso ID risorsa:

Resource ID for an Azure Cosmos DB account, split with the key-value pair on a separate line.

Se si aggiunge un database a questo account, è possibile usare il sqlDatabases tipo di risorsa figlio. Aggiungere un database denominato FlightTests all'account Azure Cosmos DB ed esaminare l'ID risorsa figlio:

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

Di seguito è riportata una rappresentazione visiva:

Child resource ID for an Azure Cosmos DB database, split with the key-value pair on a separate line.

È possibile avere più livelli di risorse figlio. Di seguito è illustrato un ID risorsa di esempio che mostra un account di archiviazione con due livelli di risorse figlio:

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

Di seguito è riportata una rappresentazione visiva dello stesso ID risorsa:

Child resource ID for a storage account with blob container, split with the key-value pair on a separate line.

Questo ID risorsa include diversi componenti:

Tutti gli elementi fino a secrettoys costituiscono l'ID risorsa padre.
blobServices indica che la risorsa si trova all'interno di un tipo di risorsa figlio denominato blobServices.

Nota

Non è necessario creare le risorse blobServices manualmente. Il provider di risorse Microsoft.Storage crea automaticamente questa risorsa quando si crea un account di archiviazione. Questo tipo di risorsa è chiamato a volte risorsa implicita. Non sono comuni, ma sono presenti in Azure.
default è il nome della risorsa figlio blobServices.

Nota

In alcuni casi, è consentita una sola istanza di una risorsa figlio. Questo tipo di istanza è chiamato singleton e spesso è denominato default.
containers indica che la risorsa si trova all'interno di un tipo di risorsa figlio denominato containers.
glitterspecs è il nome del contenitore BLOB.