Dies ist der AWS CDK v2-Entwicklerhandbuch. Das ältere CDK v1 wurde am 1. Juni 2022 gewartet und der Support wurde am 1. Juni 2023 eingestellt. Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Arbeiten mit dem AWS CDK in Python Python ist eine vollständig unterstützte Client-Sprache für das AWS Cloud Development Kit (AWS CDK) und gilt als stabil. Bei der Arbeit mit dem AWS CDK in Python werden vertraute Tools verwendet, darunter die Standard-Python-Implementierung (CPython), virtuelle Umgebungen mit `virtualenv` und das Python-Paketinstallationsprogramm`pip`. Die Module, aus denen die AWS Construct-Bibliothek besteht, werden über [pypi.org](https://pypi.org/search/?q=aws-cdk) vertrieben. Die Python-Version des AWS CDK verwendet sogar Bezeichner im Python-Stil (z. B. Methodennamen). `snake_case` Sie können jeden Editor oder jede IDE verwenden. Viele AWS CDK-Entwickler verwenden [Visual Studio Code](https://code.visualstudio.com/) (oder sein Open-Source-Äquivalent [VSCodium](https://vscodium.com/)), das Python über eine [offizielle](https://marketplace.visualstudio.com/items?itemName=ms-python.python) Erweiterung gut unterstützt. Der in Python enthaltene IDLE-Editor reicht aus, um loszulegen. Die Python-Module für das AWS CDK haben Typhinweise, die für ein Linting-Tool oder eine IDE, die Typvalidierung unterstützt, nützlich sind. ## Erste Schritte mit Python Um mit dem AWS CDK arbeiten zu können, müssen Sie über ein AWS Konto und Anmeldeinformationen verfügen und Node.js und das AWS CDK Toolkit installiert haben. Weitere Informationen finden Sie unter [Erste Schritte mit dem CDK](getting-started.md). AWS AWS Python-CDK-Anwendungen benötigen Python 3.9 oder höher. Falls Sie es noch nicht installiert haben, [laden Sie eine kompatible Version](https://www.python.org/downloads/) für Ihr Betriebssystem von [python.org](https://www.python.org/) herunter. Wenn Sie Linux verwenden, wurde Ihr System möglicherweise mit einer kompatiblen Version geliefert, oder Sie können es mit dem Paketmanager Ihrer Distribution installieren (`yum``apt`, usw.). Mac-Benutzer könnten an [Homebrew](https://brew.sh/) interessiert sein, einem Paketmanager im Linux-Stil für macOS. **Anmerkung** Veraltete Sprachversion von Drittanbietern: Die Sprachversion wird nur bis zu ihrem vom Anbieter oder der Community mitgeteilten EOL (End Of Life) unterstützt und kann sich mit vorheriger Ankündigung ändern. Das Python-Paketinstallationsprogramm und der Virtual Environment Manager sind ebenfalls erforderlich. `pip` `virtualenv` Windows-Installationen kompatibler Python-Versionen enthalten diese Tools. Unter Linux `pip` und `virtualenv` kann als separate Pakete in Ihrem Paketmanager bereitgestellt werden. Alternativ können Sie sie mit den folgenden Befehlen installieren: ``` python -m ensurepip --upgrade python -m pip install --upgrade pip python -m pip install --upgrade virtualenv ``` Wenn Sie auf einen Berechtigungsfehler stoßen, führen Sie die obigen Befehle mit der `--user` Markierung aus, sodass die Module in Ihrem Benutzerverzeichnis installiert werden, oder verwenden Sie `sudo` sie, um die Berechtigungen für die systemweite Installation der Module zu erhalten. **Anmerkung** Es ist üblich, dass Linux-Distributionen den Namen der ausführbaren Datei `python3` für Python 3.x verwenden und auf eine Python 2.x-Installation `python` verweisen. Einige Distributionen haben ein optionales Paket, das Sie installieren können, damit sich der `python` Befehl auf Python 3 bezieht. Andernfalls können Sie den Befehl, mit dem Ihre Anwendung ausgeführt wird, anpassen, indem Sie ihn `cdk.json` im Hauptverzeichnis des Projekts bearbeiten. **Anmerkung** Unter Windows möchten Sie vielleicht Python (und`pip`) mit der `py` ausführbaren Datei, dem [Python-Launcher für Windows](https://docs.python.org/3/using/windows.html#launcher), aufrufen. Mit dem Launcher können Sie unter anderem einfach angeben, welche installierte Version von Python Sie verwenden möchten. Wenn die Eingabe `python` in der Befehlszeile zu einer Meldung über die Installation von Python aus dem Windows Store führt, auch nach der Installation einer Windows-Version von Python, öffnen Sie den Windows-Einstellungsbereich „App-Ausführungs-Aliase verwalten“ und deaktivieren Sie die beiden App Installer-Einträge für Python. ## Erstellen eines Projekts Sie erstellen ein neues AWS CDK-Projekt, indem Sie es `cdk init` in einem leeren Verzeichnis aufrufen. Verwenden Sie die `--language` Option und geben Sie an: `python` ``` $ mkdir my-project $ cd my-project $ cdk init app --language python ``` `cdk init`verwendet den Namen des Projektordners, um verschiedene Elemente des Projekts zu benennen, einschließlich Klassen, Unterordnern und Dateien. Bindestriche im Ordnernamen werden in Unterstriche umgewandelt. Ansonsten sollte der Name jedoch der Form eines Python-Bezeichners folgen; er sollte beispielsweise nicht mit einer Zahl beginnen oder Leerzeichen enthalten. Um mit dem neuen Projekt zu arbeiten, aktivieren Sie seine virtuelle Umgebung. Dadurch können die Abhängigkeiten des Projekts lokal und nicht global im Projektordner installiert werden. ``` $ source .venv/bin/activate ``` **Anmerkung** Möglicherweise erkennen Sie dies als den Mac/Linux Befehl zur Aktivierung einer virtuellen Umgebung. Die Python-Vorlagen enthalten eine Batch-Datei, `source.bat`, die die Verwendung desselben Befehls unter Windows ermöglicht. Der traditionelle Windows-Befehl`.\venv\Scripts\activate`,, funktioniert auch. Wenn Sie Ihr AWS CDK-Projekt mit CDK Toolkit v1.70.0 oder früher initialisiert haben, befindet sich Ihre virtuelle Umgebung im Verzeichnis statt. `.env` `.venv` **Wichtig** Aktivieren Sie die virtuelle Umgebung des Projekts, wann immer Sie damit beginnen, daran zu arbeiten. Andernfalls haben Sie keinen Zugriff auf die dort installierten Module, und die von Ihnen installierten Module werden in das globale Python-Modulverzeichnis verschoben (oder führen zu einem Berechtigungsfehler). Nachdem Sie Ihre virtuelle Umgebung zum ersten Mal aktiviert haben, installieren Sie die Standardabhängigkeiten der App: ``` $ python -m pip install -r requirements.txt ``` ## Verwaltung von AWS Construct Library-Modulen Verwenden Sie das Python-Paketinstallationsprogramm`pip`,, um AWS Construct Library-Module für Ihre Apps sowie andere Pakete, die Sie benötigen, zu installieren und zu aktualisieren. `pip`installiert auch die Abhängigkeiten für diese Module automatisch. Wenn Ihr System den Befehl nicht `pip` als eigenständigen Befehl erkennt, rufen Sie ihn wie folgt `pip` als Python-Modul auf: ``` $ python -m pip ``` Die meisten AWS CDK-Konstrukte sind enthalten. `aws-cdk-lib` Experimentelle Module befinden sich in separaten Modulen mit dem Namen wie. `aws-cdk..alpha` Der Dienstname enthält ein *AWS-Präfix*. Wenn Sie sich des Namens eines Moduls nicht sicher sind, [suchen Sie bei PyPI danach](https://pypi.org/search/?q=aws-cdk). Mit dem folgenden Befehl wird beispielsweise die Bibliothek installiert. AWS CodeStar ``` $ python -m pip install aws-cdk.aws-codestar-alpha ``` Die Konstrukte einiger Dienste befinden sich in mehr als einem Namespace. Außerdem gibt es `aws-cdk.aws-route53` beispielsweise drei zusätzliche Amazon Route 53-Namespaces mit den Namen`aws-route53-targets`, und`aws-route53-patterns`. `aws-route53resolver` **Anmerkung** Die [Python-Ausgabe der CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/python/index.html) zeigt auch die Paketnamen. Die Namen, die für den Import von AWS Construct Library-Modulen in Ihren Python-Code verwendet werden, sehen wie folgt aus. ``` import aws_cdk.aws_s3 as s3 import aws_cdk.aws_lambda as lambda_ ``` Wir empfehlen die folgenden Methoden, wenn Sie AWS CDK-Klassen und AWS Construct Library-Module in Ihre Anwendungen importieren. Das Befolgen dieser Richtlinien trägt dazu bei, dass Ihr Code mit anderen AWS CDK-Anwendungen konsistent und verständlicher ist. + Im Allgemeinen sollten Sie einzelne Klassen aus der obersten `aws_cdk` Ebene importieren. ``` from aws_cdk import App, Construct ``` + Wenn Sie viele Klassen aus dem benötigen`aws_cdk`, können Sie einen Namespace-Alias von verwenden, `cdk` anstatt einzelne Klassen zu importieren. Vermeiden Sie es, beides zu tun. ``` import aws_cdk as cdk ``` + Im Allgemeinen sollten Sie AWS Construct-Bibliotheken mit kurzen Namespace-Aliasen importieren. ``` import aws_cdk.aws_s3 as s3 ``` Aktualisieren Sie nach der Installation eines Moduls die `requirements.txt` Datei Ihres Projekts, in der die Abhängigkeiten Ihres Projekts aufgeführt sind. Es ist am besten, dies manuell zu tun, anstatt es zu verwenden`pip freeze`. `pip freeze`erfasst die aktuellen Versionen aller Module, die in Ihrer virtuellen Python-Umgebung installiert sind. Dies kann nützlich sein, wenn Sie ein Projekt bündeln, das an anderer Stelle ausgeführt werden soll. Normalerweise `requirements.txt` sollten Sie jedoch nur Abhängigkeiten der obersten Ebene auflisten (Module, von denen Ihre App direkt abhängt) und nicht die Abhängigkeiten dieser Bibliotheken. Diese Strategie erleichtert die Aktualisierung Ihrer Abhängigkeiten. Sie können Änderungen vornehmen`requirements.txt`, um Upgrades zuzulassen. Ersetzen Sie einfach die `==` vorherige Versionsnummer durch, `~=` um Upgrades auf eine höhere kompatible Version zu ermöglichen, oder entfernen Sie die Versionsanforderung vollständig, um die neueste verfügbare Version des Moduls anzugeben. Wenn die `requirements.txt` Datei entsprechend bearbeitet wurde, um Upgrades zu ermöglichen, geben Sie diesen Befehl ein, um die in Ihrem Projekt installierten Module jederzeit zu aktualisieren: ``` $ pip install --upgrade -r requirements.txt ``` ## Abhängigkeiten in Python verwalten In Python spezifizieren Sie Abhängigkeiten, indem Sie sie `requirements.txt` für Anwendungen oder `setup.py` für Konstruktbibliotheken eingeben. Abhängigkeiten werden dann mit dem PIP-Tool verwaltet. PIP wird auf eine der folgenden Arten aufgerufen: ``` pip python -m pip ``` Der `python -m pip` Aufruf funktioniert auf den meisten Systemen; `pip` erfordert, dass sich die ausführbare Datei von PIP im Systempfad befindet. Wenn `pip` das nicht funktioniert, versuchen Sie, es durch zu ersetzen. `python -m pip` Der `cdk init --language python` Befehl erstellt eine virtuelle Umgebung für Ihr neues Projekt. Dadurch kann jedes Projekt seine eigenen Versionen von Abhängigkeiten und auch eine `requirements.txt` Basisdatei haben. Sie müssen diese virtuelle Umgebung `source .venv/bin/activate` jedes Mal aktivieren, indem Sie sie ausführen, wenn Sie mit der Arbeit an dem Projekt beginnen. Führen Sie unter Windows `.\venv\Scripts\activate` stattdessen den Befehl aus ### CDK-Anwendungen Im Folgenden sehen Sie ein Beispiel für eine `requirements.txt`-Datei. Da PIP nicht über eine Funktion zum Sperren von Abhängigkeiten verfügt, empfehlen wir, den Operator == zu verwenden, um exakte Versionen für alle Abhängigkeiten anzugeben, wie hier gezeigt. ``` aws-cdk-lib==2.14.0 aws-cdk.aws-appsync-alpha==2.10.0a0 ``` Durch die Installation eines Moduls mit `pip install` wird es nicht automatisch hinzugefügt. `requirements.txt` Das müssen Sie selbst tun. Wenn Sie auf eine neuere Version einer Abhängigkeit aktualisieren möchten, bearbeiten Sie deren Versionsnummer unter`requirements.txt`. Um die Abhängigkeiten Ihres Projekts nach der Erstellung oder Bearbeitung zu installieren oder zu aktualisieren`requirements.txt`, führen Sie den folgenden Befehl aus: ``` python -m pip install -r requirements.txt ``` **Tipp** Der `pip freeze` Befehl gibt die Versionen aller installierten Abhängigkeiten in einem Format aus, das in eine Textdatei geschrieben werden kann. Dies kann als Anforderungsdatei mit verwendet werden`pip install -r`. Diese Datei ist praktisch, um alle Abhängigkeiten (einschließlich transitiver Abhängigkeiten) genau den Versionen zuzuordnen, mit denen Sie getestet haben. Um Probleme bei der späteren Aktualisierung von Paketen zu vermeiden, verwenden Sie hierfür eine separate Datei, z. B. `freeze.txt` (not`requirements.txt`). Generieren Sie sie dann neu, wenn Sie die Abhängigkeiten Ihres Projekts aktualisieren. ### Konstruktbibliotheken von Drittanbietern In Bibliotheken werden Abhängigkeiten in angegeben`setup.py`, sodass transitive Abhängigkeiten automatisch heruntergeladen werden, wenn das Paket von einer Anwendung verwendet wird. Andernfalls muss jede Anwendung, die Ihr Paket verwenden möchte, Ihre Abhängigkeiten in ihre `requirements.txt` Dateien kopieren. Ein Beispiel `setup.py` wird hier gezeigt. ``` from setuptools import setup setup( name='my-package', version='0.0.1', install_requires=[ 'aws-cdk-lib==2.14.0', ], ... ) ``` Um an dem Paket für die Entwicklung zu arbeiten, erstellen oder aktivieren Sie eine virtuelle Umgebung und führen Sie dann den folgenden Befehl aus. ``` python -m pip install -e . ``` Obwohl PIP automatisch transitive Abhängigkeiten installiert, kann von jedem Paket nur eine Kopie installiert werden. Die Version, die im Abhängigkeitsbaum am höchsten angegeben ist, wird ausgewählt; Anwendungen haben immer das letzte Wort darüber, welche Version von Paketen installiert wird. ## AWS CDK-Idiome in Python ### Sprachkonflikte In Python `lambda` ist dies ein Sprachschlüsselwort, sodass Sie es nicht als Namen für das AWS Lambda-Konstruktbibliotheksmodul oder für Lambda-Funktionen verwenden können. Die Python-Konvention für solche Konflikte besteht darin, im Variablennamen einen abschließenden Unterstrich wie in `lambda_` zu verwenden. Konventionell wird das zweite Argument für AWS CDK-Konstrukte benannt. `id` Wenn Sie Ihre eigenen Stapel und Konstrukte schreiben, `id` „überschattet“ der Aufruf eines Parameters die eingebaute Python-Funktion`id()`, die den eindeutigen Bezeichner eines Objekts zurückgibt. Diese Funktion wird nicht sehr oft verwendet, aber wenn Sie sie zufällig in Ihrem Konstrukt benötigen sollten, benennen Sie das Argument beispielsweise um. `construct_id` ### Argumente und Eigenschaften Alle AWS Construct-Library-Klassen werden mit drei Argumenten instanziiert: dem *Bereich*, in dem das Konstrukt definiert wird (sein übergeordnetes Objekt im Konstruktbaum), einer *ID* und *Requisiten*, einem Bündel von key/value Paaren, das das Konstrukt verwendet, um die von ihm erstellten Ressourcen zu konfigurieren. Andere Klassen und Methoden verwenden ebenfalls das Muster „Bündel von Attributen“ für Argumente. *scope* und *id* sollten immer als Positionsargumente und nicht als Schlüsselwortargumente übergeben werden, da sich ihre Namen ändern, wenn das Konstrukt eine Eigenschaft namens *scope* oder *id* akzeptiert. In Python werden Requisiten als Schlüsselwortargumente ausgedrückt. Wenn ein Argument verschachtelte Datenstrukturen enthält, werden diese mithilfe einer Klasse ausgedrückt, die bei der Instanziierung ihre eigenen Schlüsselwortargumente verwendet. Das gleiche Muster wird auf andere Methodenaufrufen angewendet, die ein strukturiertes Argument verwenden. In der `add_lifecycle_rule` Methode eines Amazon S3 S3-Buckets ist die `transitions` Eigenschaft beispielsweise eine Liste von `Transition` Instances. ``` bucket.add_lifecycle_rule( transitions=[ Transition( storage_class=StorageClass.GLACIER, transition_after=Duration.days(10) ) ] ) ``` Wenn Sie eine Klasse erweitern oder eine Methode überschreiben, möchten Sie möglicherweise zusätzliche Argumente für Ihre eigenen Zwecke akzeptieren, die von der übergeordneten Klasse nicht verstanden werden. In diesem Fall sollten Sie die Argumente, die Ihnen egal sind, mit dem \$1\$1kwargs-Idiom akzeptieren und Argumente verwenden, die nur Stichwörter enthalten, um die Argumente zu akzeptieren, an denen Sie interessiert sind. Wenn Sie den Konstruktor des übergeordneten Elements oder die überschriebene Methode aufrufen, übergeben Sie nur die Argumente, die das Objekt erwartet (oft nur\$1\$1kwargs). Die Übergabe von Argumenten, die die übergeordnete Klasse oder Methode nicht erwartet, führt zu einem Fehler. ``` class MyConstruct(Construct): def __init__(self, id, *, MyProperty=42, **kwargs): super().__init__(self, id, **kwargs) # ... ``` Eine future Version des AWS CDK könnte zufällig eine neue Immobilie mit einem Namen hinzufügen, den Sie für Ihre eigene Immobilie verwendet haben. Dies wird zwar keine technischen Probleme für Benutzer Ihres Konstrukts oder Ihrer Methode verursachen (da Ihre Eigenschaft nicht „in der Kette“ weitergereicht wird, verwendet die übergeordnete Klasse oder überschriebene Methode einfach einen Standardwert), aber es kann zu Verwirrung führen. Sie können dieses potenzielle Problem vermeiden, indem Sie Ihre Eigenschaften so benennen, dass sie eindeutig zu Ihrem Konstrukt gehören. Wenn es viele neue Eigenschaften gibt, bündeln Sie sie in einer Klasse mit dem entsprechenden Namen und übergeben Sie sie als einzelnes Schlüsselwortargument. ### Fehlende Werte Das AWS CDK wird verwendet, `None` um fehlende oder undefinierte Werte darzustellen. Wenn Sie mit\$1\$1kwargs arbeiten, verwenden Sie die `get()` Methode des Wörterbuchs, um einen Standardwert anzugeben, falls eine Eigenschaft nicht angegeben wird. Vermeiden Sie die Verwendung`kwargs[…​]`, da dies auf fehlende Werte zurückzuführen `KeyError` ist. ``` encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing ``` Einige AWS CDK-Methoden (z. B. `tryGetContext()` zum Abrufen eines Laufzeitkontextwerts) geben möglicherweise einen Wert zurück`None`, den Sie explizit überprüfen müssen. ### Verwenden von Schnittstellen Python hat keine Schnittstellenfunktion wie einige andere Sprachen, obwohl es [abstrakte Basisklassen](https://docs.python.org/3/library/abc.html) hat, die ähnlich sind. (Wenn Sie mit Schnittstellen nicht vertraut sind, hat Wikipedia [eine gute Einführung](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages).) TypeScript, die Sprache, in der das AWS CDK implementiert ist, stellt Schnittstellen bereit, und Konstrukte und andere AWS CDK-Objekte erfordern oft ein Objekt, das sich an eine bestimmte Schnittstelle hält, anstatt es von einer bestimmten Klasse zu erben. [Das AWS CDK bietet also eine eigene Schnittstellenfunktion als Teil der JSII-Schicht.](https://github.com/aws/jsii) Um anzugeben, dass eine Klasse eine bestimmte Schnittstelle implementiert, können Sie den Decorator verwenden: `@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) ``` ### Geben Sie Fallstricke ein Python verwendet dynamische Typisierung, bei der sich alle Variablen auf einen Wert beliebigen Typs beziehen können. Parameter und Rückgabewerte können mit Typen annotiert werden, aber das sind „Hinweise“ und werden nicht erzwungen. Das bedeutet, dass es in Python einfach ist, den falschen Wertetyp an ein AWS CDK-Konstrukt zu übergeben. Anstatt beim Build einen Typfehler zu erhalten, wie Sie es bei einer statisch typisierten Sprache tun würden, erhalten Sie möglicherweise einen Laufzeitfehler, wenn die JSII-Schicht (die zwischen Python und dem TypeScript Kern des AWS CDK übersetzt) den unerwarteten Typ nicht verarbeiten kann. Unserer Erfahrung nach fallen die Typfehler, die Python-Programmierer machen, in diese Kategorien. + Übergeben eines einzelnen Werts, wenn ein Konstrukt einen Container erwartet (Python-Liste oder Wörterbuch) oder umgekehrt. + Übergabe eines Werts eines Typs, der mit einem Layer-1-Konstrukt (`CfnXxxxxx`) verknüpft ist, an ein L2- oder L3-Konstrukt oder umgekehrt. ## Vermeidung von Typfehlern Die AWS-CDK-Python-Module enthalten Typanmerkungen, sodass Sie Tools verwenden können, die sie unterstützen, um Typfehler vor der Bereitstellung zu erkennen. ### IDE-Integration (empfohlen) Visual Studio Code with Pylance bietet eine Typüberprüfung in Echtzeit, während Sie Code schreiben: 1. Installieren Sie die [Pylance-Erweiterung](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) 1. Konfigurieren Sie das strikte Einchecken von Typen: `.vscode/settings.json` ``` { "python.languageServer": "Pylance", "python.analysis.typeCheckingMode": "strict" } ``` 1. Tippfehler werden jetzt sofort mit roten Schnörkeln und detaillierten Fehlermeldungen angezeigt [PyCharm](https://www.jetbrains.com/pycharm/)bietet auch eine integrierte Typprüfung mit ähnlichen Funktionen. ### Typüberprüfung in der Befehlszeile Verwenden Sie für CI/CD Pipelines oder die Validierung vor dem Commit einen der folgenden Typprüfer: **MyPy (Python-basiert):** ``` pip install mypy mypy app.py ``` **Pyright (schneller, JavaScript basiert, dieselbe Engine wie Pylance):** ``` npm install -g pyright pyright app.py ``` ### Empfohlener Workflow 1. Während der Entwicklung: Verwenden Sie Pyright oder Pylance für sofortiges Feedback 1. Vor dem Commit: Führen Sie aus oder `mypy app.py` `pyright app.py` 1. In CI/CD: Machen Sie die Typprüfung vor der Bereitstellung zu einem erforderlichen Schritt