これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。 翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # TypeScript で AWS CDK を使用する TypeScript は AWS Cloud Development Kit (AWS CDK) で完全にサポートされているクライアント言語であり、安定していると考えられています。TypeScript で AWS CDK を使用すると、Microsoft の TypeScript コンパイラ (`tsc`)、[Node.js](https://nodejs.org/)、Node Package Manager (`npm`) などの使い慣れたツールを利用できます。このガイドの例では NPM を使用していますが、必要に応じて [Yarn](https://yarnpkg.com/) を使用することもできます。AWS コンストラクトライブラリを構成するモジュールは、NPM リポジトリの [npmjs.org](https://www.npmjs.com/) を介して配布されます。 任意のエディタまたは IDE を使用できます。多くの AWS CDK デベロッパーは [Visual Studio Code](https://code.visualstudio.com/) (または同等のオープンソースの [VSCodium](https://vscodium.com/)) を使用しており、TypeScript のサポートが良好です。 ## TypeScript の使用の開始 AWS CDK を使用するには、AWS アカウントおよび認証情報を持ち、Node.js および AWS CDK Toolkit がインストールされている必要があります。「[AWS CDK の使用を開始する](getting-started.md)」を参照してください。 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 ``` プロジェクトを作成すると、[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) モジュールおよびその依存関係もインストールされます。 `cdk init` はプロジェクトフォルダの名前を使用し、クラス、サブフォルダ、ファイルなどのプロジェクトのさまざまな要素に名前を付けます。フォルダ名に含まれるハイフンはアンダースコアに変換されます。ただし、それ以外の場合、名前は TypeScript 識別子の形式に従う必要があります。例えば、数字で始まったり、スペースを含めたりすることはできません。 ## ローカルの `tsc` および `cdk` の使用 ほとんどの場合、このガイドは TypeScript および CDK Toolkit をグローバルにインストールすることを前提としており (`npm install -g typescript aws-cdk`)、提供されたコマンドの例 (`cdk synth` など) はこの前提に従います。このアプローチによって両方のコンポーネントを最新の状態に保つことが容易になり、両方とも下位互換性に厳格なアプローチを取っているため、常に最新バージョンを使用するリスクは一般的にほとんどありません。 TypeScript コンパイラや CDK Toolkit などのツールを含め、一部のチームは各プロジェクト内のすべての依存関係を指定することを好みます。この実践は、これらのコンポーネントを特定のバージョンに固定し、チームのすべてのデベロッパー (および CI/CD 環境) がそれらのバージョンのみを使用できるようにします。変更になりうる原因がなくなり、ビルドおよびデプロイの一貫性および再現性が向上します。 CDK には TypeScript プロジェクトテンプレートの `package.json` に TypeScript および CDK Toolkit の両方の依存関係が含まれているため、このアプローチを使用する場合、プロジェクトを変更する必要はありません。アプリの構築および `cdk` コマンドの発行には若干異なるコマンドを使用することのみが必要です。 | Operation | グローバルツールの使用 | ローカルツールの使用 | | --- | --- | --- | | **プロジェクトの初期化** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` | | **ビルド** | `tsc` | `npm run build` | | **CDK Toolkit コマンドの実行** | `cdk …​` | `npm run cdk …​`-または-`npx aws-cdk …​` | 現在のプロジェクトにローカルにインストールされている CDK Toolkit のバージョンが存在する場合、`npx aws-cdk` はそれを実行します。グローバルインストールがある場合、それにフォールバックします。グローバルインストールが存在しない場合、`npx` は CDK Toolkit の一時コピーをダウンロードしてそれを実行します。`@` 構文を使用して CDK Toolkit の任意のバージョンを指定できます。`npx aws-cdk@2.0 --version` は `2.0.0` を出力します。 **ヒント** ローカル CDK Toolkit のインストールで `cdk` コマンドを使用できるように、エイリアスを設定します。 ``` $ alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## AWS コンストラクトライブラリモジュールの管理 ノードパッケージマネージャー (`npm`) を使用し、アプリが使用する AWS コンストラクトライブラリモジュールに加え、必要なその他のパッケージをインストールおよび更新します。(必要に応じて `npm` ではなく、`yarn` を使用できます) `npm` は、それらのモジュールの依存関係も自動的にインストールします。 ほとんどの AWS CDK コンストラクトは、`aws-cdk-lib` という名前のメイン CDK パッケージにあります。これは `cdk init` によって作成された新しいプロジェクトにおけるデフォルトの依存関係です。「実験的」な AWS コンストラクトライブラリモジュールは、上位レベルのコンストラクトがまだ開発中であり、`@aws-cdk/-alpha` のように名前が付けられます。サービス名には *aws-* のプレフィックスがあります。モジュールの名前が不明な場合、[NPM で検索します](https://www.npmjs.com/search?q=%40aws-cdk)。 **注記** [CDK API リファレンス](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html)には、パッケージ名も表示されます。 例えば、以下のコマンドは AWS CodeStar の実験モジュールをインストールします。 ``` $ npm install @aws-cdk/aws-codestar-alpha ``` 一部のサービスのコンストラクトライブラリサポートは、複数の名前空間にあります。例えば、`aws-route53` の他にも追加の Amazon Route 53 名前空間が 3 つのあり、それぞれ `aws-route53-targets`、`aws-route53-patterns`、`aws-route53resolver` です。 プロジェクトの依存関係は `package.json` で維持されます。このファイルを編集して依存関係の一部またはすべてを特定のバージョンにロックするか、特定の条件で新しいバージョンに更新することができます。`package.json` で指定したルールに従って、プロジェクトの NPM 依存関係を最新の許可されたバージョンに更新する方法 ``` $ npm update ``` TypeScript では、NPM を使用してモジュールをインストールするために使用するときと同じ名前で、モジュールをコードにインポートします。クラス AWS CDK および AWS コンストラクトライブラリモジュールをアプリケーションにインポートするとき、次の内容を実践することをお勧めします。これらのガイドラインに従うと、コードが他の AWS CDK アプリケーションと一貫性を持ち、わかりやすくなります。 + `require()` ではなく、ES6 形式の `import` ディレクティブを使用します。 + 一般的に、`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 モジュールは、`aws-cdk-lib` という 1 つの `NPM` パッケージにあります。 `npm install` を使用してパッケージをインストールすると、NPM はパッケージを `package.json` に記録します。 必要に応じて、NPM の代わりに Yarn を使用できます。ただし、CDK は Yarn のプラグアンドプレイモードをサポートしていません。このモードは、Yarn 2 のデフォルトモードです。プロジェクトの `.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 アプリケーションの場合、`package.json` の `dependencies` セクションで `aws-cdk-lib` を指定する必要があります。同じメジャーバージョン内にある限り、キャレット (^) バージョン番号の指定子を使用し、指定されたバージョンよりも新しいバージョンを受け入れることを示すことができます。 実験的なコンストラクトの場合、変更される可能性のある API を持つアルファコンストラクトライブラリモジュールの正確なバージョンを指定します。これらのモジュールの新しいバージョンには、アプリが破損する恐れのある API 変更が発生する可能性があるため、^ または \$1 を使用しないでください。 `package.json` の `devDependencies` セクションで、アプリをテストするために必要なライブラリおよびツールのバージョン (例えば、`jest` テストフレームワークなど) を指定します。オプションとして、^ を使用して新しい互換性のあるバージョンが許容されることを指定します。 ### サードパーティーのコンストラクトライブラリ コンストラクトライブラリを開発している場合、次の `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 バージョンとの互換性が最大化されます。変更される可能性のある API を持つアルファコンストラクトライブラリモジュールの正確なバージョンを指定します。`peerDependencies` を使用することで、`node_modules` ツリーですべての CDK ライブラリのコピーが 1 つしか存在しないことが保証されます。 テストに必要なツールおよびライブラリを `devDependencies` で指定します。オプションとして ^ を含めて指定し、新しい互換性のあるバージョンが許容可能であることを示します。ライブラリが `aws-cdk-lib` およびその他の CDK パッケージと互換性があることをアドバタイズする最低バージョンを正確に (^ または \$1 なしで) 指定します。これを実践すると、テストがこれらのバージョンに対して実行されていることを確認できます。これにより、新しいバージョンでのみ見つかった機能を誤って使用した場合、テストで検出できます。 **警告** `peerDependencies` は NPM 7 以降でのみ自動的にインストールされます。NPM 6 以前または Yarn を使用している場合、依存関係の依存関係を `devDependencies` に含める必要があります。そうしないと、インストールされないため、未解決のピア依存関係に関する警告が表示されます。 ### 依存関係のインストールと更新 次のコマンドを実行してプロジェクトの依存関係をインストールします。 **Example** ``` # 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 ``` ``` # 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` コマンドを使用できます。いずれのコマンドも、`package.json` のルールを満たす最新バージョンに `node_modules` のパッケージを更新します。ただし、`package.json` 自体は更新されません。新しい最小バージョンを設定するために行うことができます。GitHub でパッケージをホストする場合、`package.json` を自動的に更新するように [Dependabot バージョンの更新プログラム](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates)を設定できます。または、[npm-check-updates ](https://www.npmjs.com/package/npm-check-updates) を使用します。 **重要** 設計上、依存関係をインストールまたは更新するとき、NPM および Yarn は `package.json` で指定された要件を満たすすべてのパッケージの最新バージョンを選択します。これらのバージョンが (誤ってまたは意図的に) 破損するリスクが常にあります。プロジェクトの依存関係を更新した後は、徹底的なテストを行ってください。 ## TypeScript の AWS CDK イディオム ### Props すべての AWS コンストラクトライブラリクラスは、3 つの引数を使用してインスタンス化されます。コンストラクトが定義されている*scope* (コンストラクトツリー内の親)、*ID*、*props* があります。引数の*props*は、コンストラクトが作成する AWS リソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドでは、引数に「属性のバンドル」パターンも使用されます。 TypeScript では、必要な引数およびオプションの引数に加え、それぞれのタイプを指定するインターフェイスを使用して `props` の形状が定義されます。このようなインターフェイスは `props` 引数の種類ごとに定義され、通常は単一のコンストラクトまたはメソッドの固有なものです。例えば、[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) コンストラクト (`aws-cdk-lib/aws-s3` モジュール内) は、[https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html) インターフェイスに適合する `props` 引数を指定します。 プロパティ自体がオブジェクトの場合 (例えば、`BucketProps` の [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect) プロパティなど)、そのオブジェクトには独自のインターフェイスがあり、その形状が適合する必要があります。この場合は [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html) です。 AWS コンストラクトライブラリクラスをサブクラス化する場合 (または props のような引数を取るメソッドを上書きする場合)、既存のインターフェイスから継承して、コードに必要な新しい props を指定する新しいインターフェイスを作成できます。親クラスまたはベースメソッドを呼び出すとき、オブジェクトで指定されても、インターフェイスで指定されていない属性は無視されるため、一般的に受け取った props 引数全体を渡すことができます。 AWS CDK の将来のリリースでは、お持ちのプロパティに使用した名前を持つ新しいプロパティが同時に追加される可能性があります。受け取る値を継承チェーンの上方に渡すと、予期しない動作が発生する可能性があります。プロパティを削除または `undefined` に設定した状態で受け取った props の浅いコピーを渡す方が安全です。例: ``` super(scope, name, {...props, encryptionKeys: undefined}); ``` または、プロパティに名前を付けてコンストラクトに属していることを明確にします。今後の AWS CDK リリースでプロパティと衝突する可能性は低くなります。多数ある場合、適切に名前が付けられたオブジェクトを 1 つ使用して保持します。 ### 欠落した値 オブジェクト (props など) の欠落値は TypeScript で `undefined` の値になります。言語のバージョン 3.7 では、これらの値の使用を簡素化する演算子が導入され、未定義の値に達したときにデフォルトおよび「短絡」連鎖を指定しやすくなります。これらの機能の詳細については、「[TypeScript 3.7 リリースノート](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html)」を参照し、特に最初の 2 つの機能である「オプションの連鎖」および「NULL 合体」をお読みください。 ## CDK アプリの構築と実行 一般的に、アプリケーションを構築して実行するとき、プロジェクトのルートディレクトリにいる必要があります。 Node.js は TypeScript を直接実行することはできません。代わりに、アプリケーションは TypeScript コンパイラの `tsc` を使用して JavaScript に変換されます。その後、結果の JavaScript コードが実行されます。 アプリを実行する必要があるたびに、AWS CDK はこれを自動的に行います。ただし、エラーをチェックしてテストを実行するため、手動でコンパイルすると便利です。TypeScript アプリを手動でコンパイルするには、`npm run build` を発行します。視聴モードに入るために `npm run watch` を発行することもあり、ソースファイルに変更を保存するたびに TypeScript コンパイラが自動的にアプリを再構築します。