Funzioni Lambda di Python

Il generatore di funzioni Lambda Python permette di aggiungere una funzione lambda a un progetto Python esistente.

Questo generatore crea un nuovo handler per funzioni lambda Python con la configurazione dell’infrastruttura AWS CDK o Terraform. Il backend generato utilizza AWS Lambda per il deployment serverless, con opzionale type-safety usando il Parser di AWS Lambda Powertools. Configura AWS Lambda Powertools per l’osservabilità, inclusi logging, tracciamento AWS X-Ray e metriche Cloudwatch.

Utilizzo

Genera una funzione Lambda

Puoi generare una nuova funzione Lambda in due modi:

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - py#lambda-function
5. Compila i parametri richiesti
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#lambda-function

yarn

yarn nx g @aws/nx-plugin:py#lambda-function

npm

npx nx g @aws/nx-plugin:py#lambda-function

bun

bunx nx g @aws/nx-plugin:py#lambda-function

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:py#lambda-function --dry-run

yarn

yarn nx g @aws/nx-plugin:py#lambda-function --dry-run

npm

npx nx g @aws/nx-plugin:py#lambda-function --dry-run

bun

bunx nx g @aws/nx-plugin:py#lambda-function --dry-run

Opzioni

Parametro	Tipo	Predefinito	Descrizione
project Obbligatorio	string	-	The project to add the lambda function to
functionName Obbligatorio	string	-	The name of the function to add
functionPath	string	-	The path within the project source directory to add the function to
eventSource	string	Any	Optional event source model to use for the lambda function
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

Output del generatore

Il generatore aggiungerà i seguenti file al tuo progetto:

• Directory<module-name>

  • <lambda-function>.py Implementazione della funzione

Se viene fornita l’opzione functionPath, il generatore aggiungerà i file necessari al percorso specificato:

• Directory<module-name>

  • Directory<custom-path>

    • <function-name>.py Implementazione della funzione

Infrastruttura

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider selezionato, creerà un progetto in packages/common che include i relativi costrutti CDK o moduli Terraform.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Nota

Questo progetto è generato utilizzando il ts#project generator e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Nota

Questo progetto è generato utilizzando il terraform#project generator e quindi configura gli stessi target di build.

Il generatore crea infrastruttura as-code per il deployment della funzione in base al iacProvider selezionato:

CDK

Il generatore crea costrutti CDK utilizzabili per deployare la funzione, residenti nella directory packages/common/constructs.

Terraform

Il generatore crea un modulo Terraform utilizzabile per deployare la funzione, residente nella directory packages/common/terraform/src/app/lambda-functions/<function-name>.

Implementazione della funzione

L’implementazione principale della funzione si trova in <function-name>.py. Ecco un esempio:

import os

from aws_lambda_powertools import Logger, Metrics, Tracer
from aws_lambda_powertools.metrics import MetricUnit
from aws_lambda_powertools.utilities.parser import event_parser
from aws_lambda_powertools.utilities.parser.models import EventBridgeModel
from aws_lambda_powertools.utilities.typing import LambdaContext

os.environ["POWERTOOLS_METRICS_NAMESPACE"] = "Foo"
os.environ["POWERTOOLS_SERVICE_NAME"] = "Foo"

logger: Logger = Logger()
metrics: Metrics = Metrics()
tracer: Tracer = Tracer()

@tracer.capture_lambda_handler
@metrics.log_metrics
@event_parser(model=EventBridgeModel)
def lambda_handler(event: EventBridgeModel, context: LambdaContext):
    logger.info("Received event", extra={"event": event.model_dump() })
    metrics.add_metric(name="InvocationCount", unit=MetricUnit.Count, value=1)

    try:
        # TODO: Implement
        metrics.add_metric(name="SuccessCount", unit=MetricUnit.Count, value=1)
        # TODO: Implement success response if required
    except Exception as e:
        logger.exception(e)
        metrics.add_metric(name="ErrorCount", unit=MetricUnit.Count, value=1)
        # TODO: Implement error response if required

Il generatore configura automaticamente diverse funzionalità:

1. Integrazione con AWS Lambda Powertools per l’osservabilità
2. Raccolta delle metriche
3. Type-safety usando @event_parser

Osservabilità con AWS Lambda Powertools

Logging

Il generatore configura il logging strutturato usando AWS Lambda Powertools.

def lambda_handler(event: EventBridgeModel, context: LambdaContext):
    logger.info("Received event", extra={"event": event.model_dump()})

Consiglio

Si raccomanda di impostare un correlation id per tutte le richieste uniche per facilitare il debugging e il monitoring. Consulta la documentazione di aws powertools logger per le best practice sui correlation id.

Il logger include automaticamente:

• Richieste di eventi
• Informazioni sul contesto Lambda
• Indicatori di cold start

Tracing

Il tracciamento AWS X-Ray è configurato automaticamente. Puoi aggiungere sottosegmenti personalizzati ai tuoi trace:

def lambda_handler(event: EventBridgeModel, context: LambdaContext):
    # Crea un nuovo sottosegmento
    with tracer.provider.in_subsegment("function-subsegment"):
        # La tua logica qui
        return ....

Metriche

Le metriche CloudWatch vengono raccolte automaticamente per ogni richiesta. Puoi aggiungere metriche personalizzate:

def lambda_handler(event: EventBridgeModel, context: LambdaContext):
    metrics.add_metric(name="NewMetric", unit=MetricUnit.Count, value=1)
    return ...

Le metriche predefinite includono:

• Conteggi delle invocazioni
• Conteggi successi/fallimenti
• Metriche sui cold start

Type Safety

Se hai scelto un eventSource durante la generazione della funzione lambda, la tua funzione è strumentata con @event_parser di AWS Lambda Powertools. Per esempio:

@event_parser(model=EventBridgeModel)
def lambda_handler(event: EventBridgeModel, context: LambdaContext):
    event.detail_type # <- type-safe con autocompletamento IDE

Questo permette di definire modelli dati usando Pydantic, in modo simile al lavoro con Fast API.

Consiglio

Se hai dati personalizzati annidati in un evento, per esempio uno stream DynamoDB o un evento EventBridge, potresti beneficiare dell’uso di Envelopes per garantire type-safety a quei dati.

Se non vuoi tipizzare l’evento, puoi semplicemente selezionare Any come eventSource.

Bundling

Il generatore configura automaticamente il bundling Python per i pacchetti di deployment Lambda usando uv:

pnpm

pnpm nx run <project-name>:bundle

yarn

yarn nx run <project-name>:bundle

npm

npx nx run <project-name>:bundle

bun

bunx nx run <project-name>:bundle

Nota

Questo processo include l’intero progetto nel pacchetto di deployment. Per minimizzare le dimensioni del deployment, potresti voler suddividere più funzioni lambda tra diversi progetti Python generati con il generatore py#project.

Questo processo utilizza:

1. uv export per esportare le dipendenze Python in un file requirements.txt
2. uv pip install per installare le dipendenze per la piattaforma target (x86_64-manylinux2014) per il deployment Lambda

Nota

Se modifichi l’architettura Lambda per usare ARM, dovrai modificare il target del bundle per usare aarch64-manylinux2014.

Deploy della funzione

Questo generatore crea infrastrutture come codice CDK o Terraform in base al iacProvider selezionato. Puoi utilizzarlo per distribuire la tua funzione.

CDK

Questo generatore crea un costrutto CDK per distribuire la tua funzione nella cartella common/constructs. Puoi utilizzarlo in un’applicazione CDK:

import { MyProjectMyFunction } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Aggiunge la funzione al tuo stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

Configura automaticamente:

1. Funzione AWS Lambda
2. Gruppo di log CloudWatch
3. Configurazione del tracciamento X-Ray
4. Namespace delle metriche CloudWatch

La funzione può essere utilizzata come target per qualsiasi sorgente eventi Lambda:

Nota

Assicurati che la sorgente eventi corrisponda all’opzione eventSource selezionata per garantire una corretta gestione degli eventi nella tua funzione handler.

L’esempio seguente mostra il codice CDK per invocare la tua funzione Lambda su una pianificazione usando EventBridge:

import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
import { MyProjectMyFunction } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Aggiunge la funzione al tuo stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // Aggiunge la funzione a una regola pianificata di EventBridge
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}

Terraform

Questo generatore crea un modulo Terraform per distribuire la tua funzione nella cartella common/terraform. Puoi utilizzarlo in una configurazione Terraform:

module "my_project_my_function" {
  source = "../../common/terraform/src/app/lambda-functions/my-project-my-function"

  # Variabili d'ambiente per la funzione Lambda
  env = {
    SOME_VARIABLE = "some value"
  }

  # Politiche IAM aggiuntive se necessarie
  additional_iam_policy_statements = [
    # Aggiungi eventuali permessi aggiuntivi richiesti dalla tua funzione
  ]
}

Configura automaticamente:

1. Funzione AWS Lambda
2. Gruppo di log CloudWatch
3. Configurazione del tracciamento X-Ray
4. Namespace delle metriche CloudWatch

La funzione può essere utilizzata come target per qualsiasi sorgente eventi Lambda. L’esempio seguente mostra il codice Terraform per invocare la tua funzione Lambda su una pianificazione usando EventBridge:

# Regola EventBridge per esecuzione pianificata
resource "aws_cloudwatch_event_rule" "my_function_schedule" {
  name                = "my-function-schedule"
  description         = "Attiva la mia funzione ogni 15 minuti"
  schedule_expression = "cron(15 * * * ? *)"
}

# Target EventBridge
resource "aws_cloudwatch_event_target" "lambda_target" {
  rule      = aws_cloudwatch_event_rule.my_function_schedule.name
  target_id = "MyFunctionTarget"
  arn       = module.my_project_my_function.function_arn
}

# Permesso per EventBridge di invocare la funzione Lambda
resource "aws_lambda_permission" "allow_eventbridge" {
  statement_id  = "AllowExecutionFromEventBridge"
  action        = "lambda:InvokeFunction"
  function_name = module.my_project_my_function.function_name
  principal     = "events.amazonaws.com"
  source_arn    = aws_cloudwatch_event_rule.my_function_schedule.arn
}

Nota

Assicurati che la sorgente eventi corrisponda all’opzione eventSource selezionata per garantire una corretta gestione degli eventi nella tua funzione handler.