Questa è la AWS CDK v2 Developer Guide. Il vecchio CDK v1 è entrato in manutenzione il 1° giugno 2022 e ha terminato il supporto il 1° giugno 2023. Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Identificatori e CDK AWS Quando crei app AWS Cloud Development Kit (AWS CDK), utilizzerai molti tipi di identificatori e nomi. Per utilizzare il AWS CDK in modo efficace ed evitare errori, è importante comprendere i tipi di identificatori. Gli identificatori devono essere unici nell'ambito in cui vengono creati; non è necessario che siano univoci a livello globale nell'applicazione CDK. AWS Se si tenta di creare un identificatore con lo stesso valore all'interno dello stesso ambito, il AWS CDK genera un'eccezione. ## Costruisci IDs L'identificatore più comune,`id`, è l'identificatore passato come secondo argomento durante l'istanziazione di un oggetto di costruzione. Questo identificatore, come tutti gli identificatori, deve essere univoco solo nell'ambito in cui viene creato, che è il primo argomento quando si crea un'istanza di un oggetto di costruzione. **Nota** L'`id`of a stack è anche l'identificatore utilizzato per fare riferimento ad esso nel riferimento [AWS CDK CLI](cli.md). Diamo un'occhiata a un esempio in cui abbiamo due costrutti con l'identificatore nella nostra app. `MyBucket` Il primo è definito nell'ambito dello stack con l'identificatore. `Stack1` Il secondo è definito nell'ambito di uno stack con l'identificatore. `Stack2` Poiché sono definiti in ambiti diversi, ciò non causa alcun conflitto e possono coesistere nella stessa app senza problemi. **Example** ``` 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'); ``` ``` 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'); ``` ``` 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') ``` ``` // 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"); } } ``` ``` 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"); } } ``` ## Percorsi I costrutti in un'applicazione AWS CDK formano una gerarchia radicata nella classe. `App` *Ci riferiamo alla raccolta di elementi IDs da un determinato costrutto, dal suo costrutto genitore, dal suo predecessore e così via fino alla radice dell'albero dei costrutti, come percorso.* Il AWS CDK in genere visualizza i percorsi nei modelli sotto forma di stringa. I livelli sono separati IDs da barre, a partire dal nodo immediatamente sotto l'`App`istanza root, che di solito è una pila. Ad esempio, i percorsi delle due risorse del bucket Amazon S3 nell'esempio di codice precedente sono e. `Stack1/MyBucket` `Stack2/MyBucket` È possibile accedere al percorso di qualsiasi costrutto a livello di codice, come illustrato nell'esempio seguente. Questo ottiene il percorso di `myConstruct` (o`my_construct`, come lo scriverebbero gli sviluppatori Python). Poiché IDs devono essere unici nell'ambito in cui vengono creati, i loro percorsi sono sempre unici all'interno di un'applicazione AWS CDK. **Example** ``` const path: string = myConstruct.node.path; ``` ``` const path = myConstruct.node.path; ``` ``` path = my_construct.node.path ``` ``` String path = myConstruct.getNode().getPath(); ``` ``` string path = myConstruct.Node.Path; ``` ## Unici IDs AWS CloudFormation richiede che tutte le IDs logiche di un modello siano uniche. Per questo motivo, il AWS CDK deve essere in grado di generare un identificatore univoco per ogni costrutto di un'applicazione. Le risorse hanno percorsi univoci a livello globale (i nomi di tutti gli ambiti dallo stack a una risorsa specifica). Pertanto, il AWS CDK genera gli identificatori univoci necessari concatenando gli elementi del percorso e aggiungendo un hash a 8 cifre. (L'hash è necessario per distinguere percorsi distinti, come `A/B/C` e`A/BC`, che risulterebbero nello stesso identificatore. AWS CloudFormation AWS CloudFormation gli identificatori sono alfanumerici e non possono contenere barre o altri caratteri separatori.) *Il AWS CDK chiama questa stringa l'ID univoco del costrutto.* In generale, la tua app AWS CDK non dovrebbe aver bisogno di conoscere l'unicità. IDs Tuttavia, potete accedere all'ID univoco di qualsiasi costrutto a livello di codice, come illustrato nell'esempio seguente. **Example** ``` const uid: string = Names.uniqueId(myConstruct); ``` ``` const uid = Names.uniqueId(myConstruct); ``` ``` uid = Names.unique_id(my_construct) ``` ``` String uid = Names.uniqueId(myConstruct); ``` ``` string uid = Names.Uniqueid(myConstruct); ``` L'*indirizzo* è un altro tipo di identificatore univoco che distingue in modo univoco le risorse CDK. Derivato dall'hash SHA-1 del percorso, non è leggibile dall'uomo. Tuttavia, la sua lunghezza costante e relativamente breve (sempre 42 caratteri esadecimali) lo rende utile in situazioni in cui l'ID univoco «tradizionale» potrebbe essere troppo lungo. Alcuni costrutti possono utilizzare l'indirizzo nel AWS CloudFormation modello sintetizzato anziché l'ID univoco. Anche in questo caso, la tua app in genere non dovrebbe aver bisogno di conoscere gli indirizzi dei suoi costrutti, ma puoi recuperare l'indirizzo di un costrutto come segue. **Example** ``` const addr: string = myConstruct.node.addr; ``` ``` const addr = myConstruct.node.addr; ``` ``` addr = my_construct.node.addr ``` ``` String addr = myConstruct.getNode().getAddr(); ``` ``` string addr = myConstruct.Node.Addr; ``` ## Logico IDs Quando il AWS CDK sintetizza l'app in un AWS CloudFormation modello, genera un *ID logico* per ogni risorsa. AWS CloudFormation utilizza la logica IDs per identificare le risorse all'interno di un modello e per tracciarle tra le distribuzioni. Comprendere come viene generata la logica IDs aiuta a evitare sostituzioni involontarie delle risorse quando si esegue il refactoring del codice CDK. ### Come vengono generati i dati logici IDs Il AWS CDK genera dati logici IDs dal percorso di costruzione utilizzando il seguente algoritmo: 1. Concatena i componenti del percorso dall'albero di costruzione, escludendo lo stack stesso. 1. [Applica l'euristica per migliorare la leggibilità (vedi Euristica dei componenti del percorso Logical ID).](#identifiers-logical-id-heuristics) 1. Aggiungi un hash di 8 caratteri del percorso completo per garantire l'unicità. Il formato risultante è: ``` <8-character-hash> ``` Ad esempio, una tabella di routing di sottorete privata VPC potrebbe produrre l'ID logico. `VPCPrivateSubnet2RouteTable0A19E10E` Le seguenti regole si applicano alla generazione di ID logici: + La lunghezza massima è 255 caratteri. La parte leggibile dall'uomo è limitata a 240 caratteri. + L'hash a 8 caratteri assicura che percorsi come `A/B/C` e, che si concatenano nella `A/BC` stessa stringa, producano logiche diverse. IDs + Le risorse che sono figlie dirette dello stack (percorsi a componente singolo) utilizzano il proprio nome direttamente senza un hash, purché il nome sia composto da 255 caratteri o meno. ### Euristica dei componenti del percorso ID logico Il AWS CDK applica la seguente euristica ai componenti del percorso quando genera la parte di logica leggibile dall'uomo. IDs `Default`— rimosso completamente Se un componente del percorso lo è`Default`, il CDK lo rimuove sia dalla parte leggibile dall'uomo che dall'input hash. Ciò significa che racchiudere un costrutto esistente all'interno di un nuovo costrutto e denominare il costrutto interno produce esattamente lo stesso ID logico del costrutto `Default` originale non confezionato. Questo è il meccanismo chiave per rifattorizzare in modo sicuro il codice flat in costrutti di livello superiore senza modificare le identità delle risorse distribuite. `Resource`— nascosto solo nella parte leggibile dall'uomo Se un componente del percorso lo è`Resource`, il CDK lo omette dalla parte leggibile dall'uomo ma lo include comunque nel calcolo dell'hash. Per convenzione, i costrutti L1 (CloudFormation) vengono utilizzati come ID di costruzione. `Resource` Ciò mantiene la logica IDs più breve senza perdere l'unicità. Componenti consecutivi duplicati: deduplicati Se il nome del componente del percorso precedente termina con il nome del componente corrente, il CDK ignora il componente corrente. Ciò impedisce ripetizioni ridondanti in logica. IDs ### Si usa `Default` per preservare la logica IDs quando si esegue il refactoring Quando rifattorizzate un flat stack in costrutti di livello superiore, potete utilizzarlo `Default` come ID del costrutto per la risorsa principale per preservarne l'ID logico. Ciò impedisce di sostituire la risorsa durante la AWS CloudFormation distribuzione. L'esempio seguente mostra uno stack con risorse definite direttamente: **Example** ``` export class MyStack extends cdk.Stack { constructor(scope: Construct, id: string) { super(scope, id); new s3.Bucket(this, 'DataBucket'); new lambda.Function(this, 'ProcessFunction', { /* ... */ }); } } ``` ``` class MyStack extends cdk.Stack { constructor(scope, id) { super(scope, id); new s3.Bucket(this, 'DataBucket'); new lambda.Function(this, 'ProcessFunction', { /* ... */ }); } } ``` ``` 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", # ... ) ``` ``` 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(); } } ``` ``` 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 { // ... }); } } } ``` ``` 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 } ``` Il percorso del bucket è`MyStack/DataBucket/Resource`, che produce un ID logico di. `DataBucket` È possibile estrarre il bucket in un costrutto di livello superiore e conservare lo stesso ID logico denominando il costrutto interno: `Default` **Example** ``` 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'); } } ``` ``` 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'); } } ``` ``` 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") ``` ``` 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"); } } ``` ``` 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"); } } } ``` ``` 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 } ``` Il percorso del bucket è ora. `MyStack/DataBucket/Default/Resource` Poiché `Default` viene rimosso sia dalla parte leggibile dall'uomo che dall'hash input, l'ID logico rimane `DataBucket` identico all'originale. **Importante** È possibile avere un solo figlio con l'ID per ambito del costrutto. `Default` Se hai bisogno di più risorse allo stesso livello, definiscile in modo descrittivo IDs. Il `Default` modello funziona meglio con costrutti a responsabilità singola che hanno una risorsa primaria. ### Considerazioni e limitazioni Quando lavori con logic, tieni presente quanto segue: IDs + È possibile assegnare l'ID del `Default` costrutto a un solo figlio per ambito. + Se si modifica l'ID di un costrutto dopo la distribuzione, l'ID logico cambia, il che comporta la sostituzione della AWS CloudFormation risorsa. `cdk diff`Utilizzatelo per verificare le modifiche prima della distribuzione. + Nei casi in cui la logica è IDs già stata modificata, è possibile utilizzare il `cdk refactor` comando per mappare la logica precedente IDs a quella nuova. Per ulteriori informazioni, consulta [Preservare le risorse distribuite durante il refactoring](refactor.md) del codice CDK. + [Per ulteriori informazioni su come IDs appare la logica nei modelli sintetizzati, consulta Generated logical in your template. IDs AWS CloudFormation ](configure-synth.md#how-synth-default-logical-ids) ### Stabilità dell'ID logico Evita di modificare l'ID logico di una risorsa dopo che è stata creata. AWS CloudFormation identifica le risorse in base al relativo ID logico. Pertanto, se si modifica l'ID logico di una risorsa, AWS CloudFormation crea una nuova risorsa con il nuovo ID logico, quindi elimina quello esistente. A seconda del tipo di risorsa, ciò potrebbe causare l'interruzione del servizio, la perdita di dati o entrambe le cose.