これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS CDK ライブラリの使用
AWS Cloud Development Kit (AWS CDK) ライブラリをインポートして使用し、[サポートされているプログラミング言語](languages.md)を使用して AWS クラウドインフラストラクチャを定義します。
## AWS CDK ライブラリのインポート
[AWS CDK ライブラリ](libraries.md)は、多くの場合は `aws-cdk-lib` という TypeScript パッケージ名で参照されます。実際のパッケージ名は言語によって異なります。次の内容は、CDK ライブラリをインストールしてインポートする方法の例です。
**Example**
| | |
| --- |--- |
| ** をインストールします**。 | `npm install aws-cdk-lib` |
| **インポート** – | `import * as cdk from 'aws-cdk-lib';` |
| | |
| --- |--- |
| ** をインストールします**。 | `npm install aws-cdk-lib` |
| **インポート** – | `const cdk = require('aws-cdk-lib');` |
| | |
| --- |--- |
| ** をインストールします**。 | `python -m pip install aws-cdk-lib` |
| **インポート** – | `import aws_cdk as cdk` |
| | |
| --- |--- |
| **`pom.xml` で、追加** | `Group software.amazon.awscdk; artifact aws-cdk-lib` |
| **インポート** – | `import software.amazon.awscdk.App;` |
| | |
| --- |--- |
| ** をインストールします**。 | `dotnet add package Amazon.CDK.Lib` |
| **インポート** – | `using Amazon.CDK;` |
| | |
| --- |--- |
| ** をインストールします**。 | `go get github.com/aws/aws-cdk-go/awscdk/v2` |
| **インポート** – | import (
"github.com/aws/aws-cdk-go/awscdk/v2"
)
|
`construct` ベースクラスおよびサポートコードは `constructs` ライブラリにあります。API がまだ改良中である実験コンストラクトは、個別のモジュールとして分散されます。
## AWS CDK API リファレンスの使用
AWS CDK で開発するときは、[AWS CDK API リファレンス](libraries.md#libraries-reference)を使用します。
各モジュールのリファレンスマテリアルは、次のセクションに分かれています。
+ *概要*: 概念および例を含め、AWS CDK のサービスを使用するために知る必要がある入門資料。
+ *コンストラクト*: 1 つ以上の具体的な AWS リソースを表すライブラリクラス。これらは「キュレートされた」(L2) リソースまたはパターン (L3 リソース) であり、正しいデフォルトを持つ高レベルのインターフェイスを提供します。
+ *クラス*: モジュールのコンストラクトによって使用される機能を提供する非コンストラクトクラス。
+ *構造*: プロパティ (コンストラクトの `props` 引数) やオプションなどの複合値の構造を定義するデータ構造 (属性バンドル)。
+ *インターフェイス*: 名前が「I」で始まるすべてのインターフェイスは、対応するコンストラクトまたは他のクラスの絶対最小機能を定義します。CDK はコンストラクトインターフェイスを使用して、AWS CDK アプリ外で定義されて `Bucket.fromBucketArn()` などのメソッドで参照された AWS リソースを表します。
+ *列挙型*: 特定のコンストラクトパラメータの指定に使用する名前付き値のコレクション。列挙値を使用すると、CDK が合成中にこれらの値の有効性を確認できるようにします。
+ *CloudFormation リソース*: 名前が「Cfn」で始まるこれらの L1 コンストラクトは、CloudFormation 仕様で定義されているリソースを正確に表しています。CDK リリースごとにその仕様から自動的に生成されます。各 L2 または L3 コンストラクトは、1 つ以上の CloudFormation リソースをカプセル化します。
+ *CloudFormation のプロパティタイプ*: 各 CloudFormation リソースのプロパティを定義する名前付き値のコレクション。
## コンストラクトクラスと比較したインターフェイス
インターフェイスをプログラミングの概念として理解している場合でも、AWS CDK は明確ではない特定の方法でインターフェイスを使用します。
AWS CDK は、`Bucket.fromBucketArn()` などのメソッドを使用して CDK アプリケーション外で定義されたリソースの使用をサポートします。外部リソースは変更できず、`Bucket` クラスなどを使用して CDK アプリで定義されたリソースで利用可能な機能がすべて揃っていない場合があります。次に、インターフェイスは特定の AWS リソースタイプ (*外部リソースを含む*) の CDK で利用可能な最小限の機能を表します。
CDK アプリでリソースをインスタンス化するとき、`Bucket` などの具体的なクラスを常に使用する必要があります。独自のコンストラクトのいずれかで受け入れる引数のタイプを指定するとき、外部リソースを処理する準備ができている場合、`IBucket` などのインターフェイスタイプを使用します (つまり、変更が不要)。CDK で定義されたコンストラクトが必要な場合、使用できる最も一般的なタイプを指定します。
一部のインターフェイスは、コンストラクトではなく、特定のクラスに関連付けられたプロパティまたはオプションバンドルの最小バージョンです。このようなインターフェイスは、親クラスに渡す引数を受け入れるようにサブクラス化するときに便利です。1 つ以上の追加プロパティが必要な場合、このインターフェイスまたはより具体的なタイプから実装または取得する必要があります。
**注記**
AWS CDK でサポートされている一部のプログラミング言語には、インターフェイス機能がありません。これらの言語では、インターフェイスは通常のクラスにすぎません。頭文字の「I」の後に他のコンストラクトの名前 (例えば、`IBucket`) が続くパターンに従う名前で特定できます。同じルールが適用されます。
## 依存関係の管理
AWS CDK アプリまたはライブラリの依存関係は、パッケージ管理ツールを使用して管理されます。これらのツールはプログラミング言語で一般的に使用されます。
通常、AWS CDK は言語の基準をサポートするか、公式パッケージ管理ツールがある場合はそれをサポートします。それ以外の場合、AWS CDK は言語の最も人気または広くサポートされているものをサポートします。特にサポートされているツールに対応している場合、他のツールも使用できる場合があります。ただし、他のツールの公式サポートは限られています。
AWS CDK は、次のパッケージマネージャーをサポートしています。
| 言語 | サポートされているパッケージ管理ツール |
| --- | --- |
| TypeScript/JavaScript | NPM (ノードパッケージマネージャー) または Yarn |
| Python (パイソン) | PIP (Python のパッケージインストーラ) |
| Java | Maven (メイヴン) |
| C\$1 | NuGet |
| Go | Go モジュール |
AWS CDK CLI の `cdk init` コマンドを使用して新しいプロジェクトを作成するとき、CDK コアライブラリおよび安定したコンストラクトの依存関係が自動的に指定されます。
サポートされているプログラミング言語の依存関係の管理における詳細については、次の内容を参照してください。
+ [TypeScript の依存関係の管理](work-with-cdk-typescript.md#work-with-cdk-typescript-dependencies)。
+ [JavaScript の依存関係の管理](work-with-cdk-javascript.md#work-with-cdk-javascript-dependencies)。
+ [Python の依存関係の管理](work-with-cdk-python.md#work-with-cdk-python-dependencies)。
+ [Java の依存関係の管理](work-with-cdk-java.md#work-with-cdk-java-dependencies)。
+ [C\$1 の依存関係の管理](work-with-cdk-csharp.md#work-with-cdk-csharp-dependencies)。
+ [Go の依存関係の管理](work-with-cdk-go.md#work-with-cdk-go-dependencies)。
## TypeScript での AWS CDK と他の言語の比較
TypeScript は、AWS CDK アプリケーションの開発でサポートされている最初の言語でした。したがって、大量の CDK コード例は TypeScript に記述されています。別の言語で開発している場合、TypeScript で AWS CDK コードが実装されている方法を、選択した言語と比較すると便利です。ドキュメント全体の例を使用できるようになります。
## モジュールのインポート
**Example**
TypeScript は名前空間全体のインポート、あるいは名前空間から個々のオブジェクトのインポートのいずれかをサポートしています。各名前空間には、特定の AWS サービスで使用するコンストラクトやその他のクラスが含まれます。
```
// Import main CDK library as cdk
import * as cdk from 'aws-cdk-lib'; // ES6 import preferred in TS
const cdk = require('aws-cdk-lib'); // Node.js require() preferred in JS
// Import specific core CDK classes
import { Stack, App } from 'aws-cdk-lib';
const { Stack, App } = require('aws-cdk-lib');
// Import AWS S3 namespace as s3 into current namespace
import { aws_s3 as s3 } from 'aws-cdk-lib'; // TypeScript
const s3 = require('aws-cdk-lib/aws-s3'); // JavaScript
// Having imported cdk already as above, this is also valid
const s3 = cdk.aws_s3;
// Now use s3 to access the S3 types
const bucket = s3.Bucket(...);
// Selective import of s3.Bucket
import { Bucket } from 'aws-cdk-lib/aws-s3'; // TypeScript
const { Bucket } = require('aws-cdk-lib/aws-s3'); // JavaScript
// Now use Bucket to instantiate an S3 bucket
const bucket = Bucket(...);
```
TypeScript と同様に、Python は名前空間モジュールインポートおよび選択的インポートをサポートしています。Python の名前空間は **aws\$1cdk** *.xxx* に似ており、*xxx* は Amazon S3 の **s3** などの AWS サービス名を表します。(Amazon S3 はこれらの例で使用されます)。
```
# Import main CDK library as cdk
import aws_cdk as cdk
# Selective import of specific core classes
from aws_cdk import Stack, App
# Import entire module as s3 into current namespace
import aws_cdk.aws_s3 as s3
# s3 can now be used to access classes it contains
bucket = s3.Bucket(...)
# Selective import of s3.Bucket into current namespace
from aws_cdk.s3 import Bucket
# Bucket can now be used to instantiate a bucket
bucket = Bucket(...)
```
Java のインポートは、TypeScript のものとは動作が異なります。各インポートステートメントは、特定のパッケージから 1 つのクラス名、あるいはそのパッケージで定義されているすべてのクラス (`\*` を使用) のいずれかをインポートします。クラス名がインポートされている場合はクラス名の単体、あるいはパッケージを含む*修飾*クラス名のいずれかを使用し、クラスにアクセスできます。
ライブラリは AWS コンストラクトライブラリ (メインライブラリは `software.amazon.awscdk` です) に対して `software.amazon.awscdk.services.xxx` のような名前が付けられます。AWS CDK パッケージの Maven グループ ID は `software.amazon.awscdk` です。
```
// Make certain core classes available
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.App;
// Make all Amazon S3 construct library classes available
import software.amazon.awscdk.services.s3.*;
// Make only Bucket and EventType classes available
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.s3.EventType;
// An imported class may now be accessed using the simple class name (assuming that name
// does not conflict with another class)
Bucket bucket = Bucket.Builder.create(...).build();
// We can always use the qualified name of a class (including its package) even without an
// import directive
software.amazon.awscdk.services.s3.Bucket bucket =
software.amazon.awscdk.services.s3.Bucket.Builder.create(...)
.build();
// Java 10 or later can use var keyword to avoid typing the type twice
var bucket =
software.amazon.awscdk.services.s3.Bucket.Builder.create(...)
.build();
```
C\$1 では、`using` ディレクティブを使用してタイプをインポートします。2 つの形式があります。1 つはプレーン名を使用し、指定された名前空間のすべてのタイプにアクセスできます。もう 1 つは、エイリアスを使用して名前空間自体を参照できます。
パッケージには、AWS コンストラクトライブラリパッケージに `Amazon.CDK.AWS.xxx` のような名前が付けられます。(コアモジュールは `Amazon.CDK`)
```
// Make CDK base classes available under cdk
using cdk = Amazon.CDK;
// Make all Amazon S3 construct library classes available
using Amazon.CDK.AWS.S3;
// Now we can access any S3 type using its name
var bucket = new Bucket(...);
// Import the S3 namespace under an alias
using s3 = Amazon.CDK.AWS.S3;
// Now we can access an S3 type through the namespace alias
var bucket = new s3.Bucket(...);
// We can always use the qualified name of a type (including its namespace) even without a
// using directive
var bucket = new Amazon.CDK.AWS.S3.Bucket(...);
```
各 AWS コンストラクトライブラリモジュールは Go パッケージとして提供されます。
```
import (
"github.com/aws/aws-cdk-go/awscdk/v2" // CDK core package
"github.com/aws/aws-cdk-go/awscdk/v2/awss3" // AWS S3 construct library module
)
// now instantiate a bucket
bucket := awss3.NewBucket(...)
// use aliases for brevity/clarity
import (
cdk "github.com/aws/aws-cdk-go/awscdk/v2" // CDK core package
s3 "github.com/aws/aws-cdk-go/awscdk/v2/awss3" // AWS S3 construct library module
)
bucket := s3.NewBucket(...)
```
## コンストラクトのインスタンス化
AWS CDK コンストラクトクラスの名前は、サポートされているすべての言語で同じです。ほとんどの言語は、`new` キーワードを使用してクラスをインスタンス化します (Python と Go はしません)。また、ほとんどの言語ではキーワードは `this` 現在のインスタンスを参照します。(Python は 規則で `self` を使用します) 作成するすべてのコンストラクトに対し、`scope` パラメータとして現在のインスタンスに参照を渡す必要があります。
AWS CDK コンストラクトの 3 番目の引数は `props` であり、コンストラクトの構築に必要な属性を含むオブジェクトです。この引数はオプションですが、必要なときはサポートされている言語が特異な方法で処理します。属性の名前は、言語の標準命名パターンにも適応されています。
**Example**
```
// Instantiate default Bucket
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket');
// Instantiate Bucket with bucketName and versioned properties
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
bucketName: 'amzn-s3-demo-bucket',
versioned: true,
});
// Instantiate Bucket with websiteRedirect, which has its own sub-properties
const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', {
websiteRedirect: {host: 'aws.amazon.com'}});
```
Python は、クラスをインスタンス化するときに `new` キーワードを使用しません。プロパティ引数はキーワード引数を使用して表され、引数は `snake_case` を使用して名前が付けられます。
props 値自体が属性のバンドルである場合、プロパティの後に名前が付けられたクラスで表され、サブプロパティのキーワード引数を受け入れます。
Python では、現在のインスタンスは最初の引数としてメソッドに渡されます。この引数は、規則によって `self` という名前が付けられます。
```
# Instantiate default Bucket
bucket = s3.Bucket(self, "amzn-s3-demo-bucket")
# Instantiate Bucket with bucket_name and versioned properties
bucket = s3.Bucket(self, "amzn-s3-demo-bucket", bucket_name="amzn-s3-demo-bucket", versioned=true)
# Instantiate Bucket with website_redirect, which has its own sub-properties
bucket = s3.Bucket(self, "amzn-s3-demo-bucket", website_redirect=s3.WebsiteRedirect(
host_name="aws.amazon.com"))
```
Java では、props 引数は `XxxxProps` という名前のクラス (例えば、`Bucket` コンストラクトの props に `BucketProps`) で表されます。ビルダーパターンを使用して props 引数を構築します。
各 `XxxxProps` クラスにはビルダーがあります。次の例で示すように、1 つのステップで props およびコンストラクトを構築する各コンストラクトに便利なビルダーもあります。
Props は、`camelCase` を使用して TypeScript と同じように名前が付けられます。
```
// Instantiate default Bucket
Bucket bucket = Bucket(self, "amzn-s3-demo-bucket");
// Instantiate Bucket with bucketName and versioned properties
Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket")
.bucketName("amzn-s3-demo-bucket").versioned(true)
.build();
# Instantiate Bucket with websiteRedirect, which has its own sub-properties
Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket")
.websiteRedirect(new websiteRedirect.Builder()
.hostName("aws.amazon.com").build())
.build();
```
C\$1 では、`XxxxProps` という名前のクラスにオブジェクト初期化子を使用して props が指定されます (例えば、`Bucket` コンストラクトの props に `BucketProps`)。
Props は TypeScript と同様に名前が付けられますが、`PascalCase` が使用されます。
コンストラクトをインスタンス化するときに `var` キーワードを使用するのが便利なため、クラス名を 2 回入力する必要はありません。ただし、ローカルコードのスタイルガイドは異なる場合があります。
```
// Instantiate default Bucket
var bucket = Bucket(self, "amzn-s3-demo-bucket");
// Instantiate Bucket with BucketName and Versioned properties
var bucket = Bucket(self, "amzn-s3-demo-bucket", new BucketProps {
BucketName = "amzn-s3-demo-bucket",
Versioned = true});
// Instantiate Bucket with WebsiteRedirect, which has its own sub-properties
var bucket = Bucket(self, "amzn-s3-demo-bucket", new BucketProps {
WebsiteRedirect = new WebsiteRedirect {
HostName = "aws.amazon.com"
}});
```
Go でコンストラクトを作成するには、`Xxxxxxx` がコンストラクトの名前である `NewXxxxxx` 関数を呼び出します。コンストラクトのプロパティは構造として定義されます。
Go では、すべてのコンストラクトパラメータはポインタであり、数値、ブール値、文字列などの値を含みます。`jsii.String` などの便利な関数を使用してこれらのポインタを作成します。
```
// Instantiate default Bucket
bucket := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), nil)
// Instantiate Bucket with BucketName and Versioned properties
bucket1 := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
BucketName: jsii.String("amzn-s3-demo-bucket"),
Versioned: jsii.Bool(true),
})
// Instantiate Bucket with WebsiteRedirect, which has its own sub-properties
bucket2 := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{
WebsiteRedirect: &awss3.RedirectTarget{
HostName: jsii.String("aws.amazon.com"),
}})
```
## メンバーへのアクセス
コンストラクトおよびその他の AWS CDK クラスの属性やプロパティを参照し、これらの値を (例えば) 入力として使用して他のコンストラクトを構築することは一般的です。メソッドの前述の名前付けによる違いは、ここでも適用されます。さらに、Java ではメンバーに直接アクセスすることはできません。代わりに、ゲッターメソッドが用意されています。
**Example**
名前は `camelCase` です。
```
bucket.bucketArn
```
名前は `snake_case` です。
```
bucket.bucket_arn
```
各プロパティにはゲッターメソッドが用意されています。これらの名前は `camelCase` です。
```
bucket.getBucketArn()
```
名前は `PascalCase` です。
```
bucket.BucketArn
```
名前は `PascalCase` です。
```
bucket.BucketArn
```
## 列挙型定数
列挙型定数はクラスにスコープされ、すべての言語で下線が付いた大文字の名前があります (`SCREAMING_SNAKE_CASE` と呼ばれることもあります)。クラス名は Go を除くサポートされているすべての言語でも同じケーシングを使用するため、修飾された列挙型名はこれらの言語でも同じです。
```
s3.BucketEncryption.KMS_MANAGED
```
Go では、列挙型定数はモジュール名前空間の属性であり、次のように記述されます。
```
awss3.BucketEncryption_KMS_MANAGED
```
## オブジェクトインターフェイス
AWS CDK は TypeScript オブジェクトインターフェイスを使用し、クラスが予想されるメソッドおよびプロパティのセットを実装していることを示します。オブジェクトインターフェイスの名前の頭文字が `I` であるため、識別できます。具体的なクラスは、`implements` キーワードを使用して実装するインターフェイスを示します。
**Example**
JavaScript にはインターフェイス機能はありません。`implements` キーワードおよびその後に続くクラス名を無視してください。
```
import { IAspect, IConstruct } from 'aws-cdk-lib';
class MyAspect implements IAspect {
public visit(node: IConstruct) {
console.log('Visited', node.node.path);
}
}
```
Python にはインターフェイス機能はありません。ただし、AWS CDK にはクラスを `@jsii.implements(interface)` で装飾することでインターフェイスの実装を示すことができます。
```
from aws_cdk import IAspect, IConstruct
import jsii
@jsii.implements(IAspect)
class MyAspect():
def visit(self, node: IConstruct) -> None:
print("Visited", node.node.path)
```
```
import software.amazon.awscdk.IAspect;
import software.amazon.awscdk.IConstruct;
public class MyAspect implements IAspect {
public void visit(IConstruct node) {
System.out.format("Visited %s", node.getNode().getPath());
}
}
```
```
using Amazon.CDK;
public class MyAspect : IAspect
{
public void Visit(IConstruct node)
{
System.Console.WriteLine($"Visited ${node.Node.Path}");
}
}
```
Go 構造は、実装するインターフェイスを明示的に宣言する必要はありません。Go コンパイラは、構造で利用可能なメソッドおよびプロパティに基づいて実装を決定します。例えば、次のコードでは、`MyAspect` は コンストラクトを取る `Visit` メソッドを提示するため、`IAspect` インターフェイスを実装します。
```
type MyAspect struct {
}
func (a MyAspect) Visit(node constructs.IConstruct) {
fmt.Println("Visited", *node.Node().Path())
}
```
# 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 コンパイラが自動的にアプリを再構築します。
# JavaScript での AWS CDK の使用
JavaScript は AWS CDK で完全にサポートされているクライアント言語であり、安定していると見なされます。JavaScript で AWS クラウド開発キット (AWS CDK) を操作するには、[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/)) を使用しています。このコードは JavaScript を十分にサポートしています。
## JavaScript の使用を開始する
AWS CDK を使用するには、 AWS アカウントと認証情報があり、Node.js と AWS CDK Toolkit がインストールされている必要があります。[AWS 「CDK の開始方法」を参照してください](getting-started.md)。
JavaScript AWS CDK アプリケーションには、これら以外の追加の前提条件は必要ありません。
**注記**
サードパーティー言語の廃止: 言語バージョンは、ベンダーまたはコミュニティによって共有される EOL (製品終了) までのみサポートされ、事前の通知によって変更されます。
## プロジェクトの作成
空のディレクトリ`cdk init`で を呼び出して、新しい AWS CDK プロジェクトを作成します。`--language` オプションを使用して `javascript` を指定します。
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language javascript
```
プロジェクトを作成すると、[aws-cdk-lib](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) モジュールおよびその依存関係もインストールされます。
`cdk init` はプロジェクトフォルダの名前を使用し、クラス、サブフォルダ、ファイルなどのプロジェクトのさまざまな要素に名前を付けます。フォルダ名に含まれるハイフンはアンダースコアに変換されます。ただし、それ以外の場合、名前は JavaScript 識別子の形式に従う必要があります。例えば、数字で始まったり、スペースを含めたりすることはできません。
## ローカル `cdk` の使用
ほとんどの場合、このガイドでは、CDK Toolkit をグローバルにインストールすることを前提としており (`npm install -g aws-cdk`)、提供されたコマンド例 (`cdk synth` など) はこの前提に従います。このアプローチによって CDK Toolkit を最新の状態に保つことが容易になり、CDK は下位互換性に厳格なアプローチを取っているため、常に最新バージョンを使用するリスクは一般的にほとんどありません。
一部のチームは、CDK Toolkit などのツールを含め、各プロジェクト内のすべての依存関係を指定することを好みます。この実践は、このようなコンポーネントを特定のバージョンに固定し、チームのすべてのデベロッパー (および CI/CD 環境) がそれらのバージョンのみを使用できるようにします。変更になりうる原因がなくなり、ビルドおよびデプロイの一貫性および再現性が向上します。
CDK には JavaScript プロジェクトテンプレートの `package.json` に CDK Toolkit の依存関係が含まれているため、このアプローチを使用する場合、プロジェクトを変更する必要はありません。アプリの構築および `cdk` コマンドの発行には若干異なるコマンドを使用することのみが必要です。
| 運用 | グローバルツールの使用 | ローカルツールの使用 |
| --- | --- | --- |
| **プロジェクトの初期化** | `cdk init --language javascript` | `npx aws-cdk init --language javascript` |
| **CDK Toolkit コマンドを実行する** | `cdk …` | `npm run cdk …`、または `npx aws-cdk …` |
現在のプロジェクトにローカルにインストールされている CDK Toolkit のバージョンが存在する場合、`npx aws-cdk` はそれを実行します。グローバルインストールがある場合、それにフォールバックします。グローバルインストールが存在しない場合、`npx` は CDK Toolkit の一時コピーをダウンロードしてそれを実行します。`@` 構文を使用して CDK Toolkit の任意のバージョンを指定できます。`npx aws-cdk@1.120 --version` は `1.120.0` を出力します。
**ヒント**
ローカル CDK Toolkit のインストールで `cdk` コマンドを使用できるように、エイリアスを設定します。
```
$ alias cdk="npx aws-cdk"
```
```
doskey cdk=npx aws-cdk $*
```
## AWS コンストラクトライブラリモジュールの管理
Node Package Manager (`npm`) を使用して、アプリケーションで使用する AWS コンストラクトライブラリモジュール、および必要なその他のパッケージをインストールおよび更新します。(必要に応じて `npm` ではなく、`yarn` を使用できます) `npm` は、それらのモジュールの依存関係も自動的にインストールします。
ほとんどの AWS CDK コンストラクトは、 という名前のメイン CDK パッケージにあります。これは`aws-cdk-lib`、 によって作成された新しいプロジェクトのデフォルトの依存関係です`cdk init`。上位レベルのコンストラクトがまだ開発中である「実験 AWS 」コンストラクトライブラリモジュールは、 のように名前が付けられます`aws-cdk-lib/-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
```
JavaScript では、NPM を使用してモジュールをインストールするために使用するときと同じ名前で、モジュールをコードにインポートします。 AWS CDK クラスと AWS コンストラクトライブラリモジュールをアプリケーションにインポートするときは、次のプラクティスをお勧めします。これらのガイドラインに従うことで、コードが他の AWS CDK アプリケーションと一貫性を持ち、理解しやすくなります。
+ ES6-style `import` ディレクティブではなく、`require()` を使用します。Node.js の古いバージョンは ES6 インポートをサポートしていないため、古い構文を使用するとより広範囲に互換性があります。(ES6 インポートを使用する場合、[esm](https://www.npmjs.com/package/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 のプラグアンドプレイモードをサポートしていません。このモードは、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 アプリケーションの場合、`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` で指定された要件を満たすすべてのパッケージの最新バージョンを選択します。これらのバージョンが (誤ってまたは意図的に) 破損するリスクが常にあります。プロジェクトの依存関係を更新した後は、徹底的なテストを行ってください。
## AWS JavaScript の CDK イディオム
### Props
すべての AWS コンストラクトライブラリクラスは、3 つの引数を使用してインスタンス化されます。コンストラクトが定義されている*スコープ* (コンストラクトツリー内の親）、*ID*、*props*、コンストラクトが作成する AWS リソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドでは、引数に「属性のバンドル」パターンも使用されます。
JavaScript オートコンプリートが適切な IDE またはエディタを使用すると、プロパティ名のスペルミスを防止することができます。コンストラクトが `encryptionKeys` プロパティを予想し、ユーザーがそれを `encryptionkeys` とスペルした場合、コンストラクトをインスタンス化するときに意図した値に合格しません。プロパティが必要な場合は合成時にエラーが発生するか、オプションの場合はプロパティが静的に無視される可能性があります。後者の場合、上書きを意図しているデフォルトの動作が発生する場合があります。ここでは十分に注意してください。
AWS コンストラクトライブラリクラスをサブクラス化する場合 (または props のような引数を取るメソッドを上書きする場合）、独自の使用のために追加のプロパティを受け入れることができます。そのコードではアクセスされないため、これらの値は親クラスまたは上書きされたメソッドによって無視されます。したがって、一般的に受け取ったすべての props を渡すことができます。
AWS CDK の今後のリリースでは、独自のプロパティに使用した名前の新しいプロパティが同時に追加される可能性があります。受け取る値を継承チェーンの上方に渡すと、予期しない動作が発生する可能性があります。プロパティを削除または `undefined` に設定した状態で受け取った props の浅いコピーを渡す方が安全です。例えば、次のようになります。
```
super(scope, name, {...props, encryptionKeys: undefined});
```
または、プロパティに名前を付けてコンストラクトに属していることを明確にします。これにより、将来の AWS CDK リリースでプロパティと衝突する可能性は低くなります。多数ある場合、適切に名前が付けられたオブジェクトを 1 つ使用して保持します。
### 欠落した値
オブジェクト (`props` など) の欠落値は、JavaScript で `undefined` の値があります。これらに対処する場合、通常の手法が適用されます。例えば、定義されていないある値のプロパティにアクセスするための一般的なイディオムは次のとおりです。
```
// 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;
```
ただし、`a` に `undefined` 以外の他の「falsy」値が含まれる可能性がある場合、テストをより明確にすることが推奨されます。こちらでは、`null` および `undefined` は等しいため、両方とも一度にテストできるという事実を活用します。
```
let c = a == null ? a : a.b;
```
**ヒント**
Node.js 14.0 以降では、未定義の値の処理を簡素化できる新しい演算子がサポートされています。詳細については、「[オプションの連鎖](https://github.com/tc39/proposal-optional-chaining/blob/master/README.md)」および「[NULL 合体](https://github.com/tc39/proposal-nullish-coalescing/blob/master/README.md)」の提案を参照してください。
## JavaScript で TypeScript 例の使用
[TypeScript](https://www.typescriptlang.org/) は AWS CDK の開発に使用する言語であり、アプリケーションの開発で最初にサポートされている言語であるため、使用可能な AWS CDK コード例は TypeScript で記述されています。これらのコード例は JavaScript デベロッパーにとって良いリソースです。コードの TypeScript 固有の部分を削除するのみです。
TypeScript スニペットは、新しい ECMAScript の `import` および `export` キーワードを使用し、他のモジュールからオブジェクトをインポートして、現在のモジュール外で利用できるようにオブジェクトを宣言することがよくあります。Node.js は、最新リリースでこれらのキーワードのサポートを開始したばかりです。使用している (またはサポートする) Node.js のバージョンによっては、古い構文を使用するためにインポートおよびエクスポートを書き換える場合があります。
インポートは `require()` 関数への呼び出しに置き換えることができます。
**Example**
```
import * as cdk from 'aws-cdk-lib';
import { Bucket, BucketPolicy } from 'aws-cdk-lib/aws-s3';
```
```
const cdk = require('aws-cdk-lib');
const { Bucket, BucketPolicy } = require('aws-cdk-lib/aws-s3');
```
エクスポートは `module.exports` オブジェクトに割り当てることができます。
**Example**
```
export class Stack1 extends cdk.Stack {
// ...
}
export class Stack2 extends cdk.Stack {
// ...
}
```
```
class Stack1 extends cdk.Stack {
// ...
}
class Stack2 extends cdk.Stack {
// ...
}
module.exports = { Stack1, Stack2 }
```
**注記**
古い形式のインポートおよびエクスポートを使用する代わりに、[esm](https://www.npmjs.com/package/esm) モジュールを使用します。
インポートおよびエクスポートの対応が済んだら、実際のコードを触れることができます。一般的に使用される以下の TypeScript 機能を使用する場合があります。
+ 型注釈
+ インターフェイス定義
+ タイプ変換/キャスト
+ アクセス修飾子
変数、クラスメンバー、関数パラメータ、関数戻り型に対して型注釈を指定できます。変数、パラメータ、メンバーの場合、識別子の後にコロンおよび型を配置することで型を指定します。関数の戻り値は関数署名に従い、コロンおよび型で構成されます。
型注釈付きコードを JavaScript に変換するには、コロンおよび型を削除します。クラスメンバーは JavaScript に値を含める必要があります。TypeScript に型注釈のみがある場合、`undefined` に設定します。
**Example**
```
var encrypted: boolean = true;
class myStack extends cdk.Stack {
bucket: s3.Bucket;
// ...
}
function makeEnv(account: string, region: string) : object {
// ...
}
```
```
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` を使用して値を*キャスト*したら、タイプまたはインターフェイス名も同様に処理できます。JavaScript はこれをサポートしていない (または必要としない) ため、`as` および次の識別子のみを削除します。あまり一般的ではないキャスト構文では、`` の括弧内に型名を使用します。これらのキャストも削除する必要があります。
最後に、TypeScript はクラスのメンバー用の `public`、`protected`、`private` アクセス修飾子をサポートします。JavaScript のすべてのクラスメンバーはパブリックです。これらの修飾子は見つけたら削除してください。
これらの TypeScript 機能を特定して削除する方法を知っていると、短い TypeScript スニペットを JavaScript に適応させる上でかなり有利になります。ただし、他の TypeScript 機能を使用する可能性が高いため、この方法で長い TypeScript の例を変換することは現実的ではない場合があります。このような状況では、[Sucrase](https://github.com/alangpierce/sucrase) をお勧めします。例えば、コードが未定義の変数を使用している場合、`tsc` とは違って Sucrase は申し立てることはありません。構文的に有効な場合、いくつかの例外を除くと Sucrase は JavaScript に変換できます。単独で実行できないスニペットを変換するのうえで特に重宝されます。
## TypeScript への移行
多くの JavaScript デベロッパーは、プロジェクトが大型化かつ複雑化すると [TypeScript](https://www.typescriptlang.org/) に移行します。TypeScript は JavaScript のスーパーセットです。JavaScript コードはすべて有効な TypeScript コードであるため、コードを変更する必要はありません。また、サポートされている AWS CDK 言語でもあります。型注釈やその他の TypeScript 機能はオプションであり、値を見つけたら AWS CDK アプリに追加できます。TypeScript は、オプション連鎖や NULL 合体など、確定する前に新しい 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 で開発を開始します。
# Python での AWS CDK の使用
Python は AWS Cloud Development Kit (AWS CDK) で完全にサポートされているクライアント言語であり、安定していると見なされます。Python で AWS CDK を操作するには、標準の Python 実装 (CPython)、 を使用した仮想環境`virtualenv`、Python パッケージインストーラ などの使い慣れたツールを使用します`pip`。 AWS コンストラクトライブラリを構成するモジュールは、[pypi.org](https://pypi.org/search/?q=aws-cdk) を介して配布されます。 AWS CDK の Python バージョンでは、Python 形式の識別子 (`snake_case`メソッド名など) も使用されます。
任意のエディタまたは IDE を使用できます。多くの AWS CDK デベロッパーは [Visual Studio Code](https://code.visualstudio.com/) (または同等のオープンソースの [VSCodium](https://vscodium.com/)) を使用します。このコードは、[公式拡張機能](https://marketplace.visualstudio.com/items?itemName=ms-python.python)を介して Python を適切にサポートしています。Python に含まれている IDLE エディタは、開始するために十分です。 AWS CDK の Python モジュールには、型検証をサポートするリンティングツールまたは IDE に役立つ型ヒントがあります。
## Python の使用を開始する
AWS CDK を使用するには、 AWS アカウントと認証情報があり、Node.js と AWS CDK Toolkit がインストールされている必要があります。[AWS 「CDK の開始方法」を参照してください](getting-started.md)。
Python AWS CDK アプリケーションには Python 3.9 以降が必要です。まだインストールされていない場合、[python.org](https://www.python.org/) でお使いのオペレーティングシステムに[対応したバージョンをダウンロード](https://www.python.org/downloads/)してください。Linux を実行する場合、システムに互換性のあるバージョンが付属している場合があります。そうでない場合、Distro のパッケージマネージャー (`yum` や `apt` など) を使用してインストールできます。Mac ユーザーは、macOS 用の Linux 形式のパッケージマネージャーである [Homebrew](https://brew.sh/) をご検討いただけます。
**注記**
サードパーティー言語の廃止: 言語バージョンは、ベンダーまたはコミュニティによって共有される EOL (製品終了) までのみサポートされ、事前の通知によって変更されます。
Python パッケージインストーラー、`pip`、仮想環境マネージャー `virtualenv` も必要です。互換性のある Python バージョンの Windows インストールには、これらのツールが含まれます。Linux では、`pip` と `virtualenv` はパッケージマネージャーで個別のパッケージとして提供される場合があります。または、次のコマンドでインストールすることができます。
```
python -m ensurepip --upgrade
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv
```
アクセス許可エラーが発生した場合、`--user` フラグを使用して上記のコマンドを実行し、モジュールがユーザーディレクトリにインストールされるようにするか、`sudo` を使用してシステム全体でモジュールをインストールするアクセス許可を取得します。
**注記**
Linux Distro が Python 3.x に実行可能な名前の `python3` を使用し、`python` に Python 2.x のインストールを参照させることは一般的です。一部の Distro にはインストールできるオプションのパッケージがあり、`python` コマンドに Python 3 を参照させます。これを行わない場合、プロジェクトのメインディレクトリで `cdk.json` を編集することにより、アプリケーションの実行に使用されるコマンドを調整できます。
**注記**
Windows では、`py` の実行ファイルである [Windows 用の Python ランチャー](https://docs.python.org/3/using/windows.html#launcher)を使用して Python (および `pip`) を呼び出すことができます。特に、ランチャーを使用すると、使用する Python のインストールされているバージョンを簡単に指定できます。
コマンドラインで `python` と入力して Windows Store から Python をインストールすることに関するメッセージが表示される場合 (Python の Windows バージョンをインストールした後でも)、Windows の [アプリ実行エイリアスの管理] 設定パネルを開き、Python の 2 つの [アプリインストーラ] エントリをオフにします。
## プロジェクトの作成
空のディレクトリ`cdk init`で を呼び出して、新しい AWS CDK プロジェクトを作成します。`--language` オプションを使用して `python` を指定します。
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language python
```
`cdk init` はプロジェクトフォルダの名前を使用し、クラス、サブフォルダ、ファイルなどのプロジェクトのさまざまな要素に名前を付けます。フォルダ名に含まれるハイフンはアンダースコアに変換されます。ただし、それ以外の場合、名前は Python 識別子の形式に従う必要があります。例えば、数字で始まったり、スペースを含めたりすることはできません。
新しいプロジェクトで作業するには、その仮想環境を有効にします。これにより、プロジェクトの依存関係をグローバルにインストールするのではなく、プロジェクトフォルダにローカルにインストールできます。
```
$ source .venv/bin/activate
```
**注記**
これは、仮想環境をアクティブにする Mac/Linux コマンドとして認識されるかもしれません。Python テンプレートには、同じコマンドを Windows で使用できるようにするバッチファイル、`source.bat` が含まれています。従来の Windows コマンドの `.\venv\Scripts\activate` も使用できます。
AWS CDK Toolkit v1.70.0 以前を使用して CDK プロジェクトを初期化した場合、仮想環境は ではなく `.env` ディレクトリにあります`.venv`。
**重要**
作業を開始するたびに、プロジェクトの仮想環境をアクティブ化します。そうしないと、そこにインストールされたモジュールにアクセスできなくなり、インストールしたモジュールは Python グローバルモジュールディレクトリに移動されます (またはアクセス許可エラーが発生します)。
仮想環境を初めてアクティブ化したら、アプリの標準依存関係をインストールします。
```
$ python -m pip install -r requirements.txt
```
## AWS コンストラクトライブラリモジュールの管理
Python パッケージインストーラ を使用して`pip`、アプリケーションで使用する AWS コンストラクトライブラリモジュール、および必要な他のパッケージをインストールおよび更新します。 は、それらのモジュールの依存関係`pip`も自動的にインストールします。システムがスタンドアロンコマンドとして `pip` を認識しない場合、次のように Python モジュールとして `pip` を呼び出します。
```
$ python -m pip
```
ほとんどの AWS CDK コンストラクトは にあります`aws-cdk-lib`。実験モジュールは、`aws-cdk..alpha` のような名前が付いた個別のモジュールにあります。サービス名には *aws* プレフィックスが含まれます。モジュールの名前が不明な場合、[PyPI で検索します](https://pypi.org/search/?q=aws-cdk)。たとえば、次のコマンドは AWS CodeStar ライブラリをインストールします。
```
$ python -m pip install aws-cdk.aws-codestar-alpha
```
一部のサービスのコンストラクトは、複数の名前空間にあります。例えば、`aws-cdk.aws-route53` の他にも追加の Amazon Route 53 名前空間が 3 つのあり、それぞれ `aws-route53-targets`、`aws-route53-patterns`、`aws-route53resolver` という名前が付いています。
**注記**
[CDK API リファレンスの Python エディション](https://docs.aws.amazon.com/cdk/api/v2/python/index.html)には、パッケージ名も表示されます。
Python コードへの AWS コンストラクトライブラリモジュールのインポートに使用される名前は次のようになります。
```
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_lambda as lambda_
```
AWS CDK クラスと AWS コンストラクトライブラリモジュールをアプリケーションにインポートするときは、次のプラクティスをお勧めします。これらのガイドラインに従うことで、コードが他の AWS CDK アプリケーションと一貫性を持ち、理解しやすくなります。
+ 一般的に、個々のクラスは最上位の `aws_cdk` からインポートします。
```
from aws_cdk import App, Construct
```
+ `aws_cdk` から多数のクラスが必要な場合、個々のクラスをインポートするのではなく、`cdk` の名前空間エイリアスを使用できます。両方を実行しないでください。
```
import aws_cdk as cdk
```
+ 通常、短い名前空間エイリアスを使用して AWS コンストラクトライブラリをインポートします。
```
import aws_cdk.aws_s3 as s3
```
モジュールをインストールしたら、プロジェクトの依存関係を一覧表示するプロジェクトの `requirements.txt` ファイルを更新します。`pip freeze` を使用するのではなく、手動で行うことをお勧めします。`pip freeze` は、Python 仮想環境にインストールされているすべてのモジュールの最新バージョンをキャプチャします。他の場所で実行されるプロジェクトをバンドルするときに便利です。
ただし、通常は `requirements.txt` は最上位の依存関係 (アプリが直接依存するモジュール) のみを一覧表示し、それらのライブラリの依存関係を一覧表示しません。この戦略は、依存関係の更新がより簡単にします。
`requirements.txt` を編集してアップグレードを許可できます。バージョン番号の前の `==` を `~=` に置き換え、互換性のあるそれ以降のバージョンへのアップグレードを許可するか、バージョン要件を完全に削除して利用可能なモジュールの最新バージョンを指定します。
アップグレードを許可するために `requirements.txt` が適切に編集されると、このコマンドを発行して、プロジェクトのインストールされたモジュールをいつでもアップグレードできます。
```
$ pip install --upgrade -r requirements.txt
```
## Python での依存関係の管理
Python で依存関係を指定するには、アプリケーションの `requirements.txt` またはコンストラクトライブラリの `setup.py` に配置します。その後、依存関係は PIP ツールで管理されます。PIP は、次のいずれかの方法で呼び出されます。
```
pip
python -m pip
```
`python -m pip` 呼び出しはほとんどのシステムで機能します。`pip` では、PIP の実行ファイルがシステムパスにある必要があります。`pip` が機能しない場合、`python -m pip` に置き換えてみてください。
`cdk init --language python` コマンドは、新しいプロジェクトの仮想環境を作成します。これにより、各プロジェクトに独自の依存関係のバージョン、ならびに基本的な `requirements.txt` ファイルを持たせることができます。プロジェクトの使用を開始するたびに `source .venv/bin/activate` を実行することにより、この仮想環境をアクティブ化する必要があります。Windows では、代わりに `.\venv\Scripts\activate` を実行します
### CDK アプリケーション
次は、`requirements.txt` ファイルの例です。PIP には依存関係ロック機能がないため、こちらに示すように、== 演算子を使用してすべての依存関係の正確なバージョンを指定することをお勧めします。
```
aws-cdk-lib==2.14.0
aws-cdk.aws-appsync-alpha==2.10.0a0
```
`pip install` を使用してモジュールをインストールしても、自動的に `requirements.txt` に追加されません。ユーザー自身で行う必要があります。依存関係の新しいバージョンにアップグレードする場合、`requirements.txt` でバージョン番号を編集します。
`requirements.txt` を作成または編集した後に、プロジェクトの依存関係をインストールまたは更新するには、次の内容を実行します。
```
python -m pip install -r requirements.txt
```
**ヒント**
`pip freeze` コマンドは、インストールされているすべての依存関係のバージョンをテキストファイルに書き込める形式で出力します。`pip install -r` に使用する要件ファイルとして使用できます。このファイルは、すべての依存関係 (一時的なものを含む) をテストした正確なバージョンに固定するために便利です。後でパッケージをアップグレードするときの問題を回避するには、`freeze.txt` (`requirements.txt` ではない) などの別のファイルを使用します。その後、プロジェクトの依存関係をアップグレードするときに再生成します。
### サードパーティーのコンストラクトライブラリ
ライブラリでは、依存関係は `setup.py` で指定されるため、パッケージがアプリケーションによって消費されるときに一時的な依存関係が自動的にダウンロードされます。それ以外の場合、パッケージを使用するすべてのアプリケーションは、依存関係を `requirements.txt` にコピーする必要があります。`setup.py` の例はこちらで示します。
```
from setuptools import setup
setup(
name='my-package',
version='0.0.1',
install_requires=[
'aws-cdk-lib==2.14.0',
],
...
)
```
開発用のパッケージを使用するには、仮想環境を作成またはアクティブ化してから次のコマンドを実行します。
```
python -m pip install -e .
```
PIP は一時的な依存関係を自動的にインストールしますが、いずれかのパッケージにはインストールしたものを 1 つしか使用できません。依存関係ツリーで最も高いバージョンとして指定されているバージョンが選択されます。アプリケーションは常に、インストールされるパッケージのバージョンで最後の単語が含まれます。
## AWS Python の CDK イディオム
### 言語の競合
Python では、 `lambda`は言語キーワードであるため、 AWS Lambda コンストラクトライブラリモジュールまたは Lambda 関数の名前として使用することはできません。このような競合における Python 規則は、`lambda_` のように変数名の末尾にアンダースコアを付けることです。
慣例により、 AWS CDK コンストラクトの 2 番目の引数は という名前です`id`。独自のスタックおよびコンストラクトを記述するとき、パラメータに `id` という名前を付けると、オブジェクトの一意な識別子を返す Python のビルトイン関数 `id()` を「シャドウイング」してしまいます。この関数は頻繁に使用されませんが、コンストラクトで必要になった場合、引数の名前を変更します (例えば、`construct_id` など)。
### 引数とプロパティ
すべての AWS コンストラクトライブラリクラスは、3 つの引数を使用してインスタンス化されます。つまり、コンストラクトが定義されている*スコープ* (コンストラクトツリー内の親）、*ID*、*props*、コンストラクトが作成するリソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドでは、引数に「属性のバンドル」パターンも使用されます。
コンストラクトが*scope* または *ID* という名前のプロパティを受け入れた場合、名前が変わるため、*scope* および *ID* はキーワード引数ではなく、常に位置引数として渡す必要があります。
Python では、props はキーワード引数として表現されます。引数にネストされたデータ構造が含まれている場合、インスタンス化時に独自のキーワード引数を取るクラスを使用して表現されます。構造化された引数を取る他のメソッドの呼び出しにも、同じパターンが適用されます。
例えば、Amazon S3 バケットの `add_lifecycle_rule` メソッドでは、`transitions` プロパティは `Transition` インスタンスのリストです。
```
bucket.add_lifecycle_rule(
transitions=[
Transition(
storage_class=StorageClass.GLACIER,
transition_after=Duration.days(10)
)
]
)
```
クラスを拡張またはメソッドを上書きするとき、親クラスに理解されない独自の目的で追加の引数を受け入れることができます。この場合、\$1\$1kwargs イディオムを使用して関心のない引数を受け入れたら、キーワードのみの引数を使用し、関心のある引数を受け入れる必要があります。親のコンストラクタまたは上書きされたメソッドを呼び出すとき、予期している引数のみを渡します (多くの場合は \$1\$1kwargs のみ)。親クラスまたはメソッドが予想しない引数を渡すと、エラーが発生します。
```
class MyConstruct(Construct):
def __init__(self, id, *, MyProperty=42, **kwargs):
super().__init__(self, id, **kwargs)
# ...
```
AWS CDK の今後のリリースでは、独自のプロパティに使用した名前の新しいプロパティが同時に追加される可能性があります。コンストラクトまたはメソッドのユーザーに技術的な問題が発生することはありません (プロパティが「上の階層」に渡されないため、親クラスまたは上書きされたメソッドは単にデフォルト値を使用)。ただし、混乱を招く可能性があります。明確にコンストラクトに属するようにプロパティに名前を付けることにより、この潜在的な問題を回避できます。新しいプロパティが多数ある場合、適切に名前が付けられたクラスにバンドルし、単一のキーワード引数として渡します。
### 欠落した値
AWS CDK は `None` を使用して欠落または未定義の値を表します。\$1\$1kwargs を使用するとき、ディクショナリの `get()` メソッドを使用し、プロパティが指定されていない場合はデフォルト値を指定します。欠落値に対して `KeyError` がフラグされるため、`kwargs[…]` は使用しないでください。
```
encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists
encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing
```
一部の AWS CDK メソッド (ランタイムコンテキスト値`tryGetContext()`を取得するなど) は`None`、明示的に確認する必要がある を返す場合があります。
### インターフェイスの使用
他の言語とは違い、Python にはインターフェイス機能はありませんが、同様な[抽象ベースクラス](https://docs.python.org/3/library/abc.html)があります。(インターフェイスに慣れていない場合、Wikipedia には[わかりやすい概要](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages)があります) TypeScript は、 AWS CDK が実装されている言語であり、インターフェイスを提供し、コンストラクトやその他の AWS CDK オブジェクトには、多くの場合、特定のクラスから継承するのではなく、特定のインターフェイスに準拠するオブジェクトが必要です。したがって、 AWS CDK は [JSII](https://github.com/aws/jsii) レイヤーの一部として独自のインターフェイス機能を提供します。
クラスが特定のインターフェイスを実装することを示すには、`@jsii.implements` デコレータを使用できます。
```
from aws_cdk import IAspect, IConstruct
import jsii
@jsii.implements(IAspect)
class MyAspect():
def visit(self, node: IConstruct) -> None:
print("Visited", node.node.path)
```
### 型の落とし穴
Python は動的型付けを使用し、すべての変数は任意の型の値を参照します。パラメータおよび戻り値は型で注釈を付けることができますが、これらは「ヒント」であって強制されません。つまり、Python では、間違ったタイプの値を AWS CDK コンストラクトに簡単に渡すことができます。静的に型指定された言語の場合と同様に、ビルド中に型エラーが発生する代わりに、JSII レイヤー (Python と AWS CDK の TypeScript コアの間で変換されます) が予期しない型に対応できない場合にランタイムエラーが発生することがあります。
経験上、Python プログラマーが行うタイプエラーは、これらのカテゴリに分類される傾向があります。
+ コンストラクトがコンテナ (Python リストまたはディクショナリ) を予想する単一の値を渡すか、その逆を行います。
+ レイヤー 1 (`CfnXxxxxx`) コンストラクトに関連付けられたタイプの値を L2 または L3 コンストラクトに渡すか、その逆を行います。
## タイプエラーの防止
AWS CDK Python モジュールには型注釈が含まれているため、それらをサポートするツールを使用して、デプロイ前に型エラーをキャッチできます。
### IDE 統合 (推奨)
Visual Studio Code with Pylance は、コードを記述するときにリアルタイムの型チェックを提供します。
1. [Pylance 拡張機能](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)をインストールする
1. で厳密な型チェックを設定します`.vscode/settings.json`。
```
{
"python.languageServer": "Pylance",
"python.analysis.typeCheckingMode": "strict"
}
```
1. タイプエラーが赤のスイグルと詳細なエラーメッセージですぐに表示されるようになりました
[PyCharm](https://www.jetbrains.com/pycharm/) は、同様の機能を備えた組み込み型チェックも提供します。
### コマンドラインタイプのチェック
CI/CD パイプラインまたはコミット前検証の場合は、次のいずれかのタイプチェッカーを使用します。
**MyPy (Python ベース):**
```
pip install mypy
mypy app.py
```
**Pyright (高速、JavaScript ベース、Pylance と同じエンジン):**
```
npm install -g pyright
pyright app.py
```
### 推奨されるワークフロー
1. 開発中: Pyright または Pylance を使用して即時フィードバックを行う
1. コミット前: `mypy app.py`または を実行 `pyright app.py`
1. CI/CD の場合: デプロイ前に必要なステップをタイプチェックする
# Java での AWS CDK の使用
Java は AWS CDK で完全にサポートされているクライアント言語であり、安定していると見なされます。JDK (Oracle または Amazon Corretto などの OpenJDK ディストリビューション) や Apache Maven などの使い慣れたツールを使用して、Java で AWS CDK アプリケーションを開発できます。
AWS CDK は Java 8 以降をサポートしています。ただし、新しいバージョンの言語には AWS CDK アプリケーションの開発に特に便利な改善点が含まれているため、使用できる最新バージョンを使用することをお勧めします。例えば、Java 9 は `Map.of()` メソッド (TypeScript でオブジェクトリテラルとして記述されるハッシュマップを宣言する便利な方法) を導入します。Java 10 は、`var` キーワードを使用してローカル型推論を導入します。
**注記**
このデベロッパーガイドに記載されているほとんどのコード例は、Java 8 で対応します。いくつかの例では `Map.of()` を使用しています。これらの例には、Java 9 が必要であることを示すコメントが含まれます。
任意のテキストエディタ、または Maven プロジェクトを読み取ることができる Java IDE を使用して、 AWS CDK アプリを操作できます。このガイドでは [Eclipse](https://www.eclipse.org/downloads/) ヒントを提供していますが、IntelliJ IDEA、NetBeans、およびその他の IDEs は Maven プロジェクトをインポートでき、Java での AWS CDK アプリケーションの開発に使用できます。
Java 以外の JVM がホストする言語 (Kotlin、Groovy、Clojure、Scala など) で AWS CDK アプリケーションを記述することは可能ですが、エクスペリエンスが特に特異ではない可能性があり、これらの言語をサポートすることはできません。
## Java の使用を開始する
AWS CDK を使用するには、 AWS アカウントと認証情報があり、Node.js と AWS CDK Toolkit がインストールされている必要があります。[AWS 「CDK の開始方法」を参照してください](getting-started.md)。
Java AWS CDK アプリケーションには Java 8 (v1.8) 以降が必要です。[Amazon Corretto](https://aws.amazon.com/corretto/) をお勧めしますが、任意の OpenJDK ディストリビューションまたは [Oracle の JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) を使用できます。[Apache Maven](https://maven.apache.org/download.cgi) 3.5 以降も必要です。Gradle などのツールを使用することもできますが、 AWS CDK Toolkit によって生成されるアプリケーションスケルトンは Maven プロジェクトです。
**注記**
サードパーティー言語の廃止: 言語バージョンは、ベンダーまたはコミュニティによって共有される EOL (製品終了) までのみサポートされ、事前の通知によって変更されます。
## プロジェクトの作成
空のディレクトリ`cdk init`で を呼び出して、新しい AWS CDK プロジェクトを作成します。`--language` オプションを使用して `java` を指定します。
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language java
```
`cdk init` はプロジェクトフォルダの名前を使用し、クラス、サブフォルダ、ファイルなどのプロジェクトのさまざまな要素に名前を付けます。フォルダ名に含まれるハイフンはアンダースコアに変換されます。ただし、それ以外の場合、名前は Java 識別子の形式に従う必要があります。例えば、数字で始まったり、スペースを含めたりすることはできません。
結果のプロジェクトには、`software.amazon.awscdk` Maven パッケージへのリファレンスが含まれています。プロジェクトおよびその依存関係は、Maven によって自動的にインストールされます。
IDE を使用している場合は、これでプロジェクトを開くかインポートできるようになります。たとえば Eclipse では、**[ファイル]**、**[インポート]**、**[Maven]**、**[既存の Maven プロジェクト]** を選択します。プロジェクト設定が Java 8 (1.8) を使用するように設定されていることを確認してください。
## AWS コンストラクトライブラリモジュールの管理
Maven を使用して、グループ にある AWS コンストラクトライブラリパッケージをインストールします`software.amazon.awscdk`。ほとんどのコンストラクトは `aws-cdk-lib` アーティファクトにあり、デフォルトで新しい Java プロジェクトに追加されます。上位レベルの CDK サポートがまだ開発中のサービスのモジュールは、サービス名の短いバージョン ( AWS または Amazon プレフィックスなし) で命名された個別の「実験」パッケージにあります。[Maven Central Repository を検索](https://search.maven.org/search?q=software.amazon.awscdk)して、すべての AWS CDK ライブラリと AWS コンストラクトモジュールライブラリの名前を検索します。
**注記**
[CDK API リファレンスの Java エディション](https://docs.aws.amazon.com/cdk/api/v2/java/index.html)にも、パッケージ名が表示されます。
一部のサービス AWS 「コンストラクトライブラリのサポート」は複数の名前空間にあります。例えば、Amazon Route 53 には `software.amazon.awscdk.route53`、`route53-patterns`、`route53resolver`、`route53-targets` に分割された機能があります。
メイン AWS CDK パッケージは として Java コードにインポートされます`software.amazon.awscdk`。 AWS コンストラクトライブラリのさまざまなサービスのモジュールは`software.amazon.awscdk.services`、Maven パッケージ名と同様に の下にあり、名前が付けられます。例えば、Amazon S3 モジュールの名前空間は `software.amazon.awscdk.services.s3` です。
各 Java ソースファイルで使用する AWS コンストラクトライブラリクラスごとに個別の Java `import`ステートメントを記述し、ワイルドカードインポートを避けることをお勧めします。`import` ステートメントなしで、型の完全な修飾名 (名前空間を含む) をいつでも使用できます。
アプリケーションが実験パッケージに依存している場合、プロジェクトの `pom.xml` を編集して `` コンテナに新しい `` 要素を追加します。例えば、次の `` 要素は CodeStar 実験コンストラクトライブラリモジュールを指定します。
```
software.amazon.awscdk
codestar-alpha
2.0.0-alpha.10
```
**ヒント**
Java IDE を使用する場合、Maven の依存関係を管理する機能がある可能性が高くなります。ただし、IDE の機能が手動で行うものと一致することを確実に確認されていない限り、`pom.xml` を直接編集することをお勧めします。
## Java の依存関係の管理
Java では依存関係は `pom.xml` で指定され、Maven を使用してインストールされます。`` コンテナには、パッケージごとに `` 要素が含まれます。次の内容は、一般的な CDK Java アプリの `pom.xml` のセクションです。
```
software.amazon.awscdk
aws-cdk-lib
2.14.0
software.amazon.awscdk
appsync-alpha
2.10.0-alpha.0
```
**ヒント**
多くの Java IDEs には統合された Maven サポートおよびビジュアル `pom.xml` エディタを備えており、依存関係の管理に便利です。
Maven は依存関係ロックをサポートしていません。`pom.xml` でバージョン範囲を指定することは可能ですが、ビルドを再現できるように必ずに正確なバージョンを使用することをお勧めします。
Maven は一時的な依存関係を自動的にインストールしますが、各パッケージにはインストールしたものを 1 つしか使用できません。POM ツリーで最も高く指定されたバージョンが選択されます。アプリケーションは常に、インストールされるパッケージのバージョンで最後の単語が含まれます。
プロジェクトを構築 (`mvn compile`) またはパッケージ化 (`mvn package`) するたびに、Maven は依存関係を自動的にインストールまたは更新します。CDK Toolkit は、実行するたびに自動的にこれを行うため、通常は Maven を手動で呼び出す必要はありません。
## AWS Java の CDK イディオム
### Props
すべての AWS コンストラクトライブラリクラスは、3 つの引数を使用してインスタンス化されます。つまり、コンストラクトが定義されている*スコープ* (コンストラクトツリー内の親）、*ID*、*props*、コンストラクトが作成するリソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドでは、引数に「属性のバンドル」パターンも使用されます。
Java では、props は[ビルダーパターン](https://en.wikipedia.org/wiki/Builder_pattern)を使用して表現されます。各コンストラクトタイプには対応する props 型があります。例えば、`Bucket` コンストラクト (Amazon S3 バケットを表す) は、`BucketProps` のインスタンスを props として取ります。
`BucketProps` クラス (すべての AWS コンストラクトライブラリ props クラスなど) には、 という内部クラスがあります`Builder`。`BucketProps.Builder` タイプには、`BucketProps` インスタンスのさまざまなプロパティを設定する方法が用意されています。各メソッドは `Builder` インスタンスを返すため、メソッドの呼び出しを連鎖させて複数のプロパティを設定できます。チェーンの最後に `build()` を呼び出し、`BucketProps` オブジェクトを実際に生成します。
```
Bucket bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps.Builder()
.versioned(true)
.encryption(BucketEncryption.KMS_MANAGED)
.build());
```
コンストラクト、ならびに props のようなオブジェクトを最終引数とする他のクラスは、ショートカットを提供します。クラスには独自の `Builder` があり、1 つのステップでクラスとその props オブジェクトをインスタンス化します。これにより、`BucketProps` と `Bucket` の両方を明示的にインスタンス化 (例えば) する必要はなく、props 型にインポートする必要はありません。
```
Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket")
.versioned(true)
.encryption(BucketEncryption.KMS_MANAGED)
.build();
```
既存のコンストラクトから独自のコンストラクトを取得するとき、追加のプロパティを受け入れることができます。これらのビルダーパターンに従うことをお勧めします。ただし、コンストラクトクラスのサブクラス化ほど簡単ではありません。2 つの新しい `Builder` クラスの可動部をご自身で指定する必要があります。コンストラクトに 1 つ以上の追加引数を単に受け入れることができます。引数がオプションの場合、追加のコンストラクターを指定する必要があります。
### 汎用構造
一部の APIs では、 AWS CDK はメソッドへの入力として JavaScript 配列または型なしオブジェクトを使用します。( AWS CodeBuild の [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue)メソッドなどを参照してください）。Java では、これらのオブジェクトは `java.util.Map` として表されます。値がすべて文字列の場合、`Map` を使用できます。
他の言語とは違い、Java はこのようなコンテナのリテラルを記述する方法を提供しません。Java 9 以降では、[https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-) を使用してこれらの呼び出しのいずれかにより、インラインで最大 10 エントリのマップを簡単に定義できます。
```
java.util.Map.of(
"base-directory", "dist",
"files", "LambdaStack.template.json"
)
```
10 を超えるエントリを持つマップを作成するには、[https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…-) を使用します。
Java 8 を使用している場合、次のような内容と同様に独自の方法を指定できます。
JavaScript 配列は Java で `List