O blog da AWS

Validando payload do evento com o Powertools for AWS Lambda (TypeScript)

Por Alexander Schüren, engenheiro senior na Amazon Web Services.

Validando payload do evento com o Powertools for AWS Lambda (TypeScript)

Nesta postagem, saiba como o novo utilitário Powertools for AWS Lambda (TypeScript) Parser pode ajudá-lo a validar cargas (payloads) com facilidade e tornar sua função Lambda mais resiliente.

A validação das cargas de entrada é um aspecto importante da criação de aplicativos seguros e confiáveis. Isso garante que os dados que um aplicativo recebe possam lidar normalmente com entradas inesperadas ou maliciosas e evitar o processamento prejudicial subsequente. Ao escrever funções do AWS Lambda, os desenvolvedores precisam validar e verificar a payload e garantir que campos e valores específicos estejam corretos e seguros de processar.

O Powertools for AWS Lambda é um kit de ferramentas para desenvolvedores disponível em Python, NodeJS/TypeScript, Java e .NET. Ele ajuda a implementar as melhores práticas em Serverless e a aumentar a velocidade do desenvolvedor. O Powertools for AWS Lambda (TypeScript) está introduzindo um novo utilitário Parser para ajudar os desenvolvedores a implementar com mais facilidade a validação em suas funções do Lambda.

Por que a validação do payload é importante

A validação de cargas pode tornar suas funções do Lambda mais resilientes. Cargas úteis que combinam informações técnicas e comerciais também podem ser difíceis de validar. Isso requer escrever uma lógica de validação dentro do código da função do Lambda. Isso pode variar de algumas instruções if para verificar os valores da payload até uma série complexa de etapas de validação com base na lógica de negócios personalizada. Talvez seja necessário separar a validação das informações técnicas da payload, como região da AWS, ID da conta, fonte do evento e informações comerciais dentro do evento, como ID do produto e detalhes do pagamento.

Pode ser difícil conhecer a estrutura e os valores do objeto do evento e como extrair as informações relevantes. Por exemplo, um evento do Amazon SQS tem um campo body com um valor de string, que pode ser um documento JSON. O Amazon EventBridge tem um objeto no campo de detalhes que você pode ler diretamente sem transformação adicional. Talvez seja necessário descompactar, decodificar, transformar e validar a carga dentro de um campo específico. Compreender as várias camadas de transformação pode ser complexo, especialmente se seu objeto de evento for resultado de várias invocações de serviço.

Usando o utilitário de análise Powertools for AWS Lambda (TypeScript)

O Powertools for AWS Lambda (TypeScript) é uma biblioteca modular. Você pode instalar seletivamente recursos como Logger, Tracer, Metrics, Batch Processing, Idempotency e muito mais. Você pode usar o Powertools for AWS Lambda nas bases de código TypeScript e JavaScript. O novo utilitário Parser simplifica a validação e usa a popular biblioteca de validação Zod.

Você pode usar o Parser  como decorador de métodos, com o middleware middy.js ou manualmente em todos os tempos de execução do NodeJS fornecidos pelo Lambda.

Para usar o utilitário, instale o utilitário de análise Powertools e o Zod (<v3.x) usando o NPM ou qualquer gerenciador de pacotes de sua escolha:

npm install @aws-lambda-powertools/parser zod@~3
Bash

Você pode definir seu esquema usando o Zod. Aqui está um exemplo de um esquema de pedido simples para validar eventos:

import { z } from 'zod';
const orderSchema = z.object({
    id: z.number().positive(),
	description: z.string(),
	items: z.array(
	    z.object({
		    id: z.number().positive(),
			quantity: z.number(),
			description: z.string(),
			})
		),
	});
export { orderSchema };
JavaScript

Esse esquema de pedido define o ID, a descrição e uma lista de itens. Você pode especificar os tipos de valor a partir de números simples, reduzi-los a positivos ou literais, ou mais complexos, como união, matriz ou até mesmo outro esquema. O Zod oferece uma lista extensa de tipos de valores que você pode usar.

Adicione o decorador do Parser  à sua função de manipulador, defina o parâmetro do esquema e use esse esquema para analisar o objeto do evento.

import type {Context} from 'aws-lambda';
import type {LambdaInterface} from '@aws-lambda-powertools/commons/types';
import {parser} from '@aws-lambda-powertools/parser';
import {z} from 'zod';
import {Logger} from '@aws-lambda-powertools/logger';

const logger = new Logger();

const orderSchema = z.object({
    id: z.number().positive(),  
	description: z.string(),  
	items: z.array(
	    z.object({
		    id: z.number().positive(),
			quantity: z.number(),
			description: z.string(),
		})
	),
});

type Order = z.infer<typeof orderSchema>;

class Lambda implements LambdaInterface {
    @parser({schema: orderSchema})  
	public async handler(event: Order, _context: Context): Promise<void> {
	    // event is now typed as Order 
		for (const item of event.items) {      
		    logger.info('Processing item', {item});
			// process order item from the event
		}
	}
}
	
const myFunction = new Lambda();

export const handler = myFunction.handler.bind(myFunction);
JavaScript

Observe que z.infer ajuda a extrair o tipo Order do esquema, o que melhora a experiência de desenvolvimento com preenchimento automático ao usar o TypeScript. O Zod analisa o objeto inteiro, incluindo campos aninhados, e relata todos os erros combinados, em vez de retornar somente o primeiro erro.

Usando o esquema incorporado para serviços da AWS

Um cenário mais comum é validar eventos dos serviços da AWS que acionam funções do Lambda, incluindo Amazon SQS, Amazon EventBridge e muito mais. Para facilitar isso, o Powertools inclui um esquema pré-criado para eventos da AWS que você pode usar.

Para analisar um evento de entrada do Amazon EventBridge, defina o esquema incorporado na configuração do seu Parser :

import {LambdaInterface} from '@aws-lambda-powertools/commons/types';
import {Context} from 'aws-lambda';
import {parser} from '@aws-lambda-powertools/parser';
import {EventBridgeSchema} from '@aws-lambda-powertools/parser/schemas';
import type {EventBridgeEvent} from '@aws-lambda-powertools/parser/types';

class Lambda implements LambdaInterface {  
    @parser({schema: EventBridgeSchema})  
	public async handler(event: EventBridgeEvent, _context: Context): Promise<void> {    
	    // event is parsed but the detail field is not specified 
	}
}

const myFunction = new Lambda();

export const handler = myFunction.handler.bind(myFunction);
JavaScript

O objeto do evento é analisado e validado durante o tempo de execução, e o tipo EventBridgeEvent do TypeScript ajuda você a entender a estrutura e acessar os campos durante o desenvolvimento. Neste exemplo, você analisa somente o objeto de evento EventBridge, então o campo de detalhes pode ser um objeto arbitrário.

Você também pode estender o esquema integrado do EventBridge e substituir o campo de detalhes pelo seu OderSchema personalizado.

import {LambdaInterface} from '@aws-lambda-powertools/commons/types';
import {Context} from 'aws-lambda';
import {parser} from '@aws-lambda-powertools/parser';
import {EventBridgeSchema} from '@aws-lambda-powertools/parser/schemas';
import {z} from 'zod';

const orderSchema = z.object({  
    id: z.number().positive(),  
	description: z.string(),  
	items: z.array(
	    z.object({
		    id: z.number().positive(),      
			quantity: z.number(),      
			description: z.string(),
		}), 
	),
});

const eventBridgeOrderSchema = EventBridgeSchema.extend({  detail: orderSchema,});

type EventBridgeOrder = z.infer<typeof eventBridgeOrderSchema>;

class Lambda implements LambdaInterface {  
    @parser({schema: eventBridgeOrderSchema})  public async handler(event: EventBridgeOrder, _context: Context): Promise<void> {
	    // event.detail is now parsed as orderSchema 
	}
}

const myFunction = new Lambda();

export const handler = myFunction.handler.bind(myFunction);
JavaScript

O Parser  valida a estrutura completa de todo o evento do EventBridge, incluindo o objeto de negócios personalizado. Use .extend ou outras funções do esquema Zod para alterar qualquer campo do esquema incorporado e personalizar a validação da payload.

Usando envelopes com esquema personalizado

Em alguns casos, você só precisa da parte personalizada da carga, por exemplo, do campo de detalhes do evento EventBridge ou do corpo dos registros SQS. Isso exige que você analise o esquema do evento manualmente, extraia o campo obrigatório e depois o analise novamente com o esquema personalizado. Isso é complexo, pois você precisa saber o campo exato da payload e como transformá-lo e analisá-lo.

O utilitário Powertools Parser ajuda a resolver esse problema com envelopes. Envelopes são objetos de esquema com lógica integrada para extrair cargas personalizadas.

Aqui está um exemplo do EventBridgeEnvelope de como ele funciona:

import {LambdaInterface} from '@aws-lambda-powertools/commons/types';
import {Context} from 'aws-lambda';
import {parser} from '@aws-lambda-powertools/parser';
import {EventBridgeEnvelope} from '@aws-lambda-powertools/parser/envelopes';
import {z} from 'zod';

const orderSchema = z.object({  
    id: z.number().positive(), 
	description: z.string(),  
	items: z.array(    
	    z.object({      
		    id: z.number().positive(),      
			quantity: z.number(),      
			description: z.string(),
		}), 
	),
});

type Order = z.infer<typeof orderSchema>;

class Lambda implements LambdaInterface {  
    @parser({schema: orderSchema, envelope: EventBridgeEnvelope})  public async handler(event: Order, _context: Context): Promise<void> {
        // event is now typed as Order inferred from the orderSchema 
    }
}

const myFunction = new Lambda();

export const handler = myFunction.handler.bind(myFunction);
JavaScript

Ao definir o esquema e o envelope, o utilitário do Parser sabe como combinar os dois parâmetros, extrair e validar a carga personalizada do evento. O Powertools Parser transforma o objeto do evento de acordo com a definição do esquema para que você possa se concentrar na parte crítica do código para os negócios dentro da função do manipulador.

Análise segura

Se o objeto não corresponder ao esquema Zod fornecido, por padrão, o Parser  lançará ParserError. Se você precisar controlar os erros de validação e implementar o tratamento personalizado de erros, use a opção SafeParse.

Aqui está um exemplo de como capturar validações com falha como uma métrica em sua função de manipulador:

import {Logger} from "@aws-lambda-powertools/logger";
import {LambdaInterface} from "@aws-lambda-powertools/commons/types";
import {parser} from "@aws-lambda-powertools/parser";
import {orderSchema} from "../app/schema";import {z} from "zod";
import {EventBridgeEnvelope} from "@aws-lambda-powertools/parser/envelopes";
import {Metrics, MetricUnit} from "@aws-lambda-powertools/metrics";
import {ParsedResult, EventBridgeEvent} from "@aws-lambda-powertools/parser/types";

const logger = new Logger();

const metrics = new Metrics();

type Order = z.infer<typeof orderSchema>;

class Lambda implements LambdaInterface {  

    @metrics.logMetrics() 
	@parser({schema: orderSchema, envelope: EventBridgeEnvelope, safeParse: true})  
	public async handler(event: ParsedResult<EventBridgeEvent, Order>, _context: unknown): Promise<void> {
	    if (!event.success) {      
		    // failed validation 
			metrics.addMetric('InvalidPayload', MetricUnit.Count, 1);      
			logger.error('Invalid payload', event.originalEvent);    
		} else {      
		    // successful validation 
			for (const item of event.data.items) {        
			    logger.info('Processing item', item);        
				// event.data is typed as Order 
			}   
		}  
	}
}

const myFunction = new Lambda();

export const handler = myFunction.handler.bind(myFunction);
JavaScript

Definir a opção SafeParse como verdadeira não gera um erro, mas retorna um objeto de evento modificado que tem um sinalizador de sucesso e campos de erro ou de dados, dependendo do resultado da validação. Em seguida, você pode criar um tratamento personalizado de erros, por exemplo, incrementar a métrica InvalidPayload e acessar o OriginalEvent para registrar um erro.

Para validações bem-sucedidas, você pode acessar o campo de dados e processar a payload. Observe que o tipo de objeto do evento agora é ParsedResult com EventBridgeEvent como entrada e Order como tipos de saída.

Validações personalizadas

Às vezes, você pode precisar de regras de negócios mais complexas para sua validação. Como os esquemas integrados do Parser são objetos Zod, você pode personalizar a validação aplicando .extend, .refine, .transform e outros operadores Zod. Aqui está um exemplo de regras complexas para o OrderSchema:

import {z} from 'zod';

const orderSchema = z.object({
    id: z.number().positive(),  
	description: z.string(),  
	items: z.array(z.object({
	    id: z.number().positive(),    
		quantity: z.number(),    
		description: z.string(),  
	})).refine((items) => items.length > 0, {
	    message: 'Order must have at least one item',  
	}),
})  
    .refine((order) => order.id > 100 && order.items.length > 100, {
	    message:      'All orders with more than 100 items must have an id greater than 100', 
	});
JavaScript

Use .refine no campo de itens para verificar se há pelo menos um item no pedido. Você também pode combinar vários campos, aqui order.id e order.items.length, para ter uma regra específica para pedidos com mais de 100 itens. Lembre-se de que .refine é executado durante a etapa de validação e .transform será aplicado após a validação. Isso permite que você altere a forma dos dados para normalizar a saída.

Conclusão

O Powertools for AWS Lambda (TypeScript) está introduzindo um novo utilitário Parser que facilita a adição de validação às suas funções do Lambda. Com base na popular biblioteca de validação Zod, a Powertools oferece um amplo conjunto de esquemas integrados para integrações de serviços populares da AWS, incluindo Amazon SQS, Amazon DynamoDB e Amazon EventBridge. Os desenvolvedores podem usar esses esquemas para validar suas cargas de eventos e também personalizá-las de acordo com suas necessidades comerciais.

Visite a documentação para saber mais e participe da nossa comunidade Powertools Discord para se conectar com entusiastas sem servidor que pensam da mesma forma.

Este conteúdo foi traduzido da postagem original do blog, que pode ser encontrada aqui.

Biografia do Autor

Alexander Schüren, engenheiro senior na Amazon Web Services

Biografia do tradutor

Daniel Abib é Arquiteto de Soluções Sênior e Especialista em Amazon Bedrock na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e especialização em Machine Learning. Ele trabalha apoiando Startups, ajudando-os em sua jornada para a nuvem.

https://www.linkedin.com/in/danielabib/

.

Biografia do Revisor

Rodrigo Peres é Arquiteto de Soluções na AWS, com mais de 20 anos de experiência trabalhando com arquitetura de soluções, desenvolvimento de sistemas e modernização de sistemas legados.