これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 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 の場合: デプロイ前に必要なステップをタイプチェックする