Set up data mapping for WebSocket APIs in API Gateway - Amazon API Gateway
Map route request data to integration request parametersExamples

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, PARAM_NAME is the name of a route request parameter of the given parameter type. It must match the regular expression '^[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.PARAM_NAME
Request header (supported only for the $connect route) route.request.header.PARAM_NAME
Multi-value request query string (supported only for the $connect route) route.request.multivaluequerystring.PARAM_NAME
Multi-value request header (supported only for the $connect route) route.request.multivalueheader.PARAM_NAME
Request body route.request.body.JSONPath_EXPRESSION
Stage variables stageVariables.VARIABLE_NAME
Context variables context.VARIABLE_NAME that must be one of the supported context variables.
Static value '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'