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 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. Beim Arbeiten mit AWS CDK in Python werden vertraute Tools verwendet, darunter die Python-Standardimplementierung (CPython), virtuelle Umgebungen mit virtualenvund das Python-Paketinstallationsprogramm pip. Die Module, aus denen die AWS Construct Library besteht, werden über pypi.org verteilt. Die Python-Version von verwendet AWS CDK sogar Kennungen im Python-Stil (z. B. snake_case Methodennamen).

Sie können jeden Editor oder jede IDE verwenden. Viele AWS CDK Entwickler verwenden Visual Studio Code (oder sein Open-Source-Äquivalent VSCodium ), das Python über eine offizielle Erweiterung gut unterstützt. Der in Python enthaltene IDLE-Editor reicht für den Einstieg aus. Die Python-Module für die AWS CDK verfügen über Typhinweise, die für ein Untersuchungstool oder eine IDE nützlich sind, die Typvalidierung unterstützt.

Erste Schritte mit Python

Um mit der zu arbeiten AWS CDK, müssen Sie über ein - AWS Konto und Anmeldeinformationen verfügen und Node.js und das AWS CDK Toolkit installiert haben. Siehe Erste Schritte mit der AWS CDK.

Python- AWS CDK Anwendungen erfordern Python 3.6 oder höher. Wenn Sie es noch nicht installiert haben, laden Sie eine kompatible Version für Ihr Betriebssystem unter herunter. python.org Wenn Sie Linux ausführen, hat Ihr System möglicherweise eine kompatible Version enthalten oder Sie können es mit dem Paketmanager Ihres Distro (yum, aptusw.) installieren. Mac-Benutzer könnten an Homebrew interessiert sein, einem Paketmanager im Linux-Stil für macOS .

Das Python-Paketinstallationsprogramm, pipund der virtuelle Umgebungsmanager, virtualenv, sind ebenfalls erforderlich. Windows-Installationen kompatibler Python-Versionen enthalten diese Tools. Unter Linux virtualenv können pip und 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 dem ---userFlag aus, damit die Module in Ihrem Benutzerverzeichnis installiert sind, oder verwenden Sie , sudo um die Berechtigungen zur systemweiten Installation der Module zu erhalten.

Erstellen eines Projekts

Sie erstellen ein neues AWS CDK Projekt, indem Sie cdk init in einem leeren Verzeichnis aufrufen. Verwenden Sie die --language Option und geben Sie anpython:

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, Unterordner und Dateien. Bindestriche im Ordnernamen werden in Unterstriche umgewandelt. Der Name sollte jedoch ansonsten der Form einer Python-Kennung 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 im Projektordner installiert werden und müssen nicht global installiert werden.

source .venv/bin/activate

Nachdem Sie Ihre virtuelle Umgebung zum ersten Mal aktiviert haben, installieren Sie die Standardabhängigkeiten der App:

python -m pip install -r requirements.txt

Verwalten von Modulen AWS der Construct Library

Verwenden Sie das Python-Paketinstallationsprogramm, pip, um AWS Construct Library-Module zur Verwendung durch Ihre Apps sowie andere benötigte Pakete zu installieren und zu aktualisieren. installiert pip auch die Abhängigkeiten für diese Module automatisch. Wenn Ihr System nicht pip als eigenständigen Befehl erkennt, rufen Sie wie folgt pip als Python-Modul auf:

python -m pip PIP-COMMAND

Die meisten AWS CDK Konstrukte befinden sich in aws-cdk-lib. Experimentelle Module befinden sich in separaten Modulen mit dem Namen aws-cdk.SERVICE-NAME.alpha. Der Servicename enthält ein AWS-Präfix. Wenn Sie sich über den Namen eines Moduls nicht sicher sind, suchen Sie unter PyPI nach diesem. Mit dem folgenden Befehl wird beispielsweise die AWS CodeStar Bibliothek installiert.

python -m pip install aws-cdk.aws-codestar-alpha

Die Konstrukte einiger Services befinden sich in mehr als einem Namespace. Neben gibt aws-cdk.aws-route53es beispielsweise drei zusätzliche Amazon Route 53-Namespaces mit dem Namen aws-route53-targetsaws-route53-patterns, und aws-route53resolver.

Die Namen, die zum Importieren von Modulen der AWS Construct Library 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 AWS CDK Sie Klassen und Module der AWS Construct Library in Ihre Anwendungen importieren. Die Einhaltung dieser Richtlinien trägt dazu bei, dass Ihr Code mit anderen AWS CDK Anwendungen konsistent und leichter verständlich ist.

Aktualisieren Sie nach der Installation eines Moduls die -requirements.txtDatei Ihres Projekts, in der die Abhängigkeiten Ihres Projekts aufgeführt sind. Es empfiehlt sich, dies manuell zu tun, anstatt zu verwendenpip freeze. pip freeze erfasst die aktuellen Versionen aller Module, die in Ihrer virtuellen Python-Umgebung installiert sind. Dies kann nützlich sein, wenn ein Projekt gebündelt wird, um es an anderer Stelle auszuführen.

Normalerweise requirements.txt sollte Ihr jedoch nur Abhängigkeiten der obersten Ebene (Module, von denen Ihre App direkt abhängt) und nicht die Abhängigkeiten dieser Bibliotheken auflisten. Diese Strategie macht die Aktualisierung Ihrer Abhängigkeiten einfacher.

Sie können bearbeiten, requirements.txt um Upgrades zuzulassen. Ersetzen Sie einfach die == vorangehende Versionsnummer durch ~=, um Upgrades auf eine höhere kompatible Version zuzulassen, oder entfernen Sie die Versionsanforderung vollständig, um die neueste verfügbare Version des Moduls anzugeben.

Wenn entsprechend requirements.txt bearbeitet wurde, um Upgrades zuzulassen, geben Sie diesen Befehl aus, um die installierten Module Ihres Projekts jederzeit zu aktualisieren:

pip install --upgrade -r requirements.txt

Verwalten von Abhängigkeiten in Python

In Python geben Sie Abhängigkeiten an, indem Sie sie requirements.txt für Anwendungen oder setup.py für Konstruktbibliotheken einfügen. Abhängigkeiten werden dann mit dem PIP-Tool verwaltet. PIP wird auf eine der folgenden Arten aufgerufen:

pip command options
python -m pip command options

Der python -m pip Aufruf funktioniert auf den meisten Systemen; pip erfordert, dass sich die ausführbare PIP-Datei auf dem Systempfad befindet. Wenn pip nicht funktioniert, versuchen Sie, es durch zu ersetzenpython -m pip.

Der cdk init --language python Befehl erstellt eine virtuelle Umgebung für Ihr neues Projekt. Auf diese Weise kann jedes Projekt seine eigenen Versionen von Abhängigkeiten sowie eine requirements.txt Basisdatei haben. Sie müssen diese virtuelle Umgebung aktivieren, indem Sie source .venv/bin/activate jedes Mal ausführen, wenn Sie mit dem Projekt beginnen.

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 zu hinzugefügtrequirements.txt. Sie müssen dies selbst tun. Wenn Sie auf eine neuere Version einer Abhängigkeit aktualisieren möchten, bearbeiten Sie ihre Versionsnummer in requirements.txt.

Führen Sie die folgenden Schritte ausrequirements.txt, um die Abhängigkeiten Ihres Projekts nach dem Erstellen oder Bearbeiten von zu installieren oder zu aktualisieren:

python -m pip install -r requirements.txt

Bibliotheken für Konstrukte von Drittanbietern

In Bibliotheken werden Abhängigkeiten in angegebensetup.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 kopierenrequirements.txt. 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 nur eine Kopie eines Pakets installiert werden. Die Version, die im Abhängigkeitsbaum am höchsten angegeben ist, wird ausgewählt. Anwendungen haben immer das letzte Wort in der installierten Version von Paketen.

AWS CDK idioms in Python

Sprachkonflikte

In Python lambda ist ein Sprachschlüsselwort, daher können Sie es nicht als Namen für das AWS Lambda Konstruktbibliotheksmodul oder die Lambda-Funktionen verwenden. Die Python-Konvention für solche Konflikte besteht darin, im Variablennamen einen Unterstrich am Ende zu verwendenlambda_, wie in .

Konventionell heißt das zweite Argument für AWS CDK Konstrukte id. Beim Schreiben eigener Stacks und Konstrukte id „schattet“ der integrierten Python-Funktion id(), die die eindeutige Kennung eines Objekts zurückgibt. Diese Funktion wird nicht sehr häufig verwendet, aber wenn Sie sie in Ihrem Konstrukt benötigen sollten, benennen Sie das Argument um, z. B. construct_id.

Argumente und Eigenschaften

Alle AWS Construct Library-Klassen werden mit drei Argumenten instanziiert: dem Umfang, in dem das Konstrukt definiert wird (sein übergeordnetes Element in der Konstruktstruktur), einer ID und props, einem Paket von Schlüssel-Wert-Paaren, die das Konstrukt zur Konfiguration der erstellten Ressourcen verwendet. Andere Klassen und Methoden verwenden auch das „Bundle of Attribute“-Muster für Argumente.

scope und id sollten immer als Positionsargumente übergeben werden, nicht als Schlüsselwortargumente, da sich ihre Namen ändern, wenn das Konstrukt eine Eigenschaft mit dem Namen scope oder id akzeptiert.

In Python werden Eigenschaften als Schlüsselwortargumente ausgedrückt. Wenn ein Argument verschachtelte Datenstrukturen enthält, werden diese mithilfe einer Klasse ausgedrückt, die bei der Instanziierung eigene Schlüsselwortargumente verwendet. Das gleiche Muster wird auf andere Methodenaufrufe angewendet, die ein strukturiertes Argument verwenden.

In der -add_lifecycle_ruleMethode eines Amazon S3-Buckets ist die -transitionsEigenschaft 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, sollten Sie zusätzliche Argumente für Ihre eigenen Zwecke akzeptieren, die von der übergeordneten Klasse nicht verstanden werden. In diesem Fall sollten Sie die Argumente akzeptieren, die Ihnen nicht wichtig sind, das **kwargs idiom zu verwenden, und Nur-Schlüsselwort-Argumente verwenden, um die Argumente zu akzeptieren, an denen Sie interessiert sind. Übergeben Sie beim Aufrufen des Konstruktors des übergeordneten Konstruktors oder der überschriebenen Methode nur die erwarteten Argumente (oft nur **kwargs). Das Übergeben 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 zukünftige Version von AWS CDK könnte zufällig eine neue Eigenschaft mit einem Namen hinzufügen, den Sie für Ihre eigene Eigenschaft verwendet haben. Dies führt nicht zu technischen Problemen für Benutzer Ihres Konstrukts oder Ihrer Methode (da Ihre Eigenschaft nicht „über die Kette“ übergeben wird, verwendet die übergeordnete Klasse oder überschriebene Methode einfach einen Standardwert), kann aber zu Verwirrung führen. Sie können dieses potenzielle Problem vermeiden, indem Sie Ihre Eigenschaften benennen, damit sie eindeutig zu Ihrem Konstrukt gehören. Wenn es viele neue Eigenschaften gibt, bündeln Sie sie in einer entsprechend benannten Klasse und übergeben Sie sie als ein einzelnes Schlüsselwortargument.

Fehlende Werte

Die AWS CDK verwendet None, um fehlende oder undefinierte Werte darzustellen. Wenn Sie mit arbeiten**kwargs, verwenden Sie die get() Methode des Wörterbuchs, um einen Standardwert bereitzustellen, wenn keine Eigenschaft angegeben wird. Vermeiden Sie die Verwendung von kwargs[...], da dies KeyError zu fehlenden Werten führt.

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 zurückNone, was Sie explizit überprüfen müssen.

Verwenden von Schnittstellen

Python verfügt nicht wie einige andere Sprachen über ein Schnittstellenfeature, obwohl es über abstrakte Basisklassen verfügt, die ähnlich sind. (Wenn Sie mit Schnittstellen nicht vertraut sind, verfügt Wikipedia über eine gute Einführung.) Die Sprache TypeScript, in der implementiert AWS CDK ist, stellt Schnittstellen bereit und Konstrukte und andere AWS CDK Objekte erfordern oft ein Objekt, das einer bestimmten Schnittstelle entspricht, anstatt von einer bestimmten Klasse zu erben. Daher AWS CDK bietet das eine eigene Schnittstellenfunktion als Teil der JSII-Ebene.

Um anzugeben, dass eine Klasse eine bestimmte Schnittstelle implementiert, können Sie den @jsii.implements Decorator verwenden:

from aws_cdk import IAspect, IConstruct
import jsii

@jsii.implements(IAspect)
class MyAspect():
    def visit(self, node: IConstruct) -> None:
        print("Visited", node.node.path)

Fallstricke vom Typ

Python verwendet dynamische Typisierung, wobei alle Variablen auf einen Wert eines beliebigen Typs verweisen können. Parameter und Rückgabewerte können mit -Typen kommentiert werden, aber diese sind „Hinweise“ und werden nicht erzwungen. Das bedeutet, dass es in Python einfach ist, den falschen Werttyp an ein AWS CDK Konstrukt zu übergeben. Anstatt während des Builds einen Typfehler zu erhalten, wie Sie es bei einer statisch typisierten Sprache tun würden, erhalten Sie stattdessen möglicherweise einen Laufzeitfehler, wenn die JSII-Ebene (die zwischen Python und dem TypeScript Kern AWS CDK des s übersetzt wird) den unerwarteten Typ nicht bewältigen kann.

Unserer Erfahrung nach fallen die Typfehler, die Python-Programmierer in der Regel in diese Kategorien fallen.

Die AWS CDK Python-Module enthalten Typanmerkungen, sodass Sie Tools verwenden können, die sie unterstützen, um bei -Typen zu helfen. Wenn Sie keine IDE verwenden, die diese unterstützt, z. B. PyCharm, sollten Sie die MyPy Typvalidierung als Schritt in Ihrem Build-Prozess aufrufen. Es gibt auch Laufzeit-Typprüfungen, die Fehlermeldungen bei typbezogenen Fehlern verbessern können.

Synthetisieren und Bereitstellen

Die in Ihrer AWS CDK App definierten Stacks können mithilfe der folgenden Befehle einzeln oder zusammen synthetisiert und bereitgestellt werden. Im Allgemeinen sollten Sie sich im Hauptverzeichnis Ihres Projekts befinden, wenn Sie sie ausgeben.

Sie können die Namen mehrerer Stacks angeben, die in einem einzigen Befehl synthetisiert oder bereitgestellt werden sollen. Wenn Ihre App nur einen Stack definiert, müssen Sie ihn nicht angeben.

cdk synth                 # app defines single stack
cdk deploy Happy Grumpy   # app defines two or more stacks; two are deployed

Sie können auch die Platzhalter * (beliebige Anzahl von Zeichen) und ? (beliebiges einzelnes Zeichen) verwenden, um Stacks nach Mustern zu identifizieren. Wenn Sie Platzhalter verwenden, schließen Sie das Muster in Anführungszeichen ein. Andernfalls versucht die Shell möglicherweise, sie auf die Namen der Dateien im aktuellen Verzeichnis zu erweitern, bevor sie an das AWS CDK Toolkit übergeben werden.

cdk synth "Stack?"    # Stack1, StackA, etc.
cdk deploy "*Stack"   # PipeStack, LambdaStack, etc.

Eine vollständige Dokumentation des cdk Befehls finden Sie unter AWS CDK Toolkit (cdkBefehl).