Questa è la AWS CDK v2 Developer Guide. Il vecchio CDK v1 è entrato 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 il AWS Cloud Development Kit (AWS CDK) ed è considerato stabile. Lavorare con il AWS CDK in Python utilizza strumenti familiari, tra cui l'implementazione standard di Python CPython ()`virtualenv`, ambienti virtuali con e il programma di installazione del pacchetto Python. `pip` [I moduli che compongono la Construct Library sono distribuiti tramite pypi.org AWS .](https://pypi.org/search/?q=aws-cdk) La versione Python del AWS CDK utilizza anche identificatori in stile Python (ad esempio, i nomi dei metodi). `snake_case`
Puoi usare qualsiasi editor o IDE. [Molti sviluppatori AWS CDK utilizzano [Visual Studio Code](https://code.visualstudio.com/) (o il suo equivalente open source [VSCodium](https://vscodium.com/)), che supporta bene Python tramite un'estensione ufficiale.](https://marketplace.visualstudio.com/items?itemName=ms-python.python) L'editor IDLE incluso in Python sarà sufficiente per iniziare. I moduli Python per il AWS CDK dispongono di suggerimenti di tipo, utili per uno strumento di linting o un IDE che supporti la convalida dei tipi.
## Inizia a usare Python
Per utilizzare il AWS CDK, è necessario disporre di un AWS account e delle credenziali e aver installato Node.js e CDK Toolkit. AWS Vedi [Guida introduttiva](getting-started.md) al CDK. AWS
Le applicazioni Python AWS CDK richiedono Python 3.9 o versione successiva. [Se non l'hai già installato, [scarica una versione compatibile](https://www.python.org/downloads/) per il tuo sistema operativo da python.org.](https://www.python.org/) Se usi Linux, il tuo sistema potrebbe avere una versione compatibile, oppure puoi installarlo usando il gestore di pacchetti della tua distribuzione (`yum``apt`, ecc.). Gli utenti Mac potrebbero essere interessati a [Homebrew](https://brew.sh/), un gestore di pacchetti in stile Linux per macOS.
**Nota**
Obsolitudine linguistica di terze parti: la versione linguistica è supportata solo fino alla fine del ciclo di vita (EOL (End Of Life) condivisa dal fornitore o dalla community ed è soggetta a modifiche con preavviso.
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.
**Nota**
È comune che le distribuzioni Linux utilizzino il nome eseguibile `python3` per Python 3.x e `python` facciano riferimento a un'installazione di Python 2.x. Alcune distribuzioni hanno un pacchetto opzionale che puoi installare che fa sì che il `python` comando faccia riferimento a Python 3. In caso contrario, è possibile modificare il comando utilizzato per eseguire l'applicazione modificandolo `cdk.json` nella directory principale del progetto.
**Nota**
Su Windows, potresti voler invocare Python (`pip`and) usando `py` l'eseguibile, il programma di avvio [Python](https://docs.python.org/3/using/windows.html#launcher) per Windows. Tra le altre cose, il programma di avvio consente di specificare facilmente quale versione installata di Python si desidera utilizzare.
Se digitando `python` nella riga di comando viene visualizzato un messaggio sull'installazione di Python da Windows Store, anche dopo aver installato una versione Windows di Python, apri il pannello delle impostazioni Manage App Execution Aliases di Windows e disattiva le due voci dell'App Installer per Python.
## Creare un progetto
È possibile creare un nuovo progetto AWS CDK invocandolo in una directory vuota. `cdk init` Utilizzate l'`--language`opzione e specificate: `python`
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language python
```
`cdk init`utilizza 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
```
**Nota**
Potresti riconoscerlo come il Mac/Linux comando per attivare un ambiente virtuale. I modelli Python includono un file batch, `source.bat`, che consente di utilizzare lo stesso comando su Windows. Anche il comando tradizionale `.\venv\Scripts\activate` di Windows funziona.
Se hai inizializzato il progetto AWS CDK utilizzando CDK Toolkit v1.70.0 o versione precedente, l'ambiente virtuale si trova invece nella directory. `.env` `.venv`
**Importante**
Attiva l'ambiente virtuale del progetto ogni volta che inizi a lavorarci. Altrimenti, non avrai accesso ai moduli installati lì e i moduli che installerai andranno nella directory globale dei moduli di Python (o genereranno un errore di autorizzazione).
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 di 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` `pip`installa 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
```
La maggior parte dei AWS costrutti CDK sono presenti. `aws-cdk-lib` I moduli sperimentali si trovano in moduli separati denominati come. `aws-cdk..alpha` Il nome del servizio include un prefisso *aws*. Se non sei sicuro del nome di un modulo, [cercalo in PyPI](https://pypi.org/search/?q=aws-cdk). 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 esempio`aws-cdk.aws-route53`, ci sono inoltre tre namespace Amazon Route 53 aggiuntivi`aws-route53-targets`, `aws-route53-patterns` denominati e. `aws-route53resolver`
**Nota**
L'[edizione Python del CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/python/index.html) mostra anche i nomi dei pacchetti.
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 classi AWS CDK e moduli AWS Construct Library nelle applicazioni. Seguire queste linee guida contribuirà a rendere il codice coerente con altre applicazioni AWS CDK e più facile da comprendere.
+ In genere, importa singole classi dal livello superiore`aws_cdk`.
```
from aws_cdk import App, Construct
```
+ Se hai bisogno di molte classi da`aws_cdk`, puoi utilizzare un alias dello spazio dei nomi di `cdk` invece di importare singole classi. Evita di fare entrambe le cose.
```
import aws_cdk as cdk
```
+ In genere, importate le librerie AWS Construct utilizzando alias di namespace brevi.
```
import aws_cdk.aws_s3 as s3
```
Dopo aver installato un modulo, aggiorna il `requirements.txt` file del progetto, che elenca le dipendenze del progetto. È meglio farlo manualmente anziché utilizzare`pip freeze`. `pip freeze`acquisisce 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
```
## Gestire le 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. PIP viene richiamato in uno dei seguenti modi:
```
pip
python -m pip
```
L'`python -m pip`invocazione funziona sulla maggior parte dei sistemi; `pip` richiede che l'eseguibile di PIP si trovi 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 tuo 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
### Applicazioni CDK
Di seguito è riportato un esempio del file `requirements.txt`. Poiché PIP non dispone di una funzionalità 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 in`requirements.txt`.
Per installare o aggiornare le dipendenze del progetto dopo la creazione o la modifica`requirements.txt`, esegui quanto segue:
```
python -m pip install -r requirements.txt
```
**Suggerimento**
Il `pip freeze` comando restituisce le versioni di tutte le dipendenze installate in un formato che può essere scritto in un file di testo. Questo può essere usato come file dei requisiti con. `pip install -r` Questo file è utile per aggiungere tutte le dipendenze (comprese quelle transitive) alle versioni esatte con cui hai testato. Per evitare problemi quando si aggiornano i pacchetti in un secondo momento, utilizzate un file separato, ad esempio (not). `freeze.txt` `requirements.txt` Quindi, rigeneralo quando aggiorni le dipendenze del progetto.
### Librerie di costruzioni di terze parti
Nelle librerie, le dipendenze sono specificate in`setup.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 PIP installi 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 Idiomi CDK in Python
### Conflitti linguistici
In Python, `lambda` è una parola chiave del linguaggio, quindi non è possibile utilizzarla come nome per il modulo della libreria di costruzioni AWS Lambda o per le funzioni Lambda. La convenzione di Python per tali conflitti consiste nell'utilizzare un carattere di sottolineatura finale, come in`lambda_`, nel nome della variabile.
Per convenzione, il secondo argomento dei costrutti AWS CDK viene denominato. `id` Quando scrivi i tuoi stack e i tuoi costrutti, chiamando un parametro `id` «shadows» la funzione incorporata in Python`id()`, 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 key/value coppie 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 dovresti accettare gli argomenti che non ti interessano usando l'idioma \$1\$1kwargs e usare argomenti basati solo su parole chiave per accettare gli argomenti che ti interessano. Quando chiami il costruttore del genitore o il metodo sovrascritto, passa solo gli argomenti che si aspetta (spesso solo \$1\$1kwargs). 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 del 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 vostro costrutto o 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
Il AWS CDK lo utilizza `None` per rappresentare valori mancanti o non definiti. Quando lavori con \$1\$1kwargs, usa il `get()` metodo del dizionario per fornire un valore predefinito se non viene fornita una proprietà. Evita di utilizzarlo`kwargs[…]`, poiché ciò genera valori mancanti`KeyError`.
```
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 metodi AWS CDK (`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](https://docs.python.org/3/library/abc.html), che sono simili. (Se non hai familiarità con le interfacce, Wikipedia ha [una buona introduzione](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages).) TypeScript, il linguaggio in cui è implementato il AWS CDK, fornisce interfacce e i costrutti e altri oggetti AWS CDK spesso richiedono un oggetto che aderisca a una particolare interfaccia, anziché ereditare da una particolare classe. [Quindi il AWS CDK fornisce la propria funzionalità di interfaccia come parte del livello JSII.](https://github.com/aws/jsii)
Per indicare che una classe implementa una particolare interfaccia, puoi usare il decoratore: `@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)
```
### 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 costrutto AWS CDK. Invece di ricevere un errore di tipo durante la compilazione, come accadrebbe con un linguaggio tipizzato staticamente, potresti invece ricevere un errore di runtime quando il livello JSII (che traduce tra Python e il core del AWS CDK) non è TypeScript in grado di gestire il tipo imprevisto.
In base alla nostra esperienza, gli errori di tipo commessi dai programmatori Python tendono a rientrare in queste categorie.
+ Passare un singolo valore in cui un costrutto prevede un contenitore (elenco o dizionario Python) o viceversa.
+ Passare un valore di un tipo associato a un costrutto di livello 1 (`CfnXxxxxx`) a un costrutto L2 o L3 o viceversa.
## Prevenzione degli errori di tipo
I moduli AWS CDK Python includono annotazioni di tipo, quindi puoi utilizzare strumenti che li supportano per catturare gli errori di tipo prima della distribuzione.
### Integrazione IDE (consigliata)
Visual Studio Code con Pylance fornisce il controllo dei tipi in tempo reale durante la scrittura del codice:
1. [Installa l'estensione Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
1. Configura il tipo di check-in rigoroso: `.vscode/settings.json`
```
{
"python.languageServer": "Pylance",
"python.analysis.typeCheckingMode": "strict"
}
```
1. Gli errori di digitazione ora vengono visualizzati immediatamente con scarabocchi rossi e messaggi di errore dettagliati
[PyCharm](https://www.jetbrains.com/pycharm/)offre anche un controllo dei tipi integrato con funzionalità simili.
### Controllo del tipo tramite riga di comando
Per le CI/CD pipeline o la convalida prima del commit, usa uno di questi correttori di tipo:
**MyPy (Basato su Python):**
```
pip install mypy
mypy app.py
```
**Pyright (più veloce, JavaScript basato sullo stesso motore di Pylance):**
```
npm install -g pyright
pyright app.py
```
### Flusso di lavoro raccomandato
1. Durante lo sviluppo: usa Pyt o Pylance per un feedback immediato
1. Prima del commit: Esegui o `mypy app.py` `pyright app.py`
1. In CI/CD: imposta il controllo del tipo come passaggio obbligatorio prima della distribuzione