View a markdown version of this page

Identifikatoren und das CDK AWS - AWS Cloud Development Kit (AWS CDK) v2
Konstruieren IDsPfadeEinzigartig IDsLogisch IDs

Dies ist der AWS CDK v2-Entwicklerhandbuch. Das ältere CDK v1 wurde am 1. Juni 2022 in die Wartung aufgenommen und der Support wurde am 1. Juni 2023 eingestellt.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Identifikatoren und das CDK AWS

Beim Erstellen von AWS Cloud Development Kit (AWS CDK) -Apps werden Sie viele Arten von Kennungen und Namen verwenden. Um das AWS CDK effektiv zu nutzen und Fehler zu vermeiden, ist es wichtig, die Arten von Identifikatoren zu verstehen.

Identifikatoren müssen innerhalb des Bereichs, in dem sie erstellt wurden, eindeutig sein. Sie müssen in Ihrer AWS CDK-Anwendung nicht global eindeutig sein.

Wenn Sie versuchen, einen Bezeichner mit demselben Wert innerhalb desselben Bereichs zu erstellen, löst das AWS CDK eine Ausnahme aus.

Konstruieren IDs

Der häufigste Bezeichner,id, ist der Bezeichner, der bei der Instanziierung eines Konstruktobjekts als zweites Argument übergeben wird. Dieser Bezeichner muss, wie alle Bezeichner, nur innerhalb des Bereichs, in dem er erstellt wurde, eindeutig sein. Dies ist das erste Argument bei der Instanziierung eines Konstruktobjekts.

Anmerkung

Der id Wert eines Stacks ist auch der Bezeichner, mit dem Sie in der AWS CDK-CLI-Referenz auf ihn verweisen.

Schauen wir uns ein Beispiel an, bei dem wir zwei Konstrukte mit dem Identifier MyBucket in unserer App haben. Das erste ist im Bereich des Stacks mit dem Bezeichner Stack1 definiert. Der zweite ist im Gültigkeitsbereich eines Stacks mit dem Bezeichner definiertStack2. Da sie in unterschiedlichen Bereichen definiert sind, führt dies zu keinem Konflikt und sie können problemlos in derselben App koexistieren.

Beispiel
TypeScript
import { App, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';

class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps = {}) {
    super(scope, id, props);

    new s3.Bucket(this, 'MyBucket');
  }
}

const app = new App();
new MyStack(app, 'Stack1');
new MyStack(app, 'Stack2');
JavaScript
const { App , Stack } = require('aws-cdk-lib');
const s3 = require('aws-cdk-lib/aws-s3');

class MyStack extends Stack {
  constructor(scope, id, props = {}) {
    super(scope, id, props);

    new s3.Bucket(this, 'MyBucket');
  }
}

const app = new App();
new MyStack(app, 'Stack1');
new MyStack(app, 'Stack2');
Python
from aws_cdk import App, Construct, Stack, StackProps
from constructs import Construct
from aws_cdk import aws_s3 as s3

class MyStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs):

        super().__init__(scope, id, **kwargs)
        s3.Bucket(self, "MyBucket")

app = App()
MyStack(app, 'Stack1')
MyStack(app, 'Stack2')
Java
// MyStack.java
package com.myorg;

import software.amazon.awscdk.App;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.constructs.Construct;
import software.amazon.awscdk.services.s3.Bucket;

public class MyStack extends Stack {
    public MyStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);
        new Bucket(this, "MyBucket");
    }
}

// Main.java
package com.myorg;

import software.amazon.awscdk.App;

public class Main {
    public static void main(String[] args) {
        App app = new App();
        new MyStack(app, "Stack1");
        new MyStack(app, "Stack2");
    }
}
C#
using Amazon.CDK;
using constructs;
using Amazon.CDK.AWS.S3;

public class MyStack : Stack
{
    public MyStack(Construct scope, string id, IStackProps props) : base(scope, id, props)
    {
        new Bucket(this, "MyBucket");
    }
}

class Program
{
    static void Main(string[] args)
    {
        var app = new App();
        new MyStack(app, "Stack1");
        new MyStack(app, "Stack2");
    }
}

Pfade

Die Konstrukte in einer AWS CDK-Anwendung bilden eine Hierarchie, die in der Klasse verwurzelt ist. App Wir bezeichnen die Sammlung IDs von einem bestimmten Konstrukt, seinem Elternkonstrukt, seinem übergeordneten Konstrukt usw. bis zur Wurzel des Konstruktbaums als Pfad.

Das AWS CDK zeigt Pfade in Ihren Vorlagen normalerweise als Zeichenfolge an. Die IDs von den Ebenen werden durch Schrägstriche getrennt, beginnend am Knoten unmittelbar unter der App Root-Instance, bei der es sich normalerweise um einen Stack handelt. Die Pfade der beiden Amazon S3 S3-Bucket-Ressourcen im vorherigen Codebeispiel lauten beispielsweise Stack1/MyBucket undStack2/MyBucket.

Sie können programmgesteuert auf den Pfad eines beliebigen Konstrukts zugreifen, wie im folgenden Beispiel gezeigt. Dies erhält den Pfad von myConstruct (odermy_construct, wie Python-Entwickler ihn schreiben würden). Da sie innerhalb des Bereichs, in dem sie erstellt wurden, eindeutig sein IDs müssen, sind ihre Pfade innerhalb einer AWS CDK-Anwendung immer eindeutig.

Beispiel
TypeScript
const path: string = myConstruct.node.path;
JavaScript
const path = myConstruct.node.path;
Python
path = my_construct.node.path
Java
String path = myConstruct.getNode().getPath();
C#
string path = myConstruct.Node.Path;

Einzigartig IDs

AWS CloudFormation erfordert, dass alle logischen IDs Elemente in einer Vorlage eindeutig sind. Aus diesem Grund muss das AWS CDK in der Lage sein, für jedes Konstrukt in einer Anwendung eine eindeutige Kennung zu generieren. Ressourcen haben Pfade, die global eindeutig sind (die Namen aller Bereiche vom Stack bis zu einer bestimmten Ressource). Daher generiert das AWS CDK die erforderlichen eindeutigen Identifikatoren, indem es die Elemente des Pfads verkettet und einen 8-stelligen Hash hinzufügt. (Der Hash ist notwendig, um verschiedene Pfade wie A/B/C und zu unterscheidenA/BC, die zu derselben Kennung führen würden. AWS CloudFormation AWS CloudFormation Bezeichner sind alphanumerisch und dürfen keine Schrägstriche oder andere Trennzeichen enthalten.) Das AWS CDK nennt diese Zeichenfolge die eindeutige ID des Konstrukts.

Im Allgemeinen sollte Ihre AWS CDK-App nichts über Unique wissen müssen. IDs Sie können jedoch programmgesteuert auf die eindeutige ID eines beliebigen Konstrukts zugreifen, wie im folgenden Beispiel gezeigt.

Beispiel
TypeScript
const uid: string = Names.uniqueId(myConstruct);
JavaScript
const uid = Names.uniqueId(myConstruct);
Python
uid = Names.unique_id(my_construct)
Java
String uid = Names.uniqueId(myConstruct);
C#
string uid = Names.Uniqueid(myConstruct);

Die Adresse ist eine weitere Art von eindeutiger Kennung, die CDK-Ressourcen eindeutig unterscheidet. Er wurde vom SHA-1-Hash des Pfads abgeleitet und ist nicht für Menschen lesbar. Aufgrund seiner konstanten, relativ kurzen Länge (immer 42 Hexadezimalzeichen) ist er jedoch in Situationen nützlich, in denen die „traditionelle“ eindeutige ID möglicherweise zu lang ist. Einige Konstrukte verwenden möglicherweise die Adresse in der synthetisierten AWS CloudFormation Vorlage anstelle der eindeutigen ID. Auch hier sollte Ihre App im Allgemeinen nichts über die Adressen ihrer Konstrukte wissen müssen, aber Sie können die Adresse eines Konstrukts wie folgt abrufen.

Beispiel
TypeScript
const addr: string = myConstruct.node.addr;
JavaScript
const addr = myConstruct.node.addr;
Python
addr = my_construct.node.addr
Java
String addr = myConstruct.getNode().getAddr();
C#
string addr = myConstruct.Node.Addr;

Logisch IDs

Wenn das AWS CDK Ihre App zu einer AWS CloudFormation Vorlage zusammenfasst, generiert es für jede Ressource eine logische ID. AWS CloudFormation verwendet Logical IDs , um Ressourcen innerhalb einer Vorlage zu identifizieren und sie über mehrere Bereitstellungen hinweg nachzuverfolgen. Wenn Sie wissen, wie logische IDs Daten generiert werden, können Sie verhindern, dass Ressourcen unbeabsichtigt ersetzt werden, wenn Sie Ihren CDK-Code umgestalten.

Wie logisch werden sie generiert IDs

Das AWS CDK generiert logische Daten IDs aus dem Konstruktpfad mithilfe des folgenden Algorithmus:

  1. Verketten Sie die Pfadkomponenten aus dem Konstruktbaum, mit Ausnahme des Stacks selbst.

  2. Wenden Sie Heuristiken an, um die Lesbarkeit zu verbessern (siehe Heuristik für logische ID-Pfadkomponenten).

  3. Hängen Sie einen 8-stelligen Hash des vollständigen Pfads an, um die Eindeutigkeit sicherzustellen.

Das resultierende Format ist:

<human-readable-portion><8-character-hash>

Beispielsweise könnte eine private VPC-Subnetz-Routentabelle die logische ID erzeugen. VPCPrivateSubnet2RouteTable0A19E10E

Die folgenden Regeln gelten für die Generierung logischer IDs:

  • Die maximale Länge beträgt 255 Zeichen. Der menschenlesbare Teil ist auf 240 Zeichen begrenzt.

  • Der 8-stellige Hash stellt sicher, dass Pfade wie A/B/C und A/BC — die zu derselben Zeichenfolge verketten — unterschiedliche logische Ergebnisse ergeben. IDs

  • Ressourcen, die direkt dem Stack untergeordnet sind (Einkomponentenpfade), verwenden ihren Namen direkt ohne Hash, sofern der Name 255 Zeichen oder weniger umfasst.

Heuristiken für logische ID-Pfadkomponenten

Das AWS CDK wendet die folgenden Heuristiken auf Pfadkomponenten an, wenn es den für Menschen lesbaren Teil von Logical generiert. IDs

Default— vollständig entfernt

Wenn eine Pfadkomponente vorhanden istDefault, entfernt das CDK sie sowohl aus dem für Menschen lesbaren Teil als auch aus der Hash-Eingabe. Das bedeutet, dass das Umschließen eines vorhandenen Konstrukts in ein neues Konstrukt — und das innere Konstrukt benennen Default — genau dieselbe logische ID erzeugt wie das ursprüngliche, unverpackte Konstrukt. Dies ist der wichtigste Mechanismus für die sichere Umgestaltung von Flatcode in Konstrukte höherer Ebene, ohne die Identitäten der bereitgestellten Ressourcen zu ändern.

Resource— nur vor dem für Menschen lesbaren Teil verborgen

Wenn es sich bei einer Pfadkomponente um eine Pfadkomponente handeltResource, lässt das CDK sie aus dem für Menschen lesbaren Teil weg, bezieht sie aber trotzdem in die Hash-Berechnung mit ein. L1 (CloudFormation) -Konstrukte verwenden Resource per Konvention ihre Konstrukt-ID. Dadurch wird die Logik IDs kürzer, ohne an Eindeutigkeit zu verlieren.

Doppelte aufeinanderfolgende Komponenten — dedupliziert

Wenn der vorherige Pfadkomponentenname mit dem aktuellen Komponentennamen endet, überspringt das CDK die aktuelle Komponente. Dies verhindert redundante Wiederholungen in logischen Fällen. IDs

Wird verwendetDefault, um IDs beim Refactoring die Logik beizubehalten

Wenn Sie einen Flat-Stack in Konstrukte höherer Ebene umgestalten, können Sie ihn Default als Konstrukt-ID für die primäre Ressource verwenden, um deren logische ID beizubehalten. Dadurch wird AWS CloudFormation verhindert, dass die Ressource während der Bereitstellung ersetzt wird.

Das folgende Beispiel zeigt einen Stack mit Ressourcen, die direkt definiert sind:

Beispiel
TypeScript
export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    new s3.Bucket(this, 'DataBucket');
    new lambda.Function(this, 'ProcessFunction', { /* ... */ });
  }
}
JavaScript
class MyStack extends cdk.Stack {
  constructor(scope, id) {
    super(scope, id);
    new s3.Bucket(this, 'DataBucket');
    new lambda.Function(this, 'ProcessFunction', { /* ... */ });
  }
}
Python
from aws_cdk import (
    Stack,
    aws_s3 as s3,
    aws_lambda as _lambda,
)
from constructs import Construct

class MyStack(Stack):
    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)
        s3.Bucket(self, "DataBucket")
        _lambda.Function(self, "ProcessFunction", # ...
        )
Java
package com.myorg;

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.lambda.Function;

public class MyStack extends Stack {
    public MyStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);
        new Bucket(this, "DataBucket");
        Function.Builder.create(this, "ProcessFunction")
            // ...
            .build();
    }
}
C#
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Lambda;

namespace MyApp
{
    public class MyStack : Stack
    {
        public MyStack(Construct scope, string id, StackProps props = null) : base(scope, id, props)
        {
            new Bucket(this, "DataBucket");
            new Function(this, "ProcessFunction", new FunctionProps
            {
                // ...
            });
        }
    }
}
Go
package main

import (
	"github.com/aws/aws-cdk-go/awscdk/v2"
	"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
	"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
	"github.com/aws/constructs-go/constructs/v10"
	"github.com/aws/jsii-runtime-go"
)

type MyStackProps struct {
	awscdk.StackProps
}

func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack {
	stack := awscdk.NewStack(scope, &id, &props.StackProps)

	awss3.NewBucket(stack, jsii.String("DataBucket"), &awss3.BucketProps{})
	awslambda.NewFunction(stack, jsii.String("ProcessFunction"), &awslambda.FunctionProps{
		// ...
	})

	return stack
}

Der Pfad des Buckets lautetMyStack/DataBucket/Resource, was eine logische ID von erzeugtDataBucket<hash>.

Sie können den Bucket in ein übergeordnetes Konstrukt extrahieren und dieselbe logische ID beibehalten, indem Sie das innere Konstrukt wie folgt benennen: Default

Beispiel
TypeScript
class DataPipeline extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    new s3.Bucket(this, 'Default');  // 'Default' is hidden from logical ID
    new lambda.Function(this, 'ProcessFunction', { /* ... */ });
  }
}

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    new DataPipeline(this, 'DataBucket');
  }
}
JavaScript
class DataPipeline extends Construct {
  constructor(scope, id) {
    super(scope, id);
    new s3.Bucket(this, 'Default');  // 'Default' is hidden from logical ID
    new lambda.Function(this, 'ProcessFunction', { /* ... */ });
  }
}

class MyStack extends cdk.Stack {
  constructor(scope, id) {
    super(scope, id);
    new DataPipeline(this, 'DataBucket');
  }
}
Python
from aws_cdk import (
    Stack,
    aws_s3 as s3,
    aws_lambda as _lambda,
)
from constructs import Construct

class DataPipeline(Construct):
    def __init__(self, scope: Construct, id: str) -> None:
        super().__init__(scope, id)
        s3.Bucket(self, "Default")  # 'Default' is hidden from logical ID
        _lambda.Function(self, "ProcessFunction", # ...
        )

class MyStack(Stack):
    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)
        DataPipeline(self, "DataBucket")
Java
package com.myorg;

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.lambda.Function;

public class DataPipeline extends Construct {
    public DataPipeline(final Construct scope, final String id) {
        super(scope, id);
        new Bucket(this, "Default");  // 'Default' is hidden from logical ID
        Function.Builder.create(this, "ProcessFunction")
            // ...
            .build();
    }
}

public class MyStack extends Stack {
    public MyStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public MyStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);
        new DataPipeline(this, "DataBucket");
    }
}
C#
using Amazon.CDK;
using Constructs;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Lambda;

namespace MyApp
{
    public class DataPipeline : Construct
    {
        public DataPipeline(Construct scope, string id) : base(scope, id)
        {
            new Bucket(this, "Default");  // 'Default' is hidden from logical ID
            new Function(this, "ProcessFunction", new FunctionProps
            {
                // ...
            });
        }
    }

    public class MyStack : Stack
    {
        public MyStack(Construct scope, string id, StackProps props = null) : base(scope, id, props)
        {
            new DataPipeline(this, "DataBucket");
        }
    }
}
Go
package main

import (
	"github.com/aws/aws-cdk-go/awscdk/v2"
	"github.com/aws/aws-cdk-go/awscdk/v2/awslambda"
	"github.com/aws/aws-cdk-go/awscdk/v2/awss3"
	"github.com/aws/constructs-go/constructs/v10"
	"github.com/aws/jsii-runtime-go"
)

type DataPipeline struct {
	constructs.Construct
}

func NewDataPipeline(scope constructs.Construct, id string) constructs.Construct {
	this := constructs.NewConstruct(scope, &id)

	// 'Default' is hidden from logical ID
	awss3.NewBucket(this, jsii.String("Default"), &awss3.BucketProps{})
	awslambda.NewFunction(this, jsii.String("ProcessFunction"), &awslambda.FunctionProps{
		// ...
	})

	return this
}

type MyStackProps struct {
	awscdk.StackProps
}

func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack {
	stack := awscdk.NewStack(scope, &id, &props.StackProps)

	NewDataPipeline(stack, "DataBucket")

	return stack
}

Der Pfad des Buckets ist jetzt. MyStack/DataBucket/Default/Resource Da er Default sowohl aus dem für Menschen lesbaren Teil als auch aus der Hash-Eingabe entfernt wird, bleibt die logische ID erhalten DataBucket<hash> — identisch mit dem Original.

Wichtig

DefaultPro Konstruktbereich kann nur ein untergeordnetes Objekt mit der ID vorhanden sein. Wenn Sie mehrere Ressourcen auf derselben Ebene benötigen, geben Sie ihnen eine Beschreibung. IDs Das Default Muster funktioniert am besten bei Konstrukten mit einer einzigen Verantwortung, die über eine primäre Ressource verfügen.

Einschränkungen und Überlegungen

Beachten Sie Folgendes, wenn Sie mit logischen Methoden arbeiten: IDs

  • Sie können nur einem Kind pro Bereich die Default Konstrukt-ID zuweisen.

  • Wenn Sie eine Konstrukt-ID nach der Bereitstellung ändern, ändert sich auch die logische ID, was AWS CloudFormation dazu führt, dass die Ressource ersetzt wird. Wird verwendetcdk diff, um Änderungen vor der Bereitstellung zu überprüfen.

  • In Fällen, in denen sich logische Daten bereits geändert IDs haben, können Sie den cdk refactor Befehl verwenden, um alte logische IDs Daten neuen zuzuordnen. Weitere Informationen finden Sie unter Beibehaltung der bereitgestellten Ressourcen beim Refactoring von CDK-Code.

  • Weitere Informationen darüber, wie logisch in synthetisierten Vorlagen IDs dargestellt wird, finden Sie unter In Ihrer Vorlage generierte logische IDs Daten. AWS CloudFormation

Stabilität logischer IDs

Vermeiden Sie es, die logische ID einer Ressource zu ändern, nachdem sie erstellt wurde. AWS CloudFormation identifiziert Ressourcen anhand ihrer logischen ID. Wenn Sie also die logische ID einer Ressource ändern, AWS CloudFormation wird eine neue Ressource mit der neuen logischen ID erstellt und anschließend die vorhandene gelöscht. Je nach Ressourcentyp kann dies zu Betriebsunterbrechungen, Datenverlust oder beidem führen.