AWS CDK での の使用 JavaScript - AWS Cloud Development Kit (AWS CDK) v2

これは AWS CDK v2 デベロッパーガイドです。古い CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS CDK での の使用 JavaScript

JavaScript は、 で完全にサポートされているクライアント言語 AWS CDK であり、安定していると見なされます。 AWS Cloud Development Kit (AWS CDK) で を操作するには、Node.js や Node Package Manager (npm) など、使い慣れたツール JavaScript を使用します。このガイドの例では NPM を使用していますが、必要に応じて Yarn を使用することもできます。 AWS コンストラクトライブラリで構成されるモジュールは、NPM リポジトリ npmjs.org を介して配布されます。

任意のエディタまたは IDE を使用できます。多くの AWS CDK デベロッパーは、Visual Studio Code (または同等のオープンソースVSCodium) を使用します。これは、 をうまくサポートしています JavaScript。

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 Toolkit をグローバルにインストールし (npm install -g aws-cdk)、提供されているコマンド例 ( などcdk synth) がこの前提に従うことを前提としています。このアプローチにより、CDK Toolkit を最新の状態に保つことが容易になり、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 Toolkit コマンドを実行する cdk ... npm 実行 cdk ... or npx aws-cdk ...

npx aws-cdk は、現在のプロジェクトにローカルにインストールされた CDK Toolkit のバージョンが存在する場合は、グローバルインストールにフォールバックします。グローバルインストールが存在しない場合、 は CDK Toolkit の一時コピーnpxをダウンロードして実行します。@ 構文を使用して任意のバージョンの CDK Toolkit を指定できます。 は をnpx aws-cdk@1.120 --version出力します1.120.0

ヒント

ローカル CDK Toolkit インストールで cdk コマンドを使用できるように、エイリアスを設定します。

macOS/Linux
alias cdk="npx aws-cdk"
Windows
doskey cdk=npx aws-cdk $*

AWS コンストラクトライブラリモジュールの管理

Node Package Manager (npm) を使用して、アプリケーションで使用する Construct Library AWS モジュールと、必要なその他のパッケージをインストールして更新します。(npm必要に応じて yarnの代わりに を使用できます。) は、それらのモジュールの依存関係npmも自動的にインストールします。

ほとんどの AWS CDK コンストラクトは、 という名前のメイン CDK パッケージにあります。これはaws-cdk-lib、 によって作成された新しいプロジェクトのデフォルトの依存関係ですcdk init。「実験 AWS 」 上位レベルのコンストラクトがまだ開発中のライブラリモジュールの構築は、 のように名前が付けられますaws-cdk-lib/SERVICE-NAME-alpha。サービス名には aws- プレフィックスが付いています。モジュールの名前がわからない場合は、NPM で検索します

注記

CDK API リファレンスにはパッケージ名も表示されます。

例えば、以下のコマンドは の実験モジュールをインストールします AWS CodeStar。

npm install @aws-cdk/aws-codestar-alpha

一部の サービスの コンストラクトライブラリのサポートは、複数の名前空間にあります。例えば、 以外にもaws-route53、Amazon Route 53 名前空間 、aws-route53-targetsaws-route53-patternsおよび が 3 つ追加されていますaws-route53resolver

プロジェクトの依存関係は で管理されますpackage.json。このファイルを編集して、依存関係の一部またはすべてを特定のバージョンにロックしたり、特定の条件下で新しいバージョンに更新したりできます。で指定したルールに従って、プロジェクトの NPM 依存関係を最新の許可されたバージョンに更新するにはpackage.json

npm update

では JavaScript、NPM を使用してインストールする場合と同じ名前でモジュールをコードにインポートします。アプリケーションに AWS CDK クラスをインポートしたり、ライブラリモジュール AWS を構築したりする場合は、次のプラクティスをお勧めします。これらのガイドラインに従うことで、コードを他の AWS CDK アプリケーションと一致させ、理解しやすくなります。

  • ES6-styleimportディレクティブではなくrequire()、 を使用します。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 に記録します。

必要に応じて、NPM の代わりに Yarn を使用できます。ただし、CDK は Yarn 2 plug-and-play のデフォルトモードである Yarn モードをサポートしていません。以下をプロジェクトの .yarnrc.yml ファイルに追加して、この機能をオフにします。

nodeLinker: node-modules

CDK アプリケーション

コマンドによって生成されるpackage.jsonファイルの例を次に示しますcdk init --language typescript。に対して生成されるファイルは類似 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サンプルファイルに示すように、 セクションpeerDependenciesdevDependenciesセクションを組み合わせて依存関係を指定します。

{ "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、テストに必要なツールとライブラリを指定します。オプションで ^ を使用して、それ以降の互換性のあるバージョンが許容できることを示します。ライブラリの互換性をアドバタイズする aws-cdk-libおよびその他の CDK パッケージの最小バージョンを正確に (^ または ~ なし) 指定します。この方法により、テストがそれらのバージョンに対して実行されるようになります。これにより、新しいバージョンでのみ見つかった機能を誤って使用すると、テストでその機能が検出される可能性があります。

警告

peerDependencies は NPM 7 以降によってのみ自動的にインストールされます。NPM 6 以前を使用している場合、または Yarn を使用している場合は、依存関係の依存関係を に含める必要がありますdevDependencies。そうしないと、インストールされず、未解決のピア依存関係に関する警告が表示されます。

依存関係のインストールと更新

次のコマンドを実行して、プロジェクトの依存関係をインストールします。

NPM
# Install the latest version of everything that matches the ranges in 'package.json' npm install # Install the same exact dependency versions as recorded in 'package-lock.json' npm ci
Yarn
# Install the latest version of everything that matches the ranges in 'package.json' yarn upgrade # Install the same exact dependency versions as recorded in 'yarn.lock' yarn install --frozen-lockfile

インストールされているモジュールを更新するには、前述の npm installおよび yarn upgrade コマンドを使用できます。どちらのコマンドも、 のパッケージnode_modulesを のルールを満たす最新バージョンに更新しますpackage.json。ただし、それらpackage.json自体は更新されません。新しい最小バージョンを設定することもできます。でパッケージをホストする場合 GitHub、 を自動的に更新するように Dependabot のバージョン更新を設定できますpackage.json。または、npm-check-updates を使用します。

重要

設計上、依存関係をインストールまたは更新すると、NPM と Yarn は、 で指定された要件を満たすすべてのパッケージの最新バージョンを選択しますpackage.json。これらのバージョンが (誤ってまたは意図的に) 壊れるリスクは常に存在します。プロジェクトの依存関係を更新した後、徹底的にテストします。

AWS CDK での idioms JavaScript

プロンプト

すべての AWS Construct Library クラスは、3 つの引数を使用してインスタンス化されます。コンストラクトが定義されているスコープ (コンストラクトツリーの親)、ID props は、コンストラクトが作成する AWS リソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドも引数に「属性のバンドル」パターンを使用します。

JavaScript オートコンプリートが適切な IDE またはエディタを使用すると、プロパティ名のスペルミスを回避できます。コンストラクトが encryptionKeysプロパティを期待していて、スペルが の場合encryptionkeys、コンストラクトをインスタンス化するときに、意図した値を渡していません。これにより、 プロパティが必要な場合は合成時にエラーが発生したり、オプションの場合はプロパティがサイレントに無視されたりする可能性があります。後者の場合、上書きしようとしているデフォルトの動作が発生することがあります。ここで特に注意してください。

AWS Construct Library クラスをサブクラスする場合 (または、props のような引数を取るメソッドを上書きする場合)、独自の使用のために追加のプロパティを受け入れることができます。これらの値は、親クラスまたはオーバーライドされたメソッドでは無視されます。このコードではアクセスされないため、通常、受信したすべてのプロパティを渡すことができます。

の将来のリリースでは、独自のプロパティに使用した名前で新しいプロパティが同時に追加 AWS CDK される可能性があります。継承チェーンで受け取った値を渡すと、予期しない動作が発生する可能性があります。プロパティを削除または に設定して、受信したプロパティの浅いコピーを渡す方が安全ですundefined。例:

super(scope, name, {...props, encryptionKeys: undefined});

または、プロパティに名前を付けて、プロパティがコンストラクトに属していることを明確にします。このようにして、将来の AWS CDK リリースでプロパティと衝突する可能性はほとんどありません。それらが多数ある場合は、適切に名前が付けられた単一の オブジェクトを使用してそれらを保持します。

欠落した値

オブジェクトの欠損値 ( など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、テストをより明示的なものにすることをお勧めします。ここでは、 nullundefinedが両方を同時にテストするのと等しいという事実を活用します。

let c = a == null ? a : a.b;
ヒント

Node.js 14.0 以降では、未定義の値の処理を簡素化できる新しい演算子がサポートされています。詳細については、「オプションの連鎖提案nullish 結合提案」を参照してください。

合成とデプロイ

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 コマンド)

で TypeScript の例の使用 JavaScript

TypeScript は、 の開発に使用する言語であり AWS CDK、アプリケーションの開発でサポートされる最初の言語であるため、利用可能な AWS CDK コード例は で記述されています TypeScript。これらのコード例は、 JavaScript デベロッパーにとって適切なリソースです。コードの TypeScript固有の部分を削除するだけで済みます。

TypeScript スニペットでは、新しい ECMAScript importexportキーワードを使用して他のモジュールからオブジェクトをインポートし、現在のモジュールの外部で使用できるようにオブジェクトを宣言することがよくあります。Node.js は、これらのキーワードのサポートを最新のリリースで開始しました。使用している Node.js のバージョン (またはサポートしたい) によっては、古い構文を使用するようにインポートとエクスポートを書き換えることができます。

インポートは、 require()関数への呼び出しに置き換えることができます。

TypeScript
import * as cdk from 'aws-cdk-lib'; import { Bucket, BucketPolicy } from 'aws-cdk-lib/aws-s3';
JavaScript
const cdk = require('aws-cdk-lib'); const { Bucket, BucketPolicy } = require('aws-cdk-lib/aws-s3');

エクスポートはmodule.exportsオブジェクトに割り当てることができます。

TypeScript
export class Stack1 extends cdk.Stack { // ... } export class Stack2 extends cdk.Stack { // ... }
JavaScript
class Stack1 extends cdk.Stack { // ... } class Stack2 extends cdk.Stack { // ... } module.exports = { Stack1, Stack2 }
注記

古いスタイルのインポートとエクスポートを使用する代わりに、 esmモジュールを使用します。

インポートとエクスポートがソートされたら、実際のコードを調べることができます。一般的に使用される次の TypeScript 機能を使用できます。

  • タイプ注釈

  • インターフェイス定義

  • タイプ変換/キャスト

  • アクセス修飾子

変数、クラスメンバー、関数パラメータ、および関数の戻り値の型には、型注釈を指定できます。変数、パラメータ、およびメンバーの場合、タイプはコロンと タイプの識別子に従って指定します。関数の戻り値は関数の署名に従い、コロンと 型で構成されます。

型注釈付きコードを に変換するには JavaScript、コロン と 型を削除します。クラスメンバーは、 に何らかの値が必要です JavaScript。 にタイプアノテーションのみundefinedがある場合は、 に設定します TypeScript。

TypeScript
var encrypted: boolean = true; class myStack extends cdk.Stack { bucket: s3.Bucket; // ... } function makeEnv(account: string, region: string) : object { // ... }
JavaScript
var encrypted = true; class myStack extends cdk.Stack { bucket = undefined; // ... } function makeEnv(account, region) { // ... }

では TypeScript、インターフェイスを使用して、必須プロパティとオプションプロパティのバンドル、およびそのタイプに名前を付けます。その後、インターフェイス名を型注釈として使用できます。例えば、関数の引数として使用するオブジェクトには、適切な型の必要なプロパティがある TypeScript ことを確認してください。

interface myFuncProps { code: lambda.Code, handler?: string }

JavaScript にはインターフェイス機能がないため、タイプアノテーションを削除したら、インターフェイス宣言を完全に削除します。

関数またはメソッドが汎用型 ( などobject) を返すが、その値をより汎用型のインターフェイスの一部ではないプロパティまたはメソッドにアクセスするために、より具体的な子型として扱う場合は、 を使用して値をキャスト TypeScript し、asその後にタイプまたはインターフェイス name. JavaScript doesn がサポート (または必要) するため、 asと次の識別子を削除します。あまりまれなキャスト構文では、タイプ名を角括弧 で囲む必要があります<LikeThis>。これらのキャストも削除する必要があります。

最後に、 はクラスのメンバーprivateのアクセス修飾子 publicprotected、および TypeScript をサポートします。のすべてのクラスメンバー JavaScript はパブリックです。これらの修飾子は、表示される場所に関係なく削除するだけです。

これらの TypeScript 機能を特定して削除する方法を知ることは、 に短い TypeScriptスニペットを適応させる上で大きな道のりです JavaScript。ただし、他の TypeScript 機能を使用する可能性が高いため、より長い TypeScript 例をこの方法で変換することは実用的でない場合があります。このような場合は、 を Sucrase することをお勧めします。コードが未定義の変数を使用する場合など、Supcrase は苦情tscを発しません。構文的に有効な場合、いくつかの例外を除いて、Scrase はそれを に変換できます JavaScript。これにより、単独では実行できないスニペットを変換する場合に特に役立ちます。

への移行 TypeScript

多くの JavaScript デベロッパーは、プロジェクトが大きくなり、複雑になるにつれて に移行TypeScriptします。 TypeScript は JavaScriptのスーパーセットです。すべての JavaScript コードは有効な TypeScript コードであるため、コードに変更を加える必要はなく、サポートされている AWS CDK 言語でもあります。タイプ注釈やその他の TypeScript 機能はオプションであり、値を見つけると AWS CDK アプリに追加できます。 TypeScript また、 では、オプションの連鎖や nullish 結合などの JavaScript 新機能を確定前に早期にアクセスでき、Node.js をアップグレードする必要はありません。

TypeScriptの「シェープベース」インターフェイスは、 オブジェクト内の必須プロパティとオプションプロパティ (およびそのタイプ) のバンドルを定義し、コードの記述中に一般的なミスを検出し、IDE が堅牢なオートコンプリートやその他のリアルタイムのコーディングアドバイスを簡単に提供できるようにします。

でコーディング TypeScript するには、 TypeScript コンパイラ を使用してアプリケーションをコンパイルするという追加のステップが必要ですtsc。一般的な AWS CDK アプリケーションの場合、コンパイルには最大で数秒かかります。

既存の JavaScript AWS CDK アプリケーションを に移行する最も簡単な方法は TypeScript 、 を使用して新しい TypeScript プロジェクトを作成しcdk init app --language typescript、ソースファイル (および AWS Lambda 関数ソースコードなどのアセットなど、その他の必要なファイル) を新しいプロジェクトにコピーすることです。 JavaScript ファイルの名前を で終わるように変更.tsし、 で開発を開始します TypeScript。