Skip to content

Commit 13e5269

Browse files
jeromevdljeromevdl
committed
documentation
1 parent 1c23738 commit 13e5269

File tree

1 file changed

+238
-1
lines changed

1 file changed

+238
-1
lines changed

‎docs/utilities/serialization.md

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

8245
## JMESPath functions
9246

0 commit comments

Comments
 (0)