Ini adalah Panduan Pengembang AWS CDK v2. CDK v1 yang lebih lama memasuki pemeliharaan pada 1 Juni 2022 dan mengakhiri dukungan pada 1 Juni 2023. Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Bekerja dengan AWS CDK dengan Python Python adalah bahasa klien yang sepenuhnya didukung untuk AWS Cloud Development Kit (AWS CDK) dan dianggap stabil. Bekerja dengan AWS CDK di Python menggunakan alat yang sudah dikenal, termasuk implementasi Python standar CPython (), lingkungan virtual dengan`virtualenv`, dan penginstal paket Python. `pip` [Modul yang terdiri dari AWS Construct Library didistribusikan melalui pypi.org.](https://pypi.org/search/?q=aws-cdk) Versi Python dari AWS CDK bahkan menggunakan pengidentifikasi gaya Python (misalnya, nama metode). `snake_case` Anda dapat menggunakan editor atau IDE apa pun. [Banyak pengembang AWS CDK menggunakan [Visual Studio Code](https://code.visualstudio.com/) (atau padanan open-source [VSCodium](https://vscodium.com/)), yang memiliki dukungan yang baik untuk Python melalui ekstensi resmi.](https://marketplace.visualstudio.com/items?itemName=ms-python.python) Editor IDLE yang disertakan dengan Python sudah cukup untuk memulai. Modul Python untuk AWS CDK memang memiliki petunjuk tipe, yang berguna untuk alat linting atau IDE yang mendukung validasi tipe. ## Memulai dengan Python Untuk bekerja dengan AWS CDK, Anda harus memiliki AWS akun dan kredensil dan telah menginstal Node.js dan CDK Toolkit. AWS Lihat [Memulai dengan AWS CDK](getting-started.md). Aplikasi AWS CDK Python membutuhkan Python 3.9 atau yang lebih baru. Jika Anda belum menginstalnya, [unduh versi yang kompatibel](https://www.python.org/downloads/) untuk sistem operasi Anda di [python.org](https://www.python.org/). Jika Anda menjalankan Linux, sistem Anda mungkin datang dengan versi yang kompatibel, atau Anda dapat menginstalnya menggunakan manajer paket distro Anda (`yum`,`apt`, dll.). Pengguna Mac mungkin tertarik dengan [Homebrew](https://brew.sh/), pengelola paket bergaya Linux untuk macOS. **catatan** Pengakhiran bahasa pihak ketiga: versi bahasa hanya didukung hingga EOL (End Of Life) dibagikan oleh vendor atau komunitas dan dapat berubah sewaktu-waktu dengan pemberitahuan sebelumnya. Penginstal paket Python,`pip`, dan manajer lingkungan virtual`virtualenv`, juga diperlukan. Instalasi Windows dari versi Python yang kompatibel termasuk alat-alat ini. Di Linux, `pip` dan `virtualenv` dapat disediakan sebagai paket terpisah di manajer paket Anda. Atau, Anda dapat menginstalnya dengan perintah berikut: ``` python -m ensurepip --upgrade python -m pip install --upgrade pip python -m pip install --upgrade virtualenv ``` Jika Anda mengalami kesalahan izin, jalankan perintah di atas dengan `--user` bendera sehingga modul diinstal di direktori pengguna Anda, atau gunakan `sudo` untuk mendapatkan izin untuk menginstal modul di seluruh sistem. **catatan** Hal ini umum untuk distro Linux untuk menggunakan nama executable untuk `python3` Python 3.x, dan telah merujuk `python` ke instalasi Python 2.x. Beberapa distro memiliki paket opsional yang dapat Anda instal yang membuat `python` perintah mengacu pada Python 3. Jika gagal, Anda dapat menyesuaikan perintah yang digunakan untuk menjalankan aplikasi Anda dengan mengedit `cdk.json` di direktori utama proyek. **catatan** Di Windows, Anda mungkin ingin memanggil Python (`pip`dan) menggunakan executable, `py` peluncur [Python untuk](https://docs.python.org/3/using/windows.html#launcher) Windows. Antara lain, peluncur memungkinkan Anda untuk dengan mudah menentukan versi Python yang diinstal yang ingin Anda gunakan. Jika mengetik `python` di baris perintah menghasilkan pesan tentang menginstal Python dari Windows Store, bahkan setelah menginstal Python versi Windows, buka panel pengaturan Alias Eksekusi Aplikasi Windows dan matikan dua entri Penginstal Aplikasi untuk Python. ## Membuat proyek Anda membuat proyek AWS CDK baru dengan memanggil `cdk init` di direktori kosong. Gunakan `--language` opsi dan tentukan`python`: ``` $ mkdir my-project $ cd my-project $ cdk init app --language python ``` `cdk init`menggunakan nama folder proyek untuk memberi nama berbagai elemen proyek, termasuk kelas, subfolder, dan file. Tanda hubung dalam nama folder diubah menjadi garis bawah. Namun, nama tersebut harus mengikuti bentuk pengenal Python; misalnya, seharusnya tidak dimulai dengan angka atau berisi spasi. Untuk bekerja dengan proyek baru, aktifkan lingkungan virtualnya. Ini memungkinkan dependensi proyek diinstal secara lokal di folder proyek, bukan secara global. ``` $ source .venv/bin/activate ``` **catatan** Anda mungkin mengenali ini sebagai Mac/Linux perintah untuk mengaktifkan lingkungan virtual. Templat Python menyertakan file batch, `source.bat`, yang memungkinkan perintah yang sama untuk digunakan pada Windows. Perintah Windows tradisional juga berfungsi. `.\venv\Scripts\activate` Jika Anda menginisialisasi proyek AWS CDK Anda menggunakan CDK Toolkit v1.70.0 atau yang lebih lama, lingkungan virtual Anda ada di direktori, bukan. `.env` `.venv` **penting** Aktifkan lingkungan virtual proyek setiap kali Anda mulai mengerjakannya. Jika tidak, Anda tidak akan memiliki akses ke modul yang diinstal di sana, dan modul yang Anda instal akan masuk ke direktori modul global Python (atau akan menghasilkan kesalahan izin). Setelah mengaktifkan lingkungan virtual Anda untuk pertama kalinya, instal dependensi standar aplikasi: ``` $ python -m pip install -r requirements.txt ``` ## Mengelola AWS modul Construct Library Gunakan penginstal paket Python,`pip`, untuk menginstal dan memperbarui modul AWS Construct Library untuk digunakan oleh aplikasi Anda, serta paket lain yang Anda butuhkan. `pip`juga menginstal dependensi untuk modul-modul tersebut secara otomatis. Jika sistem Anda tidak mengenali `pip` sebagai perintah mandiri, panggil `pip` sebagai modul Python, seperti ini: ``` $ python -m pip ``` Sebagian besar konstruksi AWS CDK ada di. `aws-cdk-lib` Modul eksperimental berada dalam modul terpisah bernama like`aws-cdk..alpha`. Nama layanan menyertakan awalan *aws*. Jika Anda tidak yakin dengan nama modul, [cari di PyPI](https://pypi.org/search/?q=aws-cdk). Misalnya, perintah di bawah ini menginstal AWS CodeStar perpustakaan. ``` $ python -m pip install aws-cdk.aws-codestar-alpha ``` Beberapa konstruksi layanan berada di lebih dari satu namespace. Misalnya, selain itu`aws-cdk.aws-route53`, ada tiga ruang nama Amazon Route 53 tambahan, bernama `aws-route53-targets``aws-route53-patterns`, dan. `aws-route53resolver` **catatan** [Edisi Python dari Referensi API CDK](https://docs.aws.amazon.com/cdk/api/v2/python/index.html) juga menunjukkan nama paket. Nama-nama yang digunakan untuk mengimpor modul AWS Construct Library ke dalam kode Python Anda terlihat seperti berikut ini. ``` import aws_cdk.aws_s3 as s3 import aws_cdk.aws_lambda as lambda_ ``` Kami merekomendasikan praktik berikut saat mengimpor kelas AWS CDK dan modul AWS Construct Library di aplikasi Anda. Mengikuti panduan ini akan membantu membuat kode Anda konsisten dengan aplikasi AWS CDK lainnya serta lebih mudah dipahami. + Umumnya, impor kelas individu dari tingkat atas`aws_cdk`. ``` from aws_cdk import App, Construct ``` + Jika Anda membutuhkan banyak kelas dari`aws_cdk`, Anda dapat menggunakan alias namespace `cdk` alih-alih mengimpor kelas individual. Hindari melakukan keduanya. ``` import aws_cdk as cdk ``` + Umumnya, impor AWS Construct Libraries menggunakan alias namespace pendek. ``` import aws_cdk.aws_s3 as s3 ``` Setelah menginstal modul, perbarui `requirements.txt` file proyek Anda, yang mencantumkan dependensi proyek Anda. Yang terbaik adalah melakukan ini secara manual daripada menggunakan`pip freeze`. `pip freeze`menangkap versi saat ini dari semua modul yang diinstal di lingkungan virtual Python Anda, yang dapat berguna saat menggabungkan proyek untuk dijalankan di tempat lain. Namun, biasanya, Anda hanya `requirements.txt` boleh mencantumkan dependensi tingkat atas (modul yang bergantung langsung pada aplikasi Anda) dan bukan dependensi pustaka tersebut. Strategi ini membuat memperbarui dependensi Anda lebih sederhana. Anda dapat mengedit `requirements.txt` untuk mengizinkan peningkatan; cukup ganti nomor versi `==` sebelumnya dengan `~=` untuk memungkinkan peningkatan ke versi kompatibel yang lebih tinggi, atau hapus persyaratan versi sepenuhnya untuk menentukan versi modul terbaru yang tersedia. Dengan `requirements.txt` diedit dengan tepat untuk memungkinkan peningkatan, keluarkan perintah ini untuk memutakhirkan modul yang diinstal proyek Anda kapan saja: ``` $ pip install --upgrade -r requirements.txt ``` ## Mengelola dependensi dengan Python Dengan Python, Anda menentukan dependensi dengan memasukkannya ke dalam aplikasi atau `requirements.txt` `setup.py` untuk membangun perpustakaan. Dependensi kemudian dikelola dengan alat PIP. PIP dipanggil dengan salah satu cara berikut: ``` pip python -m pip ``` `python -m pip`Pemanggilan bekerja pada sebagian besar sistem; `pip` mengharuskan PIP yang dapat dieksekusi berada di jalur sistem. Jika `pip` tidak berhasil, coba ganti dengan`python -m pip`. `cdk init --language python`Perintah menciptakan lingkungan virtual untuk proyek baru Anda. Ini memungkinkan setiap proyek memiliki versi dependensi sendiri, dan juga file dasar`requirements.txt`. Anda harus mengaktifkan lingkungan virtual ini dengan menjalankan `source .venv/bin/activate` setiap kali Anda mulai bekerja dengan proyek. Di Windows, jalankan `.\venv\Scripts\activate` sebagai gantinya ### Aplikasi CDK Berikut ini adalah contoh `requirements.txt` file. Karena PIP tidak memiliki fitur penguncian ketergantungan, kami menyarankan Anda menggunakan operator == untuk menentukan versi yang tepat untuk semua dependensi, seperti yang ditunjukkan di sini. ``` aws-cdk-lib==2.14.0 aws-cdk.aws-appsync-alpha==2.10.0a0 ``` Menginstal modul dengan `pip install` tidak secara otomatis menambahkannya`requirements.txt`. Anda harus melakukannya sendiri. Jika Anda ingin meningkatkan ke versi dependensi yang lebih baru, edit nomor versinya di`requirements.txt`. Untuk menginstal atau memperbarui dependensi proyek Anda setelah membuat atau mengedit`requirements.txt`, jalankan yang berikut: ``` python -m pip install -r requirements.txt ``` **Tip** `pip freeze`Perintah mengeluarkan versi semua dependensi yang diinstal dalam format yang dapat ditulis ke file teks. Ini dapat digunakan sebagai file persyaratan dengan`pip install -r`. File ini nyaman untuk menyematkan semua dependensi (termasuk yang transitif) ke versi persis yang Anda uji. Untuk menghindari masalah saat memutakhirkan paket nanti, gunakan file terpisah untuk ini, seperti `freeze.txt` (not`requirements.txt`). Kemudian, buat ulang saat Anda memutakhirkan dependensi proyek Anda. ### Perpustakaan konstruksi pihak ketiga Di pustaka, dependensi ditentukan dalam`setup.py`, sehingga dependensi transitif diunduh secara otomatis ketika paket dikonsumsi oleh aplikasi. Jika tidak, setiap aplikasi yang ingin menggunakan paket Anda perlu menyalin dependensi Anda ke dalamnya. `requirements.txt` Contoh `setup.py` ditampilkan di sini. ``` from setuptools import setup setup( name='my-package', version='0.0.1', install_requires=[ 'aws-cdk-lib==2.14.0', ], ... ) ``` Untuk mengerjakan paket untuk pengembangan, buat atau aktifkan lingkungan virtual, lalu jalankan perintah berikut. ``` python -m pip install -e . ``` Meskipun PIP secara otomatis menginstal dependensi transitif, hanya ada satu salinan yang diinstal dari satu paket. Versi yang ditentukan tertinggi di pohon ketergantungan dipilih; aplikasi selalu memiliki kata terakhir dalam versi paket apa yang diinstal. ## AWS Idiom CDK dengan Python ### Konflik bahasa Dalam Python, `lambda` adalah kata kunci bahasa, sehingga Anda tidak dapat menggunakannya sebagai nama untuk modul perpustakaan konstruksi Lambda atau AWS fungsi Lambda. Konvensi Python untuk konflik tersebut adalah dengan menggunakan garis bawah, seperti pada`lambda_`, dalam nama variabel. Menurut konvensi, argumen kedua untuk konstruksi AWS CDK diberi nama. `id` Saat menulis tumpukan dan konstruksi Anda sendiri, memanggil parameter `id` “bayangan” fungsi bawaan Python`id()`, yang mengembalikan pengenal unik objek. Fungsi ini tidak sering digunakan, tetapi jika Anda membutuhkannya dalam konstruksi Anda, ganti nama argumen, misalnya. `construct_id` ### Argumen dan properti Semua kelas AWS Construct Library dipakai menggunakan tiga argumen: *lingkup* di mana konstruksi sedang didefinisikan (induknya di pohon konstruksi), *id*, dan *props*, bundel key/value pasangan yang digunakan konstruksi untuk mengkonfigurasi sumber daya yang dibuatnya. Kelas dan metode lain juga menggunakan pola “bundel atribut” untuk argumen. *scope* *dan *id* harus selalu diteruskan sebagai argumen posisi, bukan argumen kata kunci, karena namanya berubah jika konstruksi menerima properti bernama *scope* atau id.* Dalam Python, props dinyatakan sebagai argumen kata kunci. Jika argumen berisi struktur data bersarang, ini diekspresikan menggunakan kelas yang mengambil argumen kata kunci sendiri di instantiation. Pola yang sama diterapkan pada panggilan metode lain yang mengambil argumen terstruktur. Misalnya, dalam `add_lifecycle_rule` metode bucket Amazon S3, `transitions` properti adalah daftar instance. `Transition` ``` bucket.add_lifecycle_rule( transitions=[ Transition( storage_class=StorageClass.GLACIER, transition_after=Duration.days(10) ) ] ) ``` Saat memperluas kelas atau mengganti metode, Anda mungkin ingin menerima argumen tambahan untuk tujuan Anda sendiri yang tidak dipahami oleh kelas induk. Dalam hal ini Anda harus menerima argumen yang tidak Anda pedulikan menggunakan idiom \$1\$1kwargs, dan menggunakan argumen khusus kata kunci untuk menerima argumen yang Anda minati. Saat memanggil konstruktor induk atau metode yang diganti, berikan hanya argumen yang diharapkannya (seringkali hanya \$1\$1 kwargs). Melewati argumen bahwa kelas induk atau metode tidak mengharapkan hasil kesalahan. ``` class MyConstruct(Construct): def __init__(self, id, *, MyProperty=42, **kwargs): super().__init__(self, id, **kwargs) # ... ``` Rilis AWS CDK di masa depan secara kebetulan dapat menambahkan properti baru dengan nama yang Anda gunakan untuk properti Anda sendiri. Ini tidak akan menyebabkan masalah teknis apa pun bagi pengguna konstruksi atau metode Anda (karena properti Anda tidak melewati “rantai”, kelas induk atau metode yang diganti hanya akan menggunakan nilai default) tetapi dapat menyebabkan kebingungan. Anda dapat menghindari masalah potensial ini dengan memberi nama properti Anda sehingga mereka jelas milik konstruksi Anda. Jika ada banyak properti baru, bundel mereka ke dalam kelas yang diberi nama tepat dan meneruskannya sebagai argumen kata kunci tunggal. ### Nilai yang hilang AWS CDK digunakan `None` untuk mewakili nilai yang hilang atau tidak ditentukan. Saat bekerja dengan\$1\$1kwargs, gunakan `get()` metode kamus untuk memberikan nilai default jika properti tidak disediakan. Hindari penggunaan`kwargs[…​]`, karena ini menimbulkan nilai `KeyError` yang hilang. ``` encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing ``` Beberapa metode AWS CDK (seperti `tryGetContext()` untuk mendapatkan nilai konteks runtime) mungkin kembali`None`, yang perlu Anda periksa secara eksplisit. ### Menggunakan antarmuka Python tidak memiliki fitur antarmuka seperti beberapa bahasa lain, meskipun memang memiliki [kelas dasar abstrak](https://docs.python.org/3/library/abc.html), yang serupa. (Jika Anda tidak terbiasa dengan antarmuka, Wikipedia memiliki [pengantar yang bagus](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages).) TypeScript, bahasa di mana AWS CDK diimplementasikan, memang menyediakan antarmuka, dan konstruksi dan objek AWS CDK lainnya sering memerlukan objek yang melekat pada antarmuka tertentu, daripada mewarisi dari kelas tertentu. Jadi AWS CDK menyediakan fitur antarmuka sendiri sebagai bagian dari lapisan [JSII](https://github.com/aws/jsii). Untuk menunjukkan bahwa kelas mengimplementasikan antarmuka tertentu, Anda dapat menggunakan `@jsii.implements` dekorator: ``` from aws_cdk import IAspect, IConstruct import jsii @jsii.implements(IAspect) class MyAspect(): def visit(self, node: IConstruct) -> None: print("Visited", node.node.path) ``` ### Jenis jebakan Python menggunakan pengetikan dinamis, di mana semua variabel dapat merujuk ke nilai jenis apa pun. Parameter dan nilai pengembalian dapat dianotasi dengan tipe, tetapi ini adalah “petunjuk” dan tidak diberlakukan. Ini berarti bahwa dengan Python, mudah untuk meneruskan jenis nilai yang salah ke konstruksi AWS CDK. Alih-alih mendapatkan kesalahan tipe selama pembuatan, seperti yang Anda lakukan dari bahasa yang diketik secara statis, Anda mungkin mendapatkan kesalahan runtime ketika lapisan JSII (yang menerjemahkan antara Python dan inti CDK TypeScript ) tidak dapat menangani tipe AWS yang tidak terduga. Menurut pengalaman kami, kesalahan tipe yang dilakukan programmer Python cenderung masuk dalam kategori ini. + Melewati satu nilai di mana konstruksi mengharapkan wadah (daftar Python atau kamus) atau sebaliknya. + Melewati nilai tipe yang terkait dengan konstruksi layer 1 (`CfnXxxxxx`) ke konstruksi L2 atau L3, atau sebaliknya. ## Mencegah kesalahan tipe Modul AWS CDK Python menyertakan anotasi tipe, sehingga Anda dapat menggunakan alat yang mendukungnya untuk menangkap kesalahan tipe sebelum penerapan. ### Integrasi IDE (disarankan) Visual Studio Code dengan Pylance menyediakan pengecekan tipe real-time saat Anda menulis kode: 1. Instal ekstensi [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) 1. Konfigurasikan pemeriksaan tipe ketat`.vscode/settings.json`: ``` { "python.languageServer": "Pylance", "python.analysis.typeCheckingMode": "strict" } ``` 1. Kesalahan ketik sekarang segera muncul dengan coretan merah dan pesan kesalahan terperinci [PyCharm](https://www.jetbrains.com/pycharm/)juga menyediakan pemeriksaan tipe bawaan dengan kemampuan serupa. ### Pemeriksaan tipe baris perintah Untuk CI/CD pipeline atau validasi pra-komit, gunakan salah satu dari jenis checker ini: **MyPy (Berbasis Python):** ``` pip install mypy mypy app.py ``` **Pyright (lebih cepat, JavaScript berbasis, mesin yang sama dengan Pylance):** ``` npm install -g pyright pyright app.py ``` ### Alur kerja yang direkomendasikan 1. Selama pengembangan: Gunakan Pyright atau Pylance untuk umpan balik instan 1. Sebelum komit: Jalankan `mypy app.py` atau `pyright app.py` 1. Dalam CI/CD: Jadikan pemeriksaan tipe sebagai langkah yang diperlukan sebelum penerapan