これは AWS CDK v2 デベロッパーガイドです。古い CDKv1 は 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 が使用されます。このガイドの例では を使用していますが、必要に応じて Yarn を使用することもできますNPM。Construct Library 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 アプリケーションでは、これら以外の追加の前提条件は必要ありません。

「プロジェクトの作成」

空のディレクトリ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コマンドを使用することだけです。

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

AWS 構築ライブラリモジュールの管理

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

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

例えば、以下のコマンドは の実験的なモジュールをインストールします 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 アプリケーションと一貫性を持ち、理解しやすくなります。

での依存関係の管理 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 または ~ なし) 指定します。この方法では、テストがそれらのバージョンに対して実行されることが保証されます。これにより、新しいバージョンでのみ見つかった機能を誤って使用した場合、テストで検出される可能性があります。

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

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

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 を使用します。

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;

で TypeScript の例の使用 JavaScript

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

TypeScript スニペットでは、新しい キーワードECMAScriptimportと exportキーワードを使用して、他のモジュールからオブジェクトをインポートし、現在のモジュール外で使用可能にするオブジェクトを宣言することがよくあります。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 }

インポートとエクスポートをソートしたら、実際のコードを掘り下げることができます。一般的に使用される以下の 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) を返すが、その値をより一般的な型のインターフェイスの一部ではないプロパティまたはメソッドにアクセスするためのより具体的な子型として扱う場合、 を使用して値をキャストし、asその後にタイプまたはインターフェイス name をキャスト TypeScript します。 はこれをサポート JavaScript しない (または必要としない) ため、 asと次の識別子を削除します。あまり一般的ではないキャスト構文は、括弧 で囲まれたタイプ名を使用することです<LikeThis>。これらのキャストも削除する必要があります。

最後に、 は、クラスのメンバーprivateのアクセス修飾子 public、protected、および TypeScript をサポートします。のすべてのクラスメンバー JavaScript はパブリックです。これらの修飾子は、表示される場所であればどこでも削除できます。

これらの TypeScript 機能を特定して削除する方法は、ショート TypeScriptスニペットを に適応させるのに大きく役立ちます JavaScript。ただし、他の TypeScript 機能を使用する可能性が高いため、この方法で長い TypeScript 例を変換することは実用的ではない場合があります。このような状況では、 を Sucrase することをお勧めします。たとえば、コードが未定義の変数を使用している場合、Sucase は苦情tscを申し立てません。構文的に有効な場合は、いくつかの例外を除いて、Sucrase はそれを に変換できます 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。