Funções Lambda em Python

O gerador de Função Lambda em Python permite adicionar uma função lambda a um projeto Python existente.

Este gerador cria um novo handler de lambda Python com configuração de infraestrutura AWS CDK. O backend gerado utiliza AWS Lambda para implantação serverless, com tipagem opcional usando o Parser do AWS Lambda Powertools. Ele configura o AWS Lambda Powertools para observabilidade, incluindo logging, rastreamento com AWS X-Ray e métricas no CloudWatch.

Uso

Gerar uma Função Lambda

Você pode gerar uma nova Função Lambda de duas formas:

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - py#lambda-function
5. Preencha os parâmetros obrigatórios
6. Clique em 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	The project to add the lambda function to
functionName Obrigatório	string	-	The name of the function to add
functionPath	string	-	The path within the project source directory to add the function to
eventSource Obrigatório	string	Any	Optional event source model to use for the lambda function

Saída do Gerador

O gerador adicionará os seguintes arquivos ao seu projeto:

• Directory<module-name>

  • <lambda-function>.py Implementação da função

O gerador também cria construtos CDK para implantação da função, que residem no diretório packages/common/constructs.

Se a opção functionPath for fornecida, o gerador adicionará os arquivos no caminho especificado:

• Directory<module-name>

  • Directory<custom-path>

    • <function-name>.py Implementação da função

Implementando sua Função

A implementação principal está em <function-name>.py. Veja um exemplo:

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

O gerador configura automaticamente vários recursos:

1. Integração com AWS Lambda Powertools para observabilidade
2. Coleta de métricas
3. Tipagem segura usando @event_parser

Observabilidade com AWS Lambda Powertools

Logging

O gerador configura logging estruturado usando AWS Lambda Powertools.

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

Dica

Recomenda-se definir um correlation id para requisições únicas para facilitar depuração e monitoramento. Consulte a documentação do aws powertools logger para melhores práticas.

O logger inclui automaticamente:

• Requisições de eventos
• Informações de contexto do Lambda
• Indicadores de cold start

Tracing

O rastreamento com AWS X-Ray é configurado automaticamente. Você pode adicionar subsegmentos personalizados:

def lambda_handler(event: EventBridgeModel, context: LambdaContext):
    # Cria um novo subsegmento
    with tracer.provider.in_subsegment("function-subsegment"):
        # Sua lógica aqui
        return ....

Métricas

Métricas do CloudWatch são coletadas automaticamente. Você pode adicionar métricas personalizadas:

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

Métricas padrão incluem:

• Contagem de invocações
• Contagem de sucessos/falhas
• Métricas de cold start

Tipagem Segura

Se você escolheu um eventSource ao gerar sua função, ela será instrumentada com @event_parser do AWS Lambda Powertools. Exemplo:

@event_parser(model=EventBridgeModel)
def lambda_handler(event: EventBridgeModel, context: LambdaContext):
    event.detail_type # <- tipagem segura com autocompletar na IDE

Isso permite definir modelos de dados usando Pydantic, similar ao funcionamento com FastAPI.

Dica

Para dados personalizados aninhados em eventos (ex: streams DynamoDB ou eventos EventBridge), você pode usar Envelopes para garantir tipagem segura.

Se não desejar tipar seu evento, selecione Any para o eventSource.

Implantando sua Função

O gerador cria um construto CDK para implantação no diretório common/constructs. Use em uma aplicação CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Adiciona a função à stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

Isso configura:

1. Função AWS Lambda
2. Grupo de logs no CloudWatch
3. Configuração de rastreamento X-Ray
4. Namespace de métricas no CloudWatch

A função pode ser usada como alvo para qualquer event source do Lambda:

Nota

Garanta que o event source corresponda à opção eventSource selecionada para tratamento adequado do evento.

O exemplo abaixo demonstra código CDK para invocar sua função em um agendamento usando Event Bridge:

import { EventPattern, 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) {
    // Adiciona a função à stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // Adiciona a função a uma regra do EventBridge
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}