Set up data mapping for WebSocket APIs in API Gateway
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 AWS Management Console. You must use the AWS CLI, AWS 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.
The following table shows integration request data mapping expressions. In the table,
is the name
of a route request parameter of the given parameter type. It must match the regular
expression 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 | . The
STATIC_VALUE is a string literal and must
be enclosed in single quotes. |
Examples
The following AWS CLI examples configure data mappings. For an example AWS 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'