View a markdown version of this page

Pengidentifikasi dan CDK AWS - AWS Cloud Development Kit (AWS CDK) v2
Membangun IDsJalanUnik IDsLogis IDs

Ini adalah Panduan Pengembang AWS CDK v2. CDK v1 yang lebih lama memasuki pemeliharaan pada 1 Juni 2022 dan mengakhiri dukungan pada 1 Juni 2023.

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Pengidentifikasi dan CDK AWS

Saat membuat aplikasi AWS Cloud Development Kit (AWS CDK), Anda akan menggunakan banyak jenis pengenal dan nama. Untuk menggunakan AWS CDK secara efektif dan menghindari kesalahan, penting untuk memahami jenis pengidentifikasi.

Pengidentifikasi harus unik dalam ruang lingkup di mana mereka dibuat; mereka tidak perlu unik secara global dalam aplikasi AWS CDK Anda.

Jika Anda mencoba membuat pengenal dengan nilai yang sama dalam lingkup yang sama, AWS CDK akan melempar pengecualian.

Membangun IDs

Pengidentifikasi yang paling umum,id, adalah pengidentifikasi yang diteruskan sebagai argumen kedua saat membuat instance objek konstruksi. Pengidentifikasi ini, seperti semua pengidentifikasi, hanya perlu unik dalam lingkup di mana ia dibuat, yang merupakan argumen pertama ketika membuat instance objek konstruksi.

catatan

Tumpukan juga merupakan pengidentifikasi yang Anda gunakan untuk merujuknya dalam referensi AWS CDK CLI. id

Mari kita lihat contoh di mana kita memiliki dua konstruksi dengan identifier MyBucket di aplikasi kita. Yang pertama didefinisikan dalam lingkup tumpukan dengan pengenalStack1. Yang kedua didefinisikan dalam lingkup tumpukan dengan pengenalStack2. Karena mereka didefinisikan dalam cakupan yang berbeda, ini tidak menyebabkan konflik apa pun, dan mereka dapat hidup berdampingan di aplikasi yang sama tanpa masalah.

contoh
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");
    }
}

Jalan

Konstruksi dalam aplikasi AWS CDK membentuk hierarki yang berakar di kelas. App Kami mengacu pada koleksi IDs dari konstruksi tertentu, konstruksi induknya, kakek-neneknya, dan seterusnya ke akar pohon konstruksi, sebagai jalan.

AWS CDK biasanya menampilkan jalur di template Anda sebagai string. IDs Dari tingkat dipisahkan oleh garis miring, dimulai dari node segera di bawah App instance root, yang biasanya tumpukan. Misalnya, jalur dari dua sumber daya bucket Amazon S3 dalam contoh kode sebelumnya adalah Stack1/MyBucket dan. Stack2/MyBucket

Anda dapat mengakses jalur konstruksi apa pun secara terprogram, seperti yang ditunjukkan pada contoh berikut. Ini mendapatkan jalur myConstruct (ataumy_construct, seperti yang akan ditulis oleh pengembang Python). Karena IDs harus unik dalam ruang lingkup mereka dibuat, jalur mereka selalu unik dalam aplikasi AWS CDK.

contoh
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;

Unik IDs

AWS CloudFormation mengharuskan semua logis IDs dalam template menjadi unik. Karena itu, AWS CDK harus dapat menghasilkan pengenal unik untuk setiap konstruksi dalam aplikasi. Sumber daya memiliki jalur yang unik secara global (nama semua cakupan dari tumpukan ke sumber daya tertentu). Oleh karena itu, AWS CDK menghasilkan pengidentifikasi unik yang diperlukan dengan menggabungkan elemen jalur dan menambahkan hash 8 digit. (Hash diperlukan untuk membedakan jalur yang berbeda, seperti A/B/C danA/BC, yang akan menghasilkan AWS CloudFormation pengidentifikasi yang sama. AWS CloudFormation pengidentifikasi alfanumerik dan tidak dapat berisi garis miring atau karakter pemisah lainnya.) AWS CDK memanggil string ini ID unik dari konstruksi.

Secara umum, aplikasi AWS CDK Anda tidak perlu tahu tentang unik IDs. Namun, Anda dapat mengakses ID unik dari konstruksi apa pun secara terprogram, seperti yang ditunjukkan pada contoh berikut.

contoh
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);

Alamat adalah jenis lain dari pengidentifikasi unik yang secara unik membedakan sumber daya CDK. Berasal dari hash SHA-1 jalan, itu tidak dapat dibaca manusia. Namun, panjangnya yang konstan dan relatif pendek (selalu 42 karakter heksadesimal) membuatnya berguna dalam situasi di mana ID unik “tradisional” mungkin terlalu panjang. Beberapa konstruksi mungkin menggunakan alamat dalam AWS CloudFormation template yang disintesis, bukan ID unik. Sekali lagi, aplikasi Anda umumnya tidak perlu tahu tentang alamat konstruksinya, tetapi Anda dapat mengambil alamat konstruksi sebagai berikut.

contoh
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;

Logis IDs

Saat AWS CDK mensintesis aplikasi Anda ke dalam AWS CloudFormation template, CDK akan menghasilkan ID logis untuk setiap resource. AWS CloudFormation menggunakan logis IDs untuk mengidentifikasi sumber daya dalam template dan untuk melacaknya di seluruh penerapan. Memahami bagaimana logis IDs dihasilkan membantu Anda menghindari penggantian sumber daya yang tidak diinginkan saat Anda memfaktorkan ulang kode CDK Anda.

Seberapa logis IDs dihasilkan

AWS CDK menghasilkan logis IDs dari jalur konstruksi dengan menggunakan algoritma berikut:

  1. Gabungkan komponen jalur dari pohon konstruksi, tidak termasuk tumpukan itu sendiri.

  2. Menerapkan heuristik untuk meningkatkan keterbacaan (lihat heuristik komponen jalur ID logis).

  3. Tambahkan hash 8 karakter dari jalur lengkap untuk memastikan keunikan.

Format yang dihasilkan adalah:

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

Misalnya, tabel rute subnet pribadi VPC mungkin menghasilkan ID logis. VPCPrivateSubnet2RouteTable0A19E10E

Aturan berikut berlaku untuk pembuatan ID logis:

  • Panjang maksimalnya adalah 255 karakter. Bagian yang dapat dibaca manusia dibatasi pada 240 karakter.

  • Hash 8 karakter memastikan bahwa jalur seperti A/B/C dan A/BC — yang digabungkan ke string yang sama — menghasilkan logika yang berbeda. IDs

  • Sumber daya yang merupakan turunan langsung dari tumpukan (jalur komponen tunggal) menggunakan namanya secara langsung tanpa hash, selama namanya 255 karakter atau kurang.

Heuristik komponen jalur ID logis

AWS CDK menerapkan heuristik berikut ke komponen jalur ketika menghasilkan bagian logis yang dapat dibaca manusia. IDs

Default— dihapus seluruhnya

Jika komponen jalurDefault, CDK menghapusnya dari bagian yang dapat dibaca manusia dan input hash. Ini berarti bahwa membungkus konstruksi yang ada di dalam konstruksi baru — dan menamai konstruksi bagian dalam Default — menghasilkan ID logis yang sama persis dengan konstruksi terbuka asli. Ini adalah mekanisme kunci untuk memfaktorkan ulang kode datar dengan aman ke konstruksi tingkat yang lebih tinggi tanpa mengubah identitas sumber daya yang diterapkan.

Resource— tersembunyi dari bagian yang dapat dibaca manusia saja

Jika komponen jalurResource, CDK menghilangkannya dari bagian yang dapat dibaca manusia tetapi masih memasukkannya dalam perhitungan hash. Konstruksi L1 (CloudFormation) digunakan Resource sebagai ID konstruksi mereka berdasarkan konvensi. Ini membuat logis IDs lebih pendek tanpa kehilangan keunikan.

Duplikat komponen berurutan — deduplikasi

Jika nama komponen jalur sebelumnya diakhiri dengan nama komponen saat ini, CDK melewatkan komponen saat ini. Ini mencegah pengulangan berlebihan secara logis. IDs

Gunakan Default untuk mempertahankan logis IDs saat Anda memfaktorkan ulang

Saat Anda memfaktorkan ulang tumpukan datar ke konstruksi tingkat yang lebih tinggi, Anda dapat menggunakan Default sebagai ID konstruksi untuk sumber daya utama untuk mempertahankan ID logisnya. Ini AWS CloudFormation mencegah penggantian sumber daya selama penerapan.

Contoh berikut menunjukkan tumpukan dengan sumber daya yang didefinisikan secara langsung:

contoh
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
}

Jalur bucket adalahMyStack/DataBucket/Resource, yang menghasilkan ID logis dariDataBucket<hash>.

Anda dapat mengekstrak bucket ke dalam konstruksi tingkat yang lebih tinggi dan mempertahankan ID logis yang sama dengan memberi nama konstruksi bagian dalam: Default

contoh
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
}

Jalan ember itu sekarangMyStack/DataBucket/Default/Resource. Karena Default dihapus dari bagian yang dapat dibaca manusia dan input hash, ID logis tetap DataBucket<hash> — identik dengan aslinya.

penting

Anda hanya dapat memiliki satu anak dengan ID Default per lingkup konstruksi. Jika Anda membutuhkan banyak sumber daya pada tingkat yang sama, beri mereka deskriptif IDs. DefaultPola ini bekerja paling baik dengan konstruksi tanggung jawab tunggal yang memiliki satu sumber daya utama.

Pertimbangan dan batasan

Ingatlah hal-hal berikut ketika Anda bekerja dengan logis IDs:

  • Anda dapat menetapkan hanya satu anak per lingkup ID Default konstruksi.

  • Jika Anda mengubah ID konstruksi setelah penerapan, ID logis akan berubah, yang AWS CloudFormation menyebabkan penggantian sumber daya. Gunakan cdk diff untuk memverifikasi perubahan sebelum Anda menerapkan.

  • Untuk kasus di mana logis IDs telah berubah, Anda dapat menggunakan cdk refactor perintah untuk memetakan logis lama IDs ke yang baru. Untuk informasi selengkapnya, lihat Mempertahankan sumber daya yang diterapkan saat memfaktorkan ulang kode CDK.

  • Untuk informasi selengkapnya tentang bagaimana logis IDs muncul dalam template yang disintesis, lihat Generated logical IDs di AWS CloudFormation template Anda.

Stabilitas ID logis

Hindari mengubah ID logis sumber daya setelah dibuat. AWS CloudFormation mengidentifikasi sumber daya dengan ID logisnya. Oleh karena itu, jika Anda mengubah ID logis sumber daya, AWS CloudFormation membuat sumber daya baru dengan ID logis baru, lalu hapus yang sudah ada. Tergantung pada jenis sumber daya, ini dapat menyebabkan gangguan layanan, kehilangan data, atau keduanya.