@@ -3,7 +3,249 @@ title: Serialization Utilities
33description : Utility
44---
55
6- This module contains a set of utilities you may use in your Lambda functions, mainly associated with other modules like [ validation] ( validation.md ) and [ idempotency] ( idempotency.md ) , to manipulate JSON.
6+ This module contains a set of utilities you may use in your Lambda functions, to manipulate JSON.
7+
8+ ## Easy deserialization
9+
10+ ### Key features
11+
12+ * Easily deserialize the main content of an event (for example, the body of an API Gateway event)
13+ * 15+ built-in events (see the [ list below] ( #built-in-events ) )
14+
15+ ### Getting started
16+
17+ === "Maven"
18+
19+ ```xml hl_lines="5"
20+ <dependencies>
21+ ...
22+ <dependency>
23+ <groupId>software.amazon.lambda</groupId>
24+ <artifactId>powertools-serialization</artifactId>
25+ <version>{{ powertools.version }}</version>
26+ </dependency>
27+ ...
28+ </dependencies>
29+ ```
30+
31+ === "Gradle"
32+
33+ ```
34+ implementation 'software.amazon.lambda:powertools-serialization:{{ powertools.version }}'
35+ ```
36+
37+ ### EventDeserializer
38+
39+ The ` EventDeserializer ` can be used to extract the main part of an event (body, message, records) and deserialize it from JSON to your desired type.
40+
41+ It can handle single elements like the body of an API Gateway event:
42+
43+ === "APIGWHandler.java"
44+
45+ ```java hl_lines="1 6 9"
46+ import static software.amazon.lambda.powertools.utilities.EventDeserializer.extractDataFrom;
47+
48+ public class APIGWHandler implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
49+
50+ public APIGatewayProxyResponseEvent handleRequest(
51+ final APIGatewayProxyRequestEvent event,
52+ final Context context) {
53+
54+ Product product = extractDataFrom(event).as(Product.class);
55+
56+ }
57+ ```
58+
59+ === "Product.java"
60+
61+ ```java
62+ public class Product {
63+ private long id;
64+ private String name;
65+ private double price;
66+
67+ public Product() {
68+ }
69+
70+ public Product(long id, String name, double price) {
71+ this.id = id;
72+ this.name = name;
73+ this.price = price;
74+ }
75+
76+ public long getId() {
77+ return id;
78+ }
79+
80+ public void setId(long id) {
81+ this.id = id;
82+ }
83+
84+ public String getName() {
85+ return name;
86+ }
87+
88+ public void setName(String name) {
89+ this.name = name;
90+ }
91+
92+ public double getPrice() {
93+ return price;
94+ }
95+
96+ public void setPrice(double price) {
97+ this.price = price;
98+ }
99+ }
100+ ```
101+
102+ === "event"
103+
104+ ```json hl_lines="2"
105+ {
106+ "body": "{\"id\":1234, \"name\":\"product\", \"price\":42}",
107+ "resource": "/{proxy+}",
108+ "path": "/path/to/resource",
109+ "httpMethod": "POST",
110+ "isBase64Encoded": false,
111+ "queryStringParameters": {
112+ "foo": "bar"
113+ },
114+ "pathParameters": {
115+ "proxy": "/path/to/resource"
116+ },
117+ "stageVariables": {
118+ "baz": "qux"
119+ },
120+ "headers": {
121+ "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
122+ "Accept-Encoding": "gzip, deflate, sdch",
123+ "Accept-Language": "en-US,en;q=0.8",
124+ "Cache-Control": "max-age=0",
125+ "Host": "1234567890.execute-api.us-east-1.amazonaws.com",
126+ "Upgrade-Insecure-Requests": "1",
127+ "User-Agent": "Custom User Agent String",
128+ "Via": "1.1 08f323deadbeefa7af34d5feb414ce27.cloudfront.net (CloudFront)",
129+ "X-Amz-Cf-Id": "cDehVQoZnx43VYQb9j2-nvCh-9z396Uhbp027Y2JvkCPNLmGJHqlaA==",
130+ "X-Forwarded-For": "127.0.0.1, 127.0.0.2",
131+ "X-Forwarded-Port": "443",
132+ "X-Forwarded-Proto": "https"
133+ },
134+ "requestContext": {
135+ "accountId": "123456789012",
136+ "resourceId": "123456",
137+ "stage": "prod",
138+ "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
139+ "requestTime": "09/Apr/2015:12:34:56 +0000",
140+ "requestTimeEpoch": 1428582896000,
141+ "identity": {
142+ "cognitoIdentityPoolId": null,
143+ "accountId": null,
144+ "cognitoIdentityId": null,
145+ "caller": null,
146+ "accessKey": null,
147+ "sourceIp": "127.0.0.1",
148+ "cognitoAuthenticationType": null,
149+ "cognitoAuthenticationProvider": null,
150+ "userArn": null,
151+ "userAgent": "Custom User Agent String",
152+ "user": null
153+ },
154+ "path": "/prod/path/to/resource",
155+ "resourcePath": "/{proxy+}",
156+ "httpMethod": "POST",
157+ "apiId": "1234567890",
158+ "protocol": "HTTP/1.1"
159+ }
160+ }
161+ ```
162+
163+ It can also handle a collection of elements like the records of an SQS event:
164+
165+ === "SQSHandler.java"
166+
167+ ```java hl_lines="1 6 9"
168+ import static software.amazon.lambda.powertools.utilities.EventDeserializer.extractDataFrom;
169+
170+ public class SQSHandler implements RequestHandler<SQSEvent, String> {
171+
172+ public String handleRequest(
173+ final SQSEvent event,
174+ final Context context) {
175+
176+ List<Product> products = extractDataFrom(event).asListOf(Product.class);
177+
178+ }
179+ ```
180+
181+ === "event"
182+
183+ ```json hl_lines="6 23"
184+ {
185+ "Records": [
186+ {
187+ "messageId": "d9144555-9a4f-4ec3-99a0-34ce359b4b54",
188+ "receiptHandle": "13e7f7851d2eaa5c01f208ebadbf1e72==",
189+ "body": "{ \" id\" : 1234, \" name\" : \" product\" , \" price\" : 42}",
190+ "attributes": {
191+ "ApproximateReceiveCount": "1",
192+ "SentTimestamp": "1601975706495",
193+ "SenderId": "AROAIFU437PVZ5L2J53F5",
194+ "ApproximateFirstReceiveTimestamp": "1601975706499"
195+ },
196+ "messageAttributes": {
197+ },
198+ "md5OfBody": "13e7f7851d2eaa5c01f208ebadbf1e72",
199+ "eventSource": "aws: sqs ",
200+ "eventSourceARN": "arn:aws:sqs:eu-central-1:123456789012: TestLambda ",
201+ "awsRegion": "eu-central-1"
202+ },
203+ {
204+ "messageId": "d9144555-9a4f-4ec3-99a0-34ce359b4b54",
205+ "receiptHandle": "13e7f7851d2eaa5c01f208ebadbf1e72==",
206+ "body": "{ \" id\" : 12345, \" name\" : \" product5\" , \" price\" : 45}",
207+ "attributes": {
208+ "ApproximateReceiveCount": "1",
209+ "SentTimestamp": "1601975706495",
210+ "SenderId": "AROAIFU437PVZ5L2J53F5",
211+ "ApproximateFirstReceiveTimestamp": "1601975706499"
212+ },
213+ "messageAttributes": {
214+
215+ },
216+ "md5OfBody": "13e7f7851d2eaa5c01f208ebadbf1e72",
217+ "eventSource": "aws: sqs ",
218+ "eventSourceARN": "arn:aws:sqs:eu-central-1:123456789012: TestLambda ",
219+ "awsRegion": "eu-central-1"
220+ }
221+ ]
222+ }
223+ ```
224+
225+ !!! Tip
226+ In the background, ` EventDeserializer ` is using Jackson. The ` ObjectMapper ` is configured in ` JsonConfig ` . You can customize the configuration of the mapper if needed:
227+ ` JsonConfig.get().getObjectMapper() ` . Using this feature, you don't need to add Jackson to your project and create another instance of ` ObjectMapper ` .
228+
229+ ### Built-in events
230+
231+ | Event Type | Path to the content | List |
232+ | ---------------------------------------------------| -----------------------------------------------------------| ------|
233+ | ` APIGatewayProxyRequestEvent ` | ` body ` | |
234+ | ` APIGatewayV2HTTPEvent ` | ` body ` | |
235+ | ` SNSEvent ` | ` Records[0].Sns.Message ` | |
236+ | ` SQSEvent ` | ` Records[*].body ` | x |
237+ | ` ScheduledEvent ` | ` detail ` | |
238+ | ` ApplicationLoadBalancerRequestEvent ` | ` body ` | |
239+ | ` CloudWatchLogsEvent ` | ` powertools_base64_gzip(data) ` | |
240+ | ` CloudFormationCustomResourceEvent ` | ` resourceProperties ` | |
241+ | ` KinesisEvent ` | ` Records[*].kinesis.powertools_base64(data) ` | x |
242+ | ` KinesisFirehoseEvent ` | ` Records[*].powertools_base64(data) ` | x |
243+ | ` KafkaEvent ` | ` records[*].values[*].powertools_base64(value) ` | x |
244+ | ` ActiveMQEvent ` | ` messages[*].powertools_base64(data) ` | x |
245+ | ` RabbitMQEvent ` | ` rmqMessagesByQueue[*].values[*].powertools_base64(data) ` | x |
246+ | ` KinesisAnalyticsFirehoseInputPreprocessingEvent ` | ` Records[*].kinesis.powertools_base64(data) ` | x |
247+ | ` KinesisAnalyticsStreamsInputPreprocessingEvent ` | ` Records[*].kinesis.powertools_base64(data) ` | x |
248+
7249
8250## JMESPath functions
9251
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
0 commit comments