Setting up data mapping for WebSocket APIs
Data mapping enables you to map data from a route request to a backend integration.
Note
Data mapping for WebSocket APIs isn't supported in the Amazon Web Services Management Console. You must use the Amazon CLI, Amazon CloudFormation, or an SDK to configure data mapping.
Map route request data to integration request parameters
Integration request parameters can be mapped from any defined route request parameters, the request body, context or stage variables, and static values.
In the following table, PARAM_NAME'^[a-zA-Z0-9._$-]+$]'.
JSONPath_EXPRESSION is a JSONPath expression for a JSON field of the request body.
Integration request data mapping expressions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Mapped data source | Mapping expression | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request query string (supported only for the $connect
route) |
route.request.querystring. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request header (supported only for the $connect
route) |
route.request.header. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Multi-value request query string (supported only for the
$connect route) |
route.request.multivaluequerystring. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Multi-value request header (supported only for the
$connect route) |
route.request.multivalueheader. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Request body | route.request.body. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Stage variables | stageVariables. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Context variables | context. that
must be one of the supported
context variables. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Static value | STATIC_VALUE is a string literal and must
be enclosed in single quotes. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Examples
The following Amazon CLI examples configure data mappings. For an example Amazon CloudFormation template,
see websocket-data-mapping.yaml.
Map a client's connectionId to a header in an integration request
The following example command maps a client's connectionId to a
connectionId header in the request to a backend integration.
aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId'
Map a query string parameter to a header in an integration request
The following example commands map an authToken query string
parameter to an authToken header in the integration request.
First, add the authToken query string parameter to the route's
request parameters.
aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}'
Next, map the query string parameter to the authToken header in the
request to the backend integration.
aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken'
If necessary, delete the authToken query string parameter from the route's request parameters.
aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken'