Funzioni Lambda Python

Il generatore di Funzioni Lambda Python fornisce la capacità di aggiungere una funzione lambda a un progetto python esistente.

Questo generatore crea un nuovo handler lambda python con configurazione dell’infrastruttura AWS CDK o Terraform. Il backend generato utilizza AWS Lambda per il deployment serverless, con type-safety opzionale utilizzando il Parser da AWS Lambda Powertools. Configura AWS Lambda Powertools per l’osservabilità, inclusi logging, tracing AWS X-Ray e Cloudwatch Metrics.

Utilizzo

Generare una Funzione Lambda

Puoi generare una nuova Funzione Lambda in due modi:

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

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
project Obbligatorio	string	-	Il progetto a cui aggiungere la funzione lambda
name Obbligatorio	string	-	Il nome della funzione da aggiungere
functionPath	string	-	Il percorso all'interno della directory sorgente del progetto in cui aggiungere la funzione
event	Any | AlbModel | APIGatewayProxyEventModel | ApiGatewayAuthorizerToken | ApiGatewayAuthorizerRequest | APIGatewayProxyEventV2Model | ApiGatewayAuthorizerRequestV2 | APIGatewayWebSocketMessageEventModel | APIGatewayWebSocketConnectEventModel | APIGatewayWebSocketDisconnectEventModel | BedrockAgentEventModel | CloudFormationCustomResourceCreateModel | CloudFormationCustomResourceUpdateModel | CloudFormationCustomResourceDeleteModel | CloudWatchLogsModel | DynamoDBStreamModel | EventBridgeModel | IoTCoreThingEvent | IoTCoreThingTypeEvent | IoTCoreThingTypeAssociationEvent | IoTCoreThingGroupEvent | IoTCoreAddOrRemoveFromThingGroupEvent | IoTCoreAddOrDeleteFromThingGroupEvent | KafkaMskEventModel | KafkaSelfManagedEventModel | KinesisDataStreamModel | KinesisFirehoseModel | KinesisFirehoseSqsModel | LambdaFunctionUrlModel | S3BatchOperationModel | S3EventNotificationEventBridgeModel | S3Model | S3ObjectLambdaEvent | S3SqsEventNotificationModel | SesModel | SnsModel | SqsModel | TransferFamilyAuthorizer | VpcLatticeModel | VpcLatticeV2Model	Any	Modello di origine evento opzionale da utilizzare per la funzione lambda
infra	lambda | none	lambda	Il tipo di infrastruttura con cui distribuire la tua funzione Lambda.
iac	inherit | cdk | terraform	inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore aggiungerà i seguenti file al tuo progetto:

• Directory<module-name>

  • <lambda-function>.py Function implementation

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

• Directory<module-name>

  • Directory<custom-path>

    • <function-name>.py Function implementation

Infrastruttura

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

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

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Progetto Generato

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

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Progetto Generato

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

Il generatore crea infrastructure as code per il deployment della tua funzione in base al tuo iac selezionato:

CDK

Il generatore crea costrutti CDK che possono essere utilizzati per il deployment della tua funzione, che risiedono nella directory packages/common/constructs.

Terraform

Il generatore crea un modulo Terraform che può essere utilizzato per il deployment della tua funzione, che risiede nella directory packages/common/terraform/src/app/lambda-functions/<function-name>.

Architettura

La funzione distribuita ha la seguente architettura:

Il generatore fornisce la funzione stessa; è necessario collegare la sorgente degli eventi nello stack per invocarla (ad esempio, un’integrazione API Gateway, una regola EventBridge, una notifica S3 o un mapping di sorgente eventi SQS).

Implementare la tua 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 di AWS Lambda Powertools per l’osservabilità
2. Raccolta di metriche
3. Type-safety utilizzando @event_parser

Osservabilità con AWS Lambda Powertools

Logging

Il generatore configura il logging strutturato utilizzando AWS Lambda Powertools.

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

Correlation ID

Si consiglia di impostare il correlation id per tutte le richieste univoche per facilitare il debugging e il monitoraggio. Si prega di fare riferimento alla documentazione del aws powertools logger per le best practice relative al correlation id.

Il logger include automaticamente:

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

Tracing

Il tracing AWS X-Ray è configurato automaticamente. Puoi aggiungere subsegment personalizzati alle tue tracce:

def lambda_handler(event: EventBridgeModel, context: LambdaContext):
    # Creates a new subsegment
    with tracer.provider.in_subsegment("function-subsegment"):
        # Your logic here
        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 di successo/fallimento
• Metriche di cold start

Type Safety

event ≠ Any

Se hai scelto un event durante la generazione della tua funzione lambda, la tua funzione è instrumentata con @event_parser da AWS Lambda Powertools. Per esempio:

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

Questo ti permette di definire modelli di dati utilizzando Pydantic, in modo simile a lavorare con Fast API.

Dati Evento Personalizzati

Se hai dati personalizzati annidati all’interno di un evento, ad esempio uno stream DynamoDB o un evento EventBridge, potresti trarre vantaggio dall’utilizzo di Envelopes per fornire type-safety per quei dati personalizzati.

event = Any

Se hai selezionato Any per il tuo event, il decorator @event_parser non viene applicato e l’handler riceve un dict di eventi non tipizzato. Rigenera con un event specifico se desideri la validazione Pydantic e l’accesso ai campi tipizzati.

Bundling

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

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Comportamento del Bundle

Questo raggruppa l’intero progetto come pacchetto di deployment. Per minimizzare la dimensione del deployment, potresti voler suddividere più funzioni lambda su più progetti Python generati con il generatore py#project.

Questo processo utilizza:

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

Modifiche all’Architettura

Se modifichi la tua architettura lambda in ARM, dovrai modificare il tuo target di bundle per utilizzare il target aarch64-manylinux_2_28.

Deployment della tua Funzione

Questo generatore crea infrastruttura come codice CDK o Terraform in base al tuo iac 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) {
    // Add the function to your stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

Questo configura:

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

Questa funzione può quindi essere utilizzata come destinazione per qualsiasi sorgente di eventi lambda:

Corrispondenza della sorgente di eventi

Assicurati che la sorgente di eventi corrisponda all’opzione event selezionata per garantire che l’evento sia gestito correttamente all’interno della tua funzione handler.

L’esempio seguente dimostra il codice CDK per invocare la tua funzione lambda secondo una pianificazione utilizzando 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) {
    // Add the function to your stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // Add the function to an EventBridge scheduled rule
    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. Istanzia il modulo condiviso core/asset-bucket una volta per distribuzione e passa il suo bucket_name nell’input asset_bucket_name:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name

  env = {
    SOME_VARIABLE = "some value"
  }

  additional_iam_policy_statements = [
    # Add any additional permissions your function needs
  ]
}

Questo configura:

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

Questa funzione può quindi essere utilizzata come destinazione per qualsiasi sorgente di eventi lambda. L’esempio seguente dimostra il codice Terraform per invocare la tua funzione lambda secondo una pianificazione utilizzando EventBridge:

# EventBridge rule for scheduled execution
resource "aws_cloudwatch_event_rule" "my_function_schedule" {
  name                = "my-function-schedule"
  description         = "Trigger my function every 15 minutes"
  schedule_expression = "cron(15 * * * ? *)"
}

# EventBridge target
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
}

# Permission for EventBridge to invoke the Lambda function
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
}

Corrispondenza della sorgente di eventi

Assicurati che la sorgente di eventi corrisponda all’opzione event selezionata per garantire che l’evento sia gestito correttamente all’interno della tua funzione handler.