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:

Esegui questo generatore@aws/nx-plugin:py#lambda-function

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

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

Componi il tuo comando7

projectObbligatorio

nameObbligatorio

event

AnyAlbModelAPIGatewayProxyEventModelApiGatewayAuthorizerTokenApiGatewayAuthorizerRequestAPIGatewayProxyEventV2ModelApiGatewayAuthorizerRequestV2APIGatewayWebSocketMessageEventModelAPIGatewayWebSocketConnectEventModelAPIGatewayWebSocketDisconnectEventModelBedrockAgentEventModelCloudFormationCustomResourceCreateModelCloudFormationCustomResourceUpdateModelCloudFormationCustomResourceDeleteModelCloudWatchLogsModelDynamoDBStreamModelEventBridgeModelIoTCoreThingEventIoTCoreThingTypeEventIoTCoreThingTypeAssociationEventIoTCoreThingGroupEventIoTCoreAddOrRemoveFromThingGroupEventIoTCoreAddOrDeleteFromThingGroupEventKafkaMskEventModelKafkaSelfManagedEventModelKinesisDataStreamModelKinesisFirehoseModelKinesisFirehoseSqsModelLambdaFunctionUrlModelS3BatchOperationModelS3EventNotificationEventBridgeModelS3ModelS3ObjectLambdaEventS3SqsEventNotificationModelSesModelSnsModelSqsModelTransferFamilyAuthorizerVpcLatticeModelVpcLatticeV2ModelMostra tutti 40

infra

lambdanone

iac

inheritcdkterraform

functionPath

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Opzioni

Opzioni del generatore7 opzioni

projectObbligatoriostring

Il progetto a cui aggiungere la funzione lambda

nameObbligatoriostring

Il nome della funzione da aggiungere

eventenumPredefinito: Any

Modello di origine evento opzionale da utilizzare per la funzione lambda

AnyAlbModelAPIGatewayProxyEventModelApiGatewayAuthorizerTokenApiGatewayAuthorizerRequestAPIGatewayProxyEventV2ModelApiGatewayAuthorizerRequestV2APIGatewayWebSocketMessageEventModelAPIGatewayWebSocketConnectEventModelAPIGatewayWebSocketDisconnectEventModelBedrockAgentEventModelCloudFormationCustomResourceCreateModelCloudFormationCustomResourceUpdateModelCloudFormationCustomResourceDeleteModelCloudWatchLogsModelDynamoDBStreamModelEventBridgeModelIoTCoreThingEventIoTCoreThingTypeEventIoTCoreThingTypeAssociationEventIoTCoreThingGroupEventIoTCoreAddOrRemoveFromThingGroupEventIoTCoreAddOrDeleteFromThingGroupEventKafkaMskEventModelKafkaSelfManagedEventModelKinesisDataStreamModelKinesisFirehoseModelKinesisFirehoseSqsModelLambdaFunctionUrlModelS3BatchOperationModelS3EventNotificationEventBridgeModelS3ModelS3ObjectLambdaEventS3SqsEventNotificationModelSesModelSnsModelSqsModelTransferFamilyAuthorizerVpcLatticeModelVpcLatticeV2ModelMostra tutti 40

infraenumPredefinito: lambda

Il tipo di infrastruttura con cui distribuire la tua funzione Lambda.

lambdanone

iacenumPredefinito: inherit

Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.

inheritcdkterraform

functionPathstring

Il percorso all'interno della directory sorgente del progetto in cui aggiungere la funzione

preferInstallDependenciesbooleanPredefinito: 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, con i suoi log, metriche e tracce che vanno a CloudWatch e X-Ray:

Loading the diagram…

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
@logger.inject_lambda_context
@metrics.log_metrics(capture_cold_start_metric=True)
@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.

L’handler è decorato con @logger.inject_lambda_context, quindi ogni record di log che emette contiene anche:

• function_name, function_memory_size, function_arn e function_request_id dal contesto Lambda
• cold_start, che indica se l’invocazione ha inizializzato un nuovo ambiente di esecuzione

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:

• InvocationCount, aggiunta ad ogni invocazione
• SuccessCount e ErrorCount, aggiunte dal blocco try/except dell’handler
• ColdStart, emessa da @metrics.log_metrics(capture_cold_start_metric=True) quando l’invocazione inizializza un nuovo ambiente di esecuzione

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.