これは AWS CDK v2 デベロッパーガイドです。古い CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
AWS CDK での の使用 TypeScript
TypeScript は、 で完全にサポートされているクライアント言語 AWS Cloud Development Kit (AWS CDK) であり、安定していると見なされます。 AWS CDK で を操作するには、Microsoft の TypeScript コンパイラ (tsc
)、Node.jsnpm
。このガイドの例では NPM を使用していますが、必要に応じて Yarn
任意のエディタまたは IDE を使用できます。多くの AWS CDK デベロッパーは、Visual Studio Code
トピック
の開始方法 TypeScript
を使用するには AWS CDK、 AWS アカウントと認証情報が必要であり、Node.js と AWS CDK Toolkit がインストールされている必要があります。の開始方法 AWS CDK を参照してください。
また、 TypeScript それ自体 (バージョン 3.8 以降) も必要です。まだ持っていない場合は、 を使用してインストールできますnpm
。
npm install -g typescript
注記
アクセス許可エラーが発生し、システムで管理者アクセス権がある場合は、 を試してくださいsudo npm install -g typescript
。
通常の を TypeScript 最新の状態に保つnpm update -g typescript
。
注記
サードパーティー言語の廃止: 言語バージョンは、ベンダーまたはコミュニティによって共有される EOL (サポート終了) までのみサポートされ、事前通知により変更される可能性があります。
「プロジェクトの作成」
空のディレクトリcdk init
で を呼び出して、新しい AWS CDK プロジェクトを作成します。--language
オプションを使用して、 を指定しますtypescript
。
mkdir my-project cd my-project cdk init app --language typescript
プロジェクトを作成すると、aws-cdk-lib
モジュールとその依存関係もインストールされます。
cdk init
は、プロジェクトフォルダの名前を使用して、クラス、サブフォルダ、ファイルなど、プロジェクトのさまざまな要素に名前を付けます。フォルダ名のハイフンはアンダースコアに変換されます。ただし、名前は TypeScript 識別子の形式に従う必要があります。例えば、数字で開始したり、スペースを含めたりしないでください。
ローカル tsc
と の使用 cdk
ほとんどの場合、このガイドでは、 TypeScript と CDK Toolkit をグローバルにインストールし (npm install -g typescript aws-cdk
)、提供されているコマンド例 ( などcdk synth
) がこの前提に従うことを前提としています。このアプローチにより、両方のコンポーネントを最新の状態に保つことが容易になります。両方のコンポーネントが下位互換性に対して厳格なアプローチを採用するため、常に最新バージョンを使用するリスクは一般的にほとんどありません。
一部の チームでは、 TypeScript コンパイラや CDK Toolkit などのツールを含め、各プロジェクト内のすべての依存関係を指定したいと考えています。この方法により、これらのコンポーネントを特定のバージョンに固定し、チーム (および CI/CD 環境) のすべてのデベロッパーがそれらのバージョンを正確に使用できるようになります。これにより、変更の原因がなくなり、ビルドとデプロイの一貫性と繰り返し性が向上します。
CDK には TypeScript 、プロジェクトテンプレートの に TypeScript と CDK Toolkit の両方の依存関係が含まれているためpackage.json
、このアプローチを使用する場合は、プロジェクトを変更する必要はありません。必要なのは、アプリケーションの構築とコマンドの発行に少し異なるcdk
コマンドを使用することだけです。
操作 | グローバルツールを使用する | ローカルツールを使用する |
---|---|---|
プロジェクトを初期化する | cdk init --language typescript |
npx aws-cdk init --language typescript |
ビルド | tsc |
npm run build |
CDK Toolkit コマンドを実行する | cdk ... |
npm run cdk ... or npx aws-cdk ... |
npx aws-cdk
は、現在のプロジェクトにローカルにインストールされた CDK Toolkit のバージョンが存在する場合は、グローバルインストールにフォールバックします。グローバルインストールが存在しない場合、 は CDK Toolkit の一時コピーnpx
をダウンロードして実行します。@
構文を使用して任意のバージョンの CDK Toolkit を指定できます。 は をnpx aws-cdk@2.0 --version
出力します2.0.0
。
ヒント
ローカル CDK Toolkit インストールで cdk
コマンドを使用できるように、エイリアスを設定します。
AWS コンストラクトライブラリモジュールの管理
Node Package Manager (npm
) を使用して、アプリケーションで使用する Construct Library AWS モジュールと、必要なその他のパッケージをインストールして更新します。(npm
必要に応じて yarn
の代わりに を使用できます。) は、それらのモジュールの依存関係も自動的にnpm
インストールします。
ほとんどの AWS CDK コンストラクトは、 という名前のメイン CDK パッケージにあります。これはaws-cdk-lib
、 によって作成された新しいプロジェクトのデフォルトの依存関係ですcdk init。「実験 AWS 」 上位レベルのコンストラクトがまだ開発中のライブラリモジュールの構築は、 のように名前が付けられます@aws-cdk/
。サービス名には aws- プレフィックスが付いています。モジュールの名前がわからない場合は、NPM で検索しますSERVICE-NAME
-alpha
注記
CDK API リファレンスにはパッケージ名も表示されます。
例えば、以下のコマンドは の実験モジュールをインストールします AWS CodeStar。
npm install @aws-cdk/aws-codestar-alpha
一部の サービスの コンストラクトライブラリのサポートは、複数の名前空間にあります。例えば、 以外にもaws-route53
、Amazon Route 53 名前空間 、aws-route53-targets
、aws-route53-patterns
および が 3 つ追加されていますaws-route53resolver
。
プロジェクトの依存関係は で管理されますpackage.json
。このファイルを編集して、依存関係の一部またはすべてを特定のバージョンにロックしたり、特定の条件下で新しいバージョンに更新したりできます。で指定したルールに従って、プロジェクトの NPM 依存関係を最新の許可されたバージョンに更新するにはpackage.json
:
npm update
では TypeScript、NPM を使用してインストールする場合と同じ名前でモジュールをコードにインポートします。アプリケーションに AWS CDK クラスをインポートしたり、ライブラリモジュール AWS を構築したりする場合は、次のプラクティスをお勧めします。これらのガイドラインに従うことで、コードを他の AWS CDK アプリケーションと一致させ、理解しやすくなります。
-
ではなく、ES6-style
import
ディレクティブを使用しますrequire()
。 -
通常、個々のクラスを からインポートします
aws-cdk-lib
。import { App, Stack } from 'aws-cdk-lib';
-
から多数のクラスが必要な場合は
aws-cdk-lib
、個々のクラスをインポートcdk
する代わりに、 の名前空間エイリアスを使用できます。両方を実行しないでください。import * as cdk from 'aws-cdk-lib';
-
通常、短い名前空間エイリアスを使用して AWS サービスコンストラクトをインポートします。
import { aws_s3 as s3 } from 'aws-cdk-lib';
での依存関係の管理 TypeScript
TypeScript CDK プロジェクトでは、依存関係はプロジェクトのメインディレクトリの package.json
ファイルで指定されます。コア AWS CDK モジュールは、 という 1 つのNPMパッケージにありますaws-cdk-lib
。
を使用してパッケージをインストールするとnpm install、NPM はパッケージを package.json
に記録します。
必要に応じて、NPM の代わりに Yarn を使用できます。ただし、CDK は Yarn 2 plug-and-play のデフォルトモードである Yarn モードをサポートしていません。以下をプロジェクトの .yarnrc.yml
ファイルに追加して、この機能をオフにします。
nodeLinker: node-modules
CDK アプリケーション
cdk init --language typescript
コマンドによって生成されるpackage.json
ファイルの例を次に示します。
{ "name": "my-package", "version": "0.1.0", "bin": { "my-package": "bin/my-package.js" }, "scripts": { "build": "tsc", "watch": "tsc -w", "test": "jest", "cdk": "cdk" }, "devDependencies": { "@types/jest": "^26.0.10", "@types/node": "10.17.27", "jest": "^26.4.2", "ts-jest": "^26.2.0", "aws-cdk": "2.16.0", "ts-node": "^9.0.0", "typescript": "~3.9.7" }, "dependencies": { "aws-cdk-lib": "2.16.0", "constructs": "^10.0.0", "source-map-support": "^0.5.16" } }
デプロイ可能な CDK アプリケーションの場合、 の dependencies
セクションで を指定aws-cdk-lib
する必要がありますpackage.json
。キャレット (^) バージョン番号指定子を使用すると、同じメジャーバージョン内にある限り、指定したバージョンよりも新しいバージョンを受け入れるように指定できます。
実験的なコンストラクトの場合は、変更される可能性のある APIs を持つアルファコンストラクトライブラリモジュールの正確なバージョンを指定します。これらのモジュールの新しいバージョンでは、アプリが破損する API の変更が発生する可能性があるため、^ または ~ を使用しないでください。
の devDependencies
セクションで、アプリケーションのテストに必要なライブラリとツールのバージョン (jest
テストフレームワークなど) を指定しますpackage.json
。オプションで、^ を使用して、新しい互換性のあるバージョンが許容可能であることを指定します。
サードパーティーのコンストラクトライブラリ
コンストラクトライブラリを開発している場合は、次のpackage.json
サンプルファイルに示すように、 セクションpeerDependencies
と devDependencies
セクションを組み合わせて依存関係を指定します。
{ "name": "my-package", "version": "0.0.1", "peerDependencies": { "aws-cdk-lib": "^2.14.0", "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha", "constructs": "^10.0.0" }, "devDependencies": { "aws-cdk-lib": "2.14.0", "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha", "constructs": "10.0.0", "jsii": "^1.50.0", "aws-cdk": "^2.14.0" } }
ではpeerDependencies
、キャレット (^) を使用して、ライブラリが動作aws-cdk-lib
する の最小バージョンを指定します。これにより、さまざまな CDK バージョンとのライブラリの互換性が最大化されます。変更される可能性のある APIs を含む alpha construct ライブラリモジュールの正確なバージョンを指定します。peerDependencies
を使用すると、ツリー内のすべての CDK ライブラリのコピーが 1 node_modules
つだけになります。
でdevDependencies
、テストに必要なツールとライブラリを指定します。オプションで ^ を使用して、それ以降の互換性のあるバージョンが許容できることを示します。ライブラリの互換性をアドバタイズする aws-cdk-lib
およびその他の CDK パッケージの最小バージョンを正確に (^ または ~ なし) 指定します。この方法により、テストがそれらのバージョンに対して実行されるようになります。これにより、新しいバージョンでのみ見つかった機能を誤って使用すると、テストでその機能をキャッチできます。
警告
peerDependencies
は NPM 7 以降によってのみ自動的にインストールされます。NPM 6 以前を使用している場合、または Yarn を使用している場合は、依存関係の依存関係を に含める必要がありますdevDependencies
。そうしないと、インストールされず、未解決のピア依存関係に関する警告が表示されます。
依存関係のインストールと更新
次のコマンドを実行して、プロジェクトの依存関係をインストールします。
インストールされているモジュールを更新するには、前述の npm installおよび yarn upgrade コマンドを使用できます。どちらのコマンドも、 のパッケージnode_modules
を、 のルールを満たす最新バージョンに更新しますpackage.json
。ただし、それらpackage.json
自体は更新されません。新しい最小バージョンを設定することもできます。でパッケージをホストする場合 GitHub、 を自動的に更新するように Dependabot のバージョンpackage.json
。または、npm-check-updates
重要
設計上、依存関係をインストールまたは更新する場合、NPM と Yarn は、 で指定された要件を満たすすべてのパッケージの最新バージョンを選択しますpackage.json
。これらのバージョンが (誤ってまたは意図的に) 壊れるリスクは常に存在します。プロジェクトの依存関係を更新した後、徹底的にテストします。
AWS CDK での idioms TypeScript
プロンプト
すべての AWS Construct Library クラスは、コンストラクトが定義されているスコープ (コンストラクトツリーの親)、ID 、props の 3 つの引数を使用してインスタンス化されます。引数プロパティは、コンストラクトが作成する AWS リソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドも引数に「属性のバンドル」パターンを使用します。
では TypeScript、 の形状props
は、必須およびオプションの引数とそのタイプを示すインターフェイスを使用して定義されます。このようなインターフェイスは、引props
数の種類ごとに定義され、通常は単一のコンストラクトまたはメソッドに固有です。例えば、バケットコンストラクト ( 内aws-cdk-lib/aws-s3 module
) は、 BucketPropsインターフェイスに準拠するprops
引数を指定します。
プロパティがそれ自体がオブジェクトである場合、例えば の websiteRedirect プロパティBucketProps
の場合、そのオブジェクトには、その形状が準拠する必要がある独自のインターフェイスがあります。この場合は ですRedirectTarget。
AWS Construct Library クラスをサブクラスする (または、props のような引数を取るメソッドを上書きする) 場合は、既存のインターフェイスから継承して、コードに必要な新しいpropsを指定する新しいインターフェイスを作成できます。親クラスまたは基本メソッドを呼び出す場合、通常、受信した props 引数全体を渡すことができます。これは、 オブジェクトで指定された属性は無視されますが、インターフェイスで指定されていないためです。
の将来のリリースでは、独自のプロパティに使用した名前で新しいプロパティが同時に追加 AWS CDK される可能性があります。継承チェーンで受け取った値を渡すと、予期しない動作が発生する可能性があります。プロパティを削除または に設定して、受信したプロパティの浅いコピーを渡す方が安全ですundefined
。例:
super(scope, name, {...props, encryptionKeys: undefined});
または、プロパティに名前を付けて、プロパティがコンストラクトに属していることを明確にします。このようにして、将来の AWS CDK リリースでプロパティと衝突する可能性はほとんどありません。それらが多数ある場合は、適切に名前が付けられた単一の オブジェクトを使用してそれらを保持します。
欠落した値
オブジェクト (props など) の欠損値は、 undefined
の値を持ちます TypeScript。言語のバージョン 3.7 では、これらの値の操作を簡素化する演算子が導入されました。これにより、未定義の値に達したときに、デフォルトと「短い回路」チェーンを簡単に指定できます。これらの機能の詳細については、TypeScript 「3.7 リリースノート
構築、合成、デプロイ
通常、アプリケーションを構築して実行するときは、プロジェクトのルートディレクトリにいる必要があります。
Node.js TypeScript を直接実行することはできません。代わりに、コンパイラ JavaScript を使用して TypeScriptアプリケーションを に変換しますtsc
。その後、結果の JavaScript コードが実行されます。
は、アプリの実行に必要なたびに、これ AWS CDK を自動的に行います。ただし、エラーを確認してテストを実行するには、手動でコンパイルすると便利です。 TypeScript アプリを手動でコンパイルするには、 を発行しますnpm run build
。視聴モードに入るnpm run watch
と問題が発生することもあります。この TypeScriptモードでは、ソースファイルに変更を保存するたびに、コンパイラが自動的にアプリを再構築します。
AWS CDK アプリケーションで定義されたスタックは、合成して個別にデプロイすることも、以下のコマンドを使用してまとめてデプロイすることもできます。通常、プロジェクトを発行するときは、プロジェクトのメインディレクトリにいる必要があります。
-
cdk synth
: AWS CDK アプリケーションの 1 つ以上のスタックから AWS CloudFormation テンプレートを合成します。 -
cdk deploy
: AWS CDK アプリケーション内の 1 つ以上のスタックによって定義されたリソースを にデプロイします AWS。
1 つのコマンドで合成またはデプロイする複数のスタックの名前を指定できます。アプリケーションが 1 つのスタックのみを定義している場合は、指定する必要はありません。
cdk synth # app defines single stack cdk deploy Happy Grumpy # app defines two or more stacks; two are deployed
また、ワイルドカード * (任意の文字数) と ? (任意の 1 文字) を使用して、パターンでスタックを識別することもできます。ワイルドカードを使用する場合は、パターンを引用符で囲みます。そうしないと、シェルは AWS CDK Toolkit に渡す前に、現在のディレクトリ内のファイルの名前に拡張しようとする可能性があります。
cdk synth "Stack?" # Stack1, StackA, etc. cdk deploy "*Stack" # PipeStack, LambdaStack, etc.
ヒント
デプロイする前にスタックを明示的に合成する必要はありません。 はこのステップcdk deploy
を実行して、最新のコードがデプロイされることを確認します。
cdk
コマンドの完全なドキュメントについては、「」を参照してくださいAWS CDK ツールキット (cdk コマンド)。