これは AWS CDK v2 デベロッパーガイドです。古い CDKv1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
AWS CDK での の操作 JavaScript
JavaScript は で完全にサポートされているクライアント言語であり AWS CDK 、安定していると見なされます。 AWS Cloud Development Kit (AWS CDK) で を操作すると、Node.js npm
) などの使い慣れたツール JavaScript が使用されます。このガイドの例では を使用していますが、必要に応じて Yarn
任意のエディタまたは を使用できますIDE。多くの AWS CDK デベロッパーは、Visual Studio Code
トピック
JavaScript の開始方法
を使用するには AWS CDK、 AWS アカウントと認証情報が必要で、Node.js と AWS CDK Toolkit がインストールされている必要があります。「の開始方法 AWS CDK」を参照してください。
JavaScript AWS CDK アプリケーションでは、これら以外の追加の前提条件は必要ありません。
注記
サードパーティー言語の非推奨: 言語バージョンは、ベンダーまたはコミュニティによって共有される EOL (サポート終了) までのみサポートされ、事前通知により変更される可能性があります。
「プロジェクトの作成」
空のディレクトリcdk init
で を呼び出して、新しい AWS CDK プロジェクトを作成します。--language
オプションを使用して を指定しますjavascript
。
mkdir my-project cd my-project cdk init app --language javascript
プロジェクトを作成すると、aws-cdk-lib
モジュールとその依存関係もインストールされます。
cdk init
は、プロジェクトフォルダの名前を使用して、クラス、サブフォルダ、ファイルなど、プロジェクトのさまざまな要素に名前を付けます。フォルダ名のハイフンはアンダースコアに変換されます。ただし、名前は JavaScript 識別子の形式に従う必要があります。例えば、数字で始まる、またはスペースを含むべきではありません。
ローカルの使用 cdk
ほとんどの場合、このガイドでは、 CDK ツールキットをグローバルにインストールし (npm install -g aws-cdk
)、提供されたコマンド例 ( などcdk synth
) がこの前提に従っていることを前提としています。このアプローチにより、CDKToolkit を最新の状態に保つことが容易になり、 CDKは下位互換性に厳格なアプローチを採用しているため、常に最新バージョンを使用するリスクは一般的にほとんどありません。
一部のチームは、 CDK Toolkit などのツールを含め、各プロジェクト内のすべての依存関係を指定したいと考えています。この方法では、このようなコンポーネントを特定のバージョンに固定し、チーム (および CI/CD 環境) のすべてのデベロッパーがそれらのバージョンを正確に使用できるようにします。これにより、変更元の可能性がなくなり、ビルドとデプロイの一貫性と反復性が向上します。
CDK には、 JavaScript プロジェクトテンプレートの に CDK Toolkit の依存関係が含まれているためpackage.json
、このアプローチを使用する場合は、プロジェクトを変更する必要はありません。必要なのは、アプリケーションの構築とコマンドの発行に少し異なるcdk
コマンドを使用することだけです。
操作 | グローバルCDKツールキットを使用する | ローカルCDKツールキットを使用する |
---|---|---|
プロジェクトの初期化 | cdk init --language javascript |
npx aws-cdk init --language javascript |
CDK ツールキットの実行コマンド | cdk ... |
npm run cdk ... 、または npx aws-cdk ... |
npx aws-cdk
は、現在のプロジェクトにローカルにインストールされている CDK Toolkit のバージョンが存在する場合は、グローバルインストールにフォールバックします。グローバルインストールが存在しない場合、 は CDK Toolkit の一時コピーnpx
をダウンロードして実行します。Toolkit の任意のバージョンは、 という@
構文CDKを使用して指定できます。 は をnpx aws-cdk@1.120 --version
出力します1.120.0
。
ヒント
ローカルの CDK Toolkit インストールで cdk
コマンドを使用できるようにエイリアスを設定します。
AWS 構築ライブラリモジュールの管理
Node Package Manager (npm
) を使用して、アプリケーションで使用する AWS 構築ライブラリモジュール、および必要なその他のパッケージをインストールおよび更新します。(npm
必要に応じて yarn
の代わりに を使用できます。) は、それらのモジュールの依存関係npm
も自動的にインストールします。
ほとんどの AWS CDK コンストラクトは、 という名前のメインCDKパッケージにあります。これはaws-cdk-lib
、 によって作成された新しいプロジェクトのデフォルトの依存関係ですcdk init。上位レベルの AWS コンストラクトがまだ開発中の「実験」コンストラクトライブラリモジュールは、 のように名前が付けられますaws-cdk-lib/
。サービス名には aws- プレフィックスが付いています。モジュールの名前がわからない場合は、 で検索しますNPMSERVICE-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
では JavaScript、 を使用してインストールするのと同じ名前でモジュールをコードにインポートしますNPM。アプリケーションに AWS CDK クラスと AWS コンストラクトライブラリモジュールをインポートするときは、次のプラクティスをお勧めします。これらのガイドラインに従うことで、コードが他の AWS CDK アプリケーションと一貫性を持ち、理解しやすくなります。
-
スタイルの
import
ディレクティブではなくrequire()
、 ES6を使用します。Node.js の古いバージョンはES6インポートをサポートしていないため、古い構文を使用すると、より広く互換性があります。(実際にES6インポートを使用する場合は、esmを使用して、プロジェクトがサポートされているすべてのバージョンの Node.js と互換性があることを確認してください)。 -
通常、 から個々のクラスをインポートします
aws-cdk-lib
。const { App, Stack } = require('aws-cdk-lib');
-
から多数のクラスが必要な場合は
aws-cdk-lib
、個々のクラスをインポートcdk
する代わりに、 の名前空間エイリアスを使用できます。両方は避けてください。const cdk = require('aws-cdk-lib');
-
通常、短い名前空間エイリアスを使用して AWS ライブラリの構築 をインポートします。
const { s3 } = require('aws-cdk-lib/aws-s3');
での依存関係の管理 JavaScript
JavaScript CDK プロジェクトでは、依存関係はプロジェクトのメインディレクトリの package.json
ファイルで指定されます。コア AWS CDK モジュールは、 という 1 つのNPMパッケージにありますaws-cdk-lib
。
を使用してパッケージをインストールするとnpm install、 NPMはパッケージpackage.json
を自動的に に記録します。
必要に応じて、 の代わりに Yarn を使用できますNPM。ただし、 CDKは Yarn の plug-and-play モードをサポートしていません。これは Yarn 2 のデフォルトモードです。プロジェクトの .yarnrc.yml
ファイルに以下を追加して、この機能をオフにします。
nodeLinker: node-modules
CDK アプリケーション
以下は、 cdk init --language typescript
コマンドによって生成されたpackage.json
ファイルの例です。用に生成されたファイルは JavaScript 類似しており、 TypeScript関連のエントリはありません。
{ "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可能性のある正確なバージョンを指定します。peerDependencies
を使用すると、ツリー内のすべてのCDKライブラリのコピーが 1 node_modules
つだけになります。
でdevDependencies
、テストに必要なツールとライブラリを指定します。オプションで ^ を指定して、それ以降の互換性のあるバージョンが許容できることを示します。ライブラリをアドバタイズするパッケージと互換性があるCDKパッケージの最小バージョンを正確に (^ aws-cdk-lib
または ~ なし) 指定します。この方法では、テストがそれらのバージョンに対して実行されることが保証されます。これにより、新しいバージョンでのみ見つかった機能を誤って使用した場合、テストで検出される可能性があります。
警告
peerDependencies
は 7 NPM 以降でのみ自動的にインストールされます。NPM 6 以前を使用している場合、または Yarn を使用している場合は、依存関係の依存関係を に含める必要がありますdevDependencies
。そうしないと、インストールされず、未解決のピア依存関係に関する警告が表示されます。
依存関係のインストールと更新
次のコマンドを実行して、プロジェクトの依存関係をインストールします。
インストールされているモジュールを更新するには、前述の npm installおよび yarn upgrade コマンドを使用できます。どちらのコマンドも、 のパッケージnode_modules
を、 のルールを満たす最新バージョンに更新しますpackage.json
。ただし、それらpackage.json
自体は更新されません。これは、新しい最小バージョンを設定するために行うことをお勧めします。でパッケージをホストする場合 GitHub、 を自動的に更新するように Dependabot のバージョンpackage.json
。または、npm-check-updates
重要
設計上、依存関係をインストールまたは更新するときに、Yarn NPM は で指定された要件を満たすすべてのパッケージの最新バージョンを選択しますpackage.json
。これらのバージョンが (誤って、または意図的に) 壊れるリスクが常にあります。プロジェクトの依存関係を更新した後、徹底的にテストします。
AWS CDK のイディオム JavaScript
プロンプト
すべての AWS Construct Library クラスは、3 つの引数を使用してインスタンス化されます。つまり、コンストラクトが定義されているスコープ (コンストラクトツリー内の親)、ID が 、プロップ です。これは、コンストラクトが作成する AWS リソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドでは、引数に「属性のバンドル」パターンも使用します。
JavaScript オートコンプリートが適切な IDEまたはエディタを使用すると、プロパティ名のスペルミスを回避できます。コンストラクトが encryptionKeys
プロパティを想定していて、スペルが の場合encryptionkeys
、コンストラクトをインスタンス化するときに、意図した値を渡していません。これにより、 プロパティが必要な場合は合成時にエラーが発生し、オプションの場合はプロパティがサイレントに無視される可能性があります。後者の場合、上書きするデフォルトの動作が発生することがあります。ここで特に注意してください。
AWS Construct Library クラスをサブクラスする場合 (または props のような引数を取るメソッドを上書きする場合)、独自の使用のために追加のプロパティを受け入れることをお勧めします。これらの値は、親クラスまたはオーバーライドされたメソッドによって無視されます。これは、そのコードではアクセスされないため、通常、受信したすべてのpropsを渡すことができるためです。
の将来のリリースでは、独自のプロパティに使用した名前の新しいプロパティが同時に追加 AWS CDK される可能性があります。継承チェーンで受け取る値を渡すと、予期しない動作が発生する可能性があります。プロパティを削除または に設定して受け取った小幕の浅いコピーを渡す方が安全ですundefined
。例:
super(scope, name, {...props, encryptionKeys: undefined});
または、プロパティに名前を付けて、プロパティがコンストラクトに属していることが明確になるようにします。これにより、今後の AWS CDK リリースでプロパティと衝突する可能性は低くなります。それらが多数ある場合は、適切に名前が付けられたオブジェクトを 1 つ使用して保持します。
欠落した値
オブジェクトの欠損値 ( などprops
) は、 undefined
の値を持ちます JavaScript。これらに対処するには、通常の手法が適用されます。例えば、未定義の値のプロパティにアクセスするための一般的なイディオムは次のとおりです。
// a may be undefined, but if it is not, it may have an attribute b // c is undefined if a is undefined, OR if a doesn't have an attribute b let c = a && a.b;
ただし、 以外の「falsy」値を持つa
可能性がある場合はundefined
、テストをより明確にすることをお勧めします。ここでは、 null
と undefined
が両方を同時にテストするのと同じであるという事実を利用します。
let c = a == null ? a : a.b;
ヒント
Node.js 14.0 以降では、未定義の値の処理を簡素化できる新しい演算子がサポートされています。詳細については、オプションの連鎖
で TypeScript の例の使用 JavaScript
TypeScript
TypeScript スニペットでは、新しい キーワードECMAScriptimport
と export
キーワードを使用して、他のモジュールからオブジェクトをインポートし、現在のモジュール外で使用可能にするオブジェクトを宣言することがよくあります。Node.js は、最新リリースでこれらのキーワードのサポートを開始しました。使用している (またはサポートする) Node.js のバージョンに応じて、古い構文を使用するようにインポートとエクスポートを書き換えることができます。
インポートは、require()
関数の呼び出しに置き換えることができます。
エクスポートは module.exports
オブジェクトに割り当てることができます。
注記
古い形式のインポートとエクスポートを使用する代わりに、 esm
インポートとエクスポートをソートしたら、実際のコードを掘り下げることができます。一般的に使用される以下の TypeScript 機能を実行できます。
-
タイプアノテーション
-
インターフェイス定義
-
型変換/キャスト
-
アクセス修飾子
型注釈は、変数、クラスメンバー、関数パラメータ、および関数戻り型に対して提供できます。変数、パラメータ、およびメンバーの場合、タイプはコロンと タイプの識別子に従って指定されます。関数の戻り値は関数の署名に従い、コロンと タイプで構成されます。
型注釈付きコードを に変換するには JavaScript、コロンと型を削除します。クラスメンバーは、 に何らかの値が必要です JavaScript。 に型注釈のみundefined
がある場合は、 に設定します TypeScript。
では TypeScript、インターフェイスを使用して、必須プロパティとオプションのプロパティ、およびそのタイプに名前を付けます。その後、インターフェイス名を型注釈として使用できます。 TypeScript は、例えば、関数の引数として使用するオブジェクトに、適切な型の必要なプロパティがあることを確認します。
interface myFuncProps { code: lambda.Code, handler?: string }
JavaScript にはインターフェイス機能がないため、タイプアノテーションを削除したら、インターフェイス宣言を完全に削除します。
関数またはメソッドが汎用型 ( などobject
) を返すが、その値をより一般的な型のインターフェイスの一部ではないプロパティまたはメソッドにアクセスするためのより具体的な子型として扱う場合、 を使用して値をキャストし、as
その後にタイプまたはインターフェイス name をキャスト TypeScript します。 はこれをサポート JavaScript しない (または必要としない) ため、 as
と次の識別子を削除します。あまり一般的ではないキャスト構文は、括弧 で囲まれたタイプ名を使用することです<LikeThis>
。これらのキャストも削除する必要があります。
最後に、 は、クラスのメンバーprivate
のアクセス修飾子 public
、protected
、および TypeScript をサポートします。のすべてのクラスメンバー JavaScript はパブリックです。これらの修飾子は、表示される場所であればどこでも削除できます。
これらの TypeScript 機能を特定して削除する方法は、ショート TypeScriptスニペットを に適応させるのに大きく役立ちます JavaScript。ただし、他の TypeScript 機能を使用する可能性が高いため、この方法で長い TypeScript 例を変換することは実用的ではない場合があります。このような状況では、 を Sucrase tsc
を申し立てません。構文的に有効な場合は、いくつかの例外を除いて、Sucrase はそれを に変換できます JavaScript。これにより、単独では実行できないスニペットを変換するのに特に役立ちます。
への移行 TypeScript
多くの JavaScript デベロッパーTypeScript
TypeScriptの「シェープベース」インターフェイスは、オブジェクト内の必須プロパティとオプションのプロパティ (およびそのタイプ) のバンドルを定義し、コードの記述中に一般的なミスを検出し、 が堅牢なオートコンプリートやその他のリアルタイムのコーディングアドバイスを簡単にIDE提供できるようにします。
でのコーディング TypeScript には、 TypeScript コンパイラ を使用してアプリケーションをコンパイルするという追加のステップが含まれますtsc
。一般的な AWS CDK アプリケーションの場合、コンパイルには最大で数秒かかります。
既存の JavaScript AWS CDK アプリケーションを に移行する最も簡単な方法は、 を使用して新しい TypeScript プロジェクト TypeScript を作成しcdk init app --language typescript
、ソースファイル (および AWS Lambda 関数のソースコードなどのアセットなどのその他の必要なファイル) を新しいプロジェクトにコピーすることです。 JavaScript ファイルの名前を で終わるように変更.ts
し、 で開発を開始します TypeScript。