Questa è la guida per sviluppatori AWS CDK v2. La versione precedente della CDK versione 1 è entrata in manutenzione il 1° giugno 2022 e ha terminato il supporto il 1° giugno 2023.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Lavorare con il AWS CDK in Python

Python è un linguaggio client completamente supportato per AWS Cloud Development Kit (AWS CDK) ed è considerato stabile. Lavorare con Python utilizza strumenti familiari, tra cui l'implementazione standard di Python (CPython), ambienti virtuali con virtualenv e il programma di installazione del pacchetto Python. AWS CDK pip I moduli che compongono la AWS Construct Library sono distribuiti tramite pypi.org. La versione Python di AWS CDK even utilizza identificatori in stile Python (ad esempio, i nomi dei metodi). snake_case

Puoi usare qualsiasi editor o. IDE Molti AWS CDK sviluppatori usano Visual Studio Code (o il suo equivalente open source VSCodium), che supporta bene Python tramite un'estensione ufficiale. L'IDLEeditor incluso in Python sarà sufficiente per iniziare. I moduli Python per la AWS CDK hanno suggerimenti di tipo, che sono utili per uno strumento di linting o che supporta la convalida dei tipi. IDE

Inizia a usare Python

Per utilizzare AWS CDK, è necessario disporre di un AWS account e delle credenziali e aver installato Node.js e il Toolkit. AWS CDK Per informazioni, consulta Iniziare con AWS CDK.

AWS CDK Le applicazioni Python richiedono Python 3.6 o successivo. Se non lo hai già installato, scarica una versione compatibile per il tuo sistema operativo su python.org. Se usi Linux, il tuo sistema potrebbe avere una versione compatibile, oppure puoi installarlo usando il gestore di pacchetti della tua distribuzione (yumapt, ecc.). Gli utenti Mac potrebbero essere interessati a Homebrew, un gestore di pacchetti in stile Linux per macOS.

Sono richiesti anche il programma di installazione del pacchetto Python e il gestore dell'ambiente virtuale. pip virtualenv Le installazioni Windows di versioni Python compatibili includono questi strumenti. Su Linux, pip e virtualenv può essere fornito come pacchetti separati nel gestore di pacchetti. In alternativa, puoi installarli con i seguenti comandi:

python -m ensurepip --upgrade
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv

Se riscontrate un errore di autorizzazione, eseguite i comandi precedenti con il --user flag in modo che i moduli siano installati nella vostra directory utente, oppure usateli sudo per ottenere le autorizzazioni per installare i moduli a livello di sistema.

Creare un progetto

È possibile creare un nuovo AWS CDK progetto richiamandolo in una directory vuota. cdk init Utilizzate l'--languageopzione e specificatepython:

mkdir my-project
cd my-project
cdk init app --language python

cdk initutilizza il nome della cartella del progetto per denominare vari elementi del progetto, tra cui classi, sottocartelle e file. I trattini nel nome della cartella vengono convertiti in caratteri di sottolineatura. Tuttavia, il nome dovrebbe altrimenti seguire la forma di un identificatore Python; ad esempio, non dovrebbe iniziare con un numero o contenere spazi.

Per lavorare con il nuovo progetto, attivare il suo ambiente virtuale. Ciò consente di installare le dipendenze del progetto localmente nella cartella del progetto, anziché globalmente.

source .venv/bin/activate

Dopo aver attivato l'ambiente virtuale per la prima volta, installa le dipendenze standard dell'app:

python -m pip install -r requirements.txt

Gestione dei moduli AWS Construct Library

Usa il programma di installazione del pacchetto Python per installare e aggiornare i moduli di AWS Construct Library da utilizzare con le tue app e con gli altri pacchetti di cui hai bisogno. pip pipinstalla inoltre automaticamente le dipendenze per tali moduli. Se il tuo sistema non riconosce pip come comando autonomo, invoca pip come modulo Python, in questo modo:

python -m pip PIP-COMMAND

La maggior parte dei AWS CDK costrutti sono disponibili. aws-cdk-lib I moduli sperimentali si trovano in moduli separati denominati comeaws-cdk.SERVICE-NAME.alpha. Il nome del servizio include un prefisso aws. Se non sei sicuro del nome di un modulo, cercalo in PyPI. Ad esempio, il comando seguente installa la libreria. AWS CodeStar

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

I costrutti di alcuni servizi si trovano in più di un namespace. Ad esempioaws-cdk.aws-route53, ci sono inoltre tre namespace Amazon Route 53 aggiuntiviaws-route53-targets, aws-route53-patterns denominati e. aws-route53resolver

I nomi usati per importare i moduli AWS Construct Library nel codice Python sono i seguenti.

import aws_cdk.aws_s3 as s3
import aws_cdk.aws_lambda as lambda_

Consigliamo le seguenti pratiche per importare AWS CDK classi e moduli AWS Construct Library nelle applicazioni. Seguire queste linee guida contribuirà a rendere il codice coerente con altre AWS CDK applicazioni e più facile da comprendere.

Dopo aver installato un modulo, aggiorna il requirements.txt file del progetto, che elenca le dipendenze del progetto. È meglio farlo manualmente anziché utilizzarepip freeze. pip freezeacquisisce le versioni correnti di tutti i moduli installati nell'ambiente virtuale Python, il che può essere utile quando si raggruppa un progetto da eseguire altrove.

Di solito, tuttavia, è requirements.txt necessario elencare solo le dipendenze di primo livello (moduli da cui dipende direttamente l'app) e non le dipendenze di tali librerie. Questa strategia semplifica l'aggiornamento delle dipendenze.

È possibile modificare requirements.txt per consentire gli aggiornamenti; è sufficiente sostituire il numero di versione == precedente con ~= per consentire l'aggiornamento a una versione compatibile superiore o rimuovere completamente il requisito di versione per specificare l'ultima versione disponibile del modulo.

Se requirements.txt modificate in modo appropriato per consentire gli aggiornamenti, eseguite questo comando per aggiornare i moduli installati del progetto in qualsiasi momento:

pip install --upgrade -r requirements.txt

Gestione delle dipendenze in Python

In Python, si specificano le dipendenze inserendole nelle applicazioni o setup.py nelle requirements.txt librerie di costruzione. Le dipendenze vengono quindi gestite con lo strumento. PIP PIPviene richiamato in uno dei seguenti modi:

pip command options
python -m pip command options

L'python -m pipinvocazione funziona sulla maggior parte dei sistemi; pip richiede che PIP sia eseguibile nel percorso di sistema. Se pip non funziona, prova a sostituirlo con. python -m pip

Il cdk init --language python comando crea un ambiente virtuale per il nuovo progetto. Ciò consente a ogni progetto di avere le proprie versioni di dipendenze e anche un requirements.txt file di base. È necessario attivare questo ambiente virtuale eseguendolo source .venv/bin/activate ogni volta che si inizia a lavorare con il progetto. Su Windows, esegui .\venv\Scripts\activate invece

CDKapplicazioni

Di seguito è riportato un esempio del file requirements.txt. Poiché PIP non dispone di una funzione di blocco delle dipendenze, si consiglia di utilizzare l'operatore == per specificare le versioni esatte per tutte le dipendenze, come illustrato di seguito.

aws-cdk-lib==2.14.0
aws-cdk.aws-appsync-alpha==2.10.0a0

L'installazione di un modulo con pip install non lo aggiunge automaticamente a. requirements.txt Devi farlo tu stesso. Se desideri eseguire l'aggiornamento a una versione successiva di una dipendenza, modificane il numero di versione inrequirements.txt.

Per installare o aggiornare le dipendenze del progetto dopo la creazione o la modificarequirements.txt, esegui quanto segue:

python -m pip install -r requirements.txt

Librerie di costruzioni di terze parti

Nelle librerie, le dipendenze sono specificate insetup.py, in modo che le dipendenze transitive vengano scaricate automaticamente quando il pacchetto viene utilizzato da un'applicazione. Altrimenti, ogni applicazione che desidera utilizzare il pacchetto deve copiare le dipendenze al suo interno. requirements.txt Un esempio setup.py è mostrato qui.

from setuptools import setup

setup(
  name='my-package',
  version='0.0.1',
  install_requires=[
    'aws-cdk-lib==2.14.0',
  ], 
  ...
)

Per lavorare sul pacchetto per lo sviluppo, crea o attiva un ambiente virtuale, quindi esegui il seguente comando.

python -m pip install -e .

Sebbene installi PIP automaticamente le dipendenze transitive, può esserci una sola copia installata di ogni pacchetto. Viene selezionata la versione specificata più in alto nell'albero delle dipendenze; le applicazioni hanno sempre l'ultima parola sulla versione dei pacchetti da installare.

AWS CDK idiomi in Python

Conflitti linguistici

In Python, lambda è una parola chiave del linguaggio, quindi non è possibile utilizzarla come nome per il modulo della libreria di AWS Lambda costruzioni o le funzioni Lambda. La convenzione di Python per tali conflitti consiste nell'utilizzare un carattere di sottolineatura finale, come inlambda_, nel nome della variabile.

Per convenzione, il secondo argomento dei AWS CDK costrutti viene denominato. id Quando scrivi i tuoi stack e i tuoi costrutti, chiamando un parametro id «shadows» la funzione incorporata in Pythonid(), che restituisce l'identificatore univoco di un oggetto. Questa funzione non viene usata molto spesso, ma se ti capita di averne bisogno nel tuo costrutto, rinomina l'argomento, ad esempio. construct_id

Argomenti e proprietà

Tutte le classi di AWS Construct Library vengono istanziate utilizzando tre argomenti: l'ambito in cui viene definito il costrutto (l'elemento principale nell'albero di costruzione), un id e props, un insieme di coppie chiave/valore che il costrutto utilizza per configurare le risorse che crea. Anche altre classi e metodi utilizzano il modello «bundle of attributes» per gli argomenti.

scope e id devono essere sempre passati come argomenti posizionali, non come argomenti di parole chiave, perché i loro nomi cambiano se il costrutto accetta una proprietà denominata scope o id.

In Python, gli oggetti di scena sono espressi come argomenti di parole chiave. Se un argomento contiene strutture di dati annidate, queste vengono espresse utilizzando una classe che utilizza i propri argomenti di parole chiave al momento dell'istanziazione. Lo stesso schema viene applicato ad altre chiamate di metodo che accettano un argomento strutturato.

Ad esempio, nel add_lifecycle_rule metodo di un bucket Amazon S3, la transitions proprietà è un elenco di istanze. Transition

bucket.add_lifecycle_rule(
  transitions=[
    Transition(
      storage_class=StorageClass.GLACIER,
      transition_after=Duration.days(10)
    )
  ]
)

Quando estendi una classe o sovrascrivi un metodo, potresti voler accettare argomenti aggiuntivi per i tuoi scopi che non sono compresi dalla classe madre. In questo caso dovreste accettare gli argomenti che non vi interessano usando l'**kwargsidioma e usare argomenti basati solo su parole chiave per accettare gli argomenti che vi interessano. Quando chiamate il costruttore del genitore o il metodo sovrascritto, passate solo gli argomenti che si aspetta (spesso solo). **kwargs Il passaggio di argomenti che la classe o il metodo principale non si aspetta genera un errore.

class MyConstruct(Construct):
    def __init__(self, id, *, MyProperty=42, **kwargs):
        super().__init__(self, id, **kwargs)
        # ...

Le future versioni di AWS CDK potrebbero aggiungere casualmente una nuova proprietà con un nome usato per la propria proprietà. Ciò non causerà alcun problema tecnico agli utenti del costrutto o del metodo (poiché la proprietà non viene passata «all'inizio della catena», la classe principale o il metodo sovrascritto utilizzeranno semplicemente un valore predefinito) ma potrebbe causare confusione. Potete evitare questo potenziale problema denominando le proprietà in modo che appartengano chiaramente al vostro costrutto. Se sono presenti molte nuove proprietà, raggruppatele in una classe dal nome appropriato e passatela come argomento di una singola parola chiave.

Valori mancanti

Gli AWS CDK usi None per rappresentare valori mancanti o non definiti. Quando si lavora con**kwargs, utilizzate il get() metodo del dizionario per fornire un valore predefinito se non viene fornita una proprietà. Evitate di utilizzarlokwargs[...], poiché ciò genera KeyError valori mancanti.

encrypted = kwargs.get("encrypted")         # None if no property "encrypted" exists
encrypted = kwargs.get("encrypted", False)  # specify default of False if property is missing

È possibile che vengano restituiti alcuni AWS CDK metodi (tryGetContext()ad esempio per ottenere un valore di contesto di runtime)None, che dovrete verificare esplicitamente.

Utilizzo delle interfacce

Python non ha una funzionalità di interfaccia come altri linguaggi, sebbene abbia classi base astratte, che sono simili. (Se non hai familiarità con le interfacce, Wikipedia ha una buona introduzione.) TypeScript, il linguaggio in cui AWS CDK è implementato, fornisce interfacce e i costrutti e altri AWS CDK oggetti spesso richiedono un oggetto che aderisca a una particolare interfaccia, anziché ereditare da una particolare classe. Quindi AWS CDK fornisce la propria funzionalità di interfaccia come parte del livello. JSII

Per indicare che una classe implementa una particolare interfaccia, puoi usare il @jsii.implements decoratore:

from aws_cdk import IAspect, IConstruct
import jsii

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

Digita le insidie

Python utilizza la tipizzazione dinamica, in cui tutte le variabili possono fare riferimento a un valore di qualsiasi tipo. I parametri e i valori restituiti possono essere annotati con tipi, ma questi sono «suggerimenti» e non vengono applicati. Ciò significa che in Python è facile passare il tipo di valore errato a un AWS CDK costrutto. Invece di ricevere un errore di tipo durante la compilazione, come faresti con un linguaggio tipizzato staticamente, potresti invece ricevere un errore di runtime quando il JSII layer (che traduce tra Python e il TypeScript core) non è in grado AWS CDK di gestire il tipo imprevisto.

Secondo la nostra esperienza, gli errori di tipo commessi dai programmatori Python tendono a rientrare in queste categorie.

I moduli AWS CDK Python includono annotazioni di tipo, quindi puoi usare strumenti che li supportano per aiutarti con i tipi. Se non state usando uno IDE che li supporti, ad esempio, potreste voler chiamare il validatore dei MyPytipi come fase del processo di compilazione. PyCharm Esistono anche correttori del tipo di runtime che possono migliorare i messaggi di errore relativi agli errori relativi ai tipi.