Definieren untergeordneter Ressourcen

  • 5 Minuten

Es ist sinnvoll, einige Ressourcen nur im Kontext ihres übergeordneten Elements bereitzustellen. Diese Ressourcen werden als untergeordnete Ressourcen bezeichnet. Es gibt viele untergeordnete Ressourcentypen in Azure. Hier sind einige Beispiele:

Name Ressourcentyp
Subnetze des virtuellen Netzwerks Microsoft.Network/virtualNetworks/subnets
App Service-Konfiguration Microsoft.Web/sites/config
SQL-Datenbanken Microsoft.Sql/servers/databases
VM-Erweiterungen Microsoft.Compute/virtualMachines/extensions
Storage Blob-Container Microsoft.Storage/storageAccounts/blobServices/containers
Azure Cosmos DB-Container Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers

Betrachten wir beispielsweise einen Storage Blob-Container. Ein Blobcontainer muss in einem Speicherkonto bereitgestellt werden, und es ist nicht sinnvoll, dass ein Container außerhalb eines Speicherkontos vorhanden ist.

Untergeordnete Ressourcentypen weisen längere Namen auf, die aus mehreren Teilen bestehen. Ein Storage Blob-Container hat folgenden vollqualifizierten Typnamen: Microsoft.Storage/storageAccounts/blobServices/containers. Die Ressourcen-ID für einen Blobcontainer enthält den Namen des Speicherkontos, das den Container enthält, und den Namen des Containers.

Hinweis

Einige untergeordnete Ressourcen haben möglicherweise denselben Namen wie andere untergeordnete Ressourcentypen von verschiedenen übergeordneten Ressourcen. containers ist beispielsweise ein untergeordneter Typ von sowohl Speicherkonten als auch Azure Cosmos DB-Datenbanken. Die Namen sind identisch, stellen aber unterschiedliche Ressourcen dar, und ihre vollqualifizierten Typnamen unterscheiden sich.

Wie werden untergeordnete Ressourcen definiert?

Mit Bicep können Sie untergeordnete Ressourcen auf verschiedene Arten deklarieren. Jede Methode hat ihre eigenen Vorteile und eignet sich für manche Situationen, für andere nicht. Schauen wir uns die einzelnen Ansätze an.

Tipp

Alle folgenden Ansätze führen zu denselben Bereitstellungsaktivitäten in Azure. Sie können den Ansatz auswählen, der Ihren Anforderungen am besten entspricht, ohne sich Gedanken darüber machen zu müssen, etwas zu beschädigen. Außerdem können Sie Ihre Vorlage aktualisieren und den von Ihnen verwendeten Ansatz ändern.

Geschachtelte Ressourcen

Ein Ansatz zum Definieren einer untergeordneten Ressource besteht darin, die untergeordnete Ressource innerhalb des übergeordneten Elements zu schachteln. Hier ist ein Beispiel für eine Bicep-Vorlage, die einen virtuellen Computer und eine Erweiterung für virtuelle Computer bereitstellt. Eine Erweiterung für virtuelle Computer ist eine untergeordnete Ressource, die zusätzliches Verhalten für einen virtuellen Computer bereitstellt. In diesem Fall führt die Erweiterung nach der Bereitstellung ein benutzerdefiniertes Skript auf dem virtuellen Computer aus.

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

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

Beachten Sie, dass die geschachtelte Ressource einen einfacheren Ressourcentyp als normal hat. Obwohl der vollqualifizierte Typname Microsoft.Compute/virtualMachines/extensions lautet, erbt die geschachtelte Ressource automatisch den Ressourcentyp des übergeordneten Elements, sodass Sie nur den Typ der untergeordneten Ressource, extensions, angeben müssen.

Beachten Sie außerdem, dass für die geschachtelte Ressource keine API-Version angegeben ist. Bicep geht davon aus, dass Sie dieselbe API-Version wie die übergeordnete Ressource verwenden möchten, obwohl Sie die API-Version außer Kraft setzen können, wenn Sie möchten.

Sie können mithilfe des Operators :: auf eine geschachtelte Ressource verweisen. Beispielsweise können Sie eine Ausgabe erstellen, welche die vollständige Ressourcen-ID der Erweiterung zurückgibt:

output childResourceId string = vm::installCustomScriptExtension.id

Das Schachteln von Ressourcen ist eine einfache Möglichkeit, um eine untergeordnete Ressource zu deklarieren. Durch das Schachteln von Ressourcen wird auch die Übergeordnet/Untergeordnet-Beziehung für jeden offensichtlich, der die Vorlage liest. Wenn Sie jedoch über viele geschachtelte Ressourcen oder mehrere Schachtelungsebenen verfügen, kann dies das Lesen von Vorlagen erschweren. Sie können Ressourcen auch nur bis zu fünf Ebenen tief schachteln.

„parent“-Eigenschaft (übergeordnet)

Ein zweiter Ansatz besteht darin, die untergeordnete Ressource ohne Schachtelung zu deklarieren. Verwenden Sie dann die parent-Eigenschaft, um Bicep über die Beziehung zwischen übergeordneten und untergeordneten Elementen zu informieren:

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

Beachten Sie, dass die untergeordnete Ressource die parent-Eigenschaft verwendet, um auf den symbolischen Namen ihres übergeordneten Elements zu verweisen.

Dieser Ansatz des Verweisens auf das übergeordnete Element ist eine weitere einfache Möglichkeit zum Deklarieren einer untergeordneten Ressource. Bicep erkennt die Beziehung zwischen übergeordneten und untergeordneten Ressourcen, weshalb Sie nicht den vollqualifizierten Ressourcennamen angeben oder eine Abhängigkeit zwischen den Ressourcen einrichten müssen. Der Ansatz vermeidet auch eine zu starke Schachtelung, die die Lesbarkeit erschweren kann. Sie müssen jedoch bei jeder Definition einer untergeordneten Ressource mithilfe der parent-Eigenschaft explizit den vollständigen Ressourcentyp und die API-Version angeben.

Um auf eine untergeordnete Ressource zu verweisen, die mit der parent-Eigenschaft deklariert wird, verwenden Sie ihren symbolischen Namen wie bei einer normalen übergeordneten Ressource:

output childResourceId string = installCustomScriptExtension.id

Erstellen des Ressourcennamens

Es gibt einige Situationen, in denen Sie keine geschachtelten Ressourcen oder das Schlüsselwort parent verwenden können. Beispiele hierfür sind, wenn Sie untergeordnete Ressourcen innerhalb einer for-Schleife deklarieren oder komplexe Ausdrücke verwenden müssen, um dynamisch eine übergeordnete Ressource für ein untergeordnetes Element auszuwählen. In diesen Situationen können Sie eine untergeordnete Ressource bereitstellen, indem Sie den Namen der untergeordneten Ressource manuell so erstellen, dass er den Namen seiner übergeordneten Ressource enthält, wie hier gezeigt:

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

Beachten Sie, dass in diesem Beispiel Zeichenfolgeninterpolation verwendet wird, um die Eigenschaft name der virtuellen Computerressource an den Namen der untergeordneten Ressource anzufügen. Bicep erkennt, dass eine Abhängigkeit zwischen Ihren untergeordneten und übergeordneten Ressourcen besteht. Sie können den Namen der untergeordneten Ressource deklarieren, indem Sie stattdessen die Variable vmName verwenden. Wenn Sie dies tun, kann ihre Bereitstellung jedoch fehlschlagen, da Bicep nicht versteht, dass die übergeordnete Ressource vor der untergeordneten Ressource bereitgestellt werden muss:

Um diese Situation zu beheben, können Sie Bicep manuell über die Abhängigkeit informieren, indem Sie das Schlüsselwort dependsOn verwenden, wie hier gezeigt:

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

Tipp

Es empfiehlt sich im Allgemeinen, die Erstellung von Ressourcennamen zu vermeiden, da Sie viele der Vorteile verlieren, die Bicep bieten kann, wenn es die Beziehungen zwischen Ihren Ressourcen erkennt. Verwenden Sie diese Option nur, wenn Sie keinen der anderen Ansätze zum Deklarieren untergeordneter Ressourcen verwenden können.

IDs untergeordneter Ressourcen

Sie beginnen mit der Erstellung der ID einer untergeordneten Ressource, indem Sie die Ressourcen-ID ihres übergeordneten Elements einschließen und dann den Typ und Namen der untergeordneten Ressource anfügen. Betrachten wir beispielsweise ein Azure Cosmos DB-Konto namens toyrnd. Der Azure Cosmos DB-Ressourcenanbieter macht einen Typ namens databaseAccounts verfügbar, bei dem es sich um die von Ihnen bereitgestellte übergeordnete Ressource handelt:

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

Hier sehen Sie eine visuelle Darstellung derselben Ressourcen-ID:

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

Wenn wir diesem Konto eine Datenbank hinzufügen, verwenden wir den sqlDatabases-Typ für untergeordnete Ressourcen. Fügen wir unserem Azure Cosmos DB-Konto eine Datenbank namens FlightTests hinzu, und sehen wir uns die ID der untergeordneten Ressource an:

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

Hier sehen Sie eine visuelle Darstellung:

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

Sie können über mehrere Ebenen untergeordneter Ressourcen verfügen. Hier ist eine Beispielressourcen-ID, die ein Speicherkonto mit zwei Ebenen untergeordneter Elemente zeigt:

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

Hier sehen Sie eine visuelle Darstellung derselben Ressourcen-ID:

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

Diese Ressourcen-ID besteht aus mehreren Komponenten:

  • Alles bis zu secrettoys ist die ID der übergeordneten Ressource.

  • blobServices gibt an, dass sich die Ressource in dem Typ einer untergeordneten Ressource namens blobServices befindet.

    Hinweis

    Sie müssen keine blobServices-Ressourcen selbst erstellen. Der Ressourcenanbieter Microsoft.Storage erstellt diese Ressource automatisch für Sie, wenn Sie ein Speicherkonto erstellen. Dieser Typ von Ressource wird manchmal als implizite Ressource bezeichnet. Er ist ziemlich ungewöhnlich, aber Sie werden ihn in Azure vorfinden.

  • default ist der Name der untergeordneten Ressource blobServices.

    Hinweis

    Manchmal ist nur eine einzelne Instanz einer untergeordneten Ressource zulässig. Dieser Instanztyp wird als Singleton bezeichnet und erhält häufig den Namen default.

  • containers gibt an, dass sich die Ressource in dem Typ einer untergeordneten Ressource namens containers befindet.

  • glitterspecs ist der Name des Blobcontainers.

Wenn Sie mit untergeordneten Ressourcen arbeiten, können Ressourcen-IDs lang werden und kompliziert aussehen. Wenn Sie jedoch eine Ressourcen-ID in ihre Komponenten aufteilen, ist es einfacher zu verstehen, wie die Ressource strukturiert ist. Eine Ressourcen-ID kann Ihnen auch wichtige Hinweise auf das Verhalten der Ressource geben.