Transformación de solicitudes y respuestas de API

Puede modificar las solicitudes API de los clientes antes de que lleguen a sus integraciones de backend. También puede cambiar la respuesta de las integraciones antes de que API Gateway devuelva la respuesta a los clientes. Utilice el mapeo de parámetros para modificar las solicitudes y respuestas de API para API HTTP. Para utilizar el mapeo de parámetros, especifique los parámetros de solicitud o respuesta de API que se van a modificar e indique cómo modificarlos.

Transformación de solicitudes de API

Los parámetros de solicitud se utilizan para cambiar las solicitudes antes de que lleguen a sus integraciones de backend. Puede modificar encabezados, cadenas de consulta o la ruta de la solicitud.

Los parámetros de solicitud son un mapa de valor-clave. La clave identifica la ubicación del parámetro de solicitud que se va a cambiar y cómo cambiarlo. El valor especifica los datos nuevos para el parámetro.

En la siguiente tabla se muestran las claves admitidas.

Claves del mapeo de parámetros
Tipo	Sintaxis
Encabezado	append|overwrite|remove:header.headername
Cadena de consulta	append|overwrite|remove:querystring.querystring-name
Ruta	overwrite:path

En la siguiente tabla se muestran los valores admitidos que se pueden mapear a los parámetros.

Valores del mapeo de parámetros de solicitud
Tipo	Sintaxis	Notas
Valor del encabezado	$request.header.name o ${request.header.name}	Los nombres del encabezado no distinguen entre mayúsculas y minúsculas. API Gateway combina varios valores de encabezado con comas, por ejemplo, "header1": "value1,value2". Algunos encabezados están reservados. Para obtener más información, consulte Encabezados reservados.
Valor de la cadena de consulta	$request.querystring.name o ${request.querystring.name}	Los nombres de las cadenas de consulta distinguen mayúsculas y minúsculas. API Gateway combina varios valores con comas, por ejemplo, "querystring1" "Value1,Value2".
Cuerpo de la solicitud	$request.body.name o ${request.body.name}	Una expresión de ruta JSON. El descenso recursivo ($request.body..name) y las expresiones de filtro (?(expression)) no son compatibles. nota Cuando se especifica una ruta JSON, API Gateway trunca el cuerpo de la solicitud en 100 KB y, a continuación, aplica la expresión de selección. Para enviar cargas de más de 100 KB, especifique $request.body.
Ruta de solicitud	$request.path o ${request.path}	La ruta de la solicitud, sin el nombre de la etapa.
Parámetro de ruta	$request.path.name o ${request.path.name}	El valor de un parámetro de ruta en la solicitud. Por ejemplo, si la ruta es /pets/{petId}, puede mapear el parámetro petId de la solicitud con $request.path.petId.
Variable de contexto	$context.variableName o ${context.variableName}	El valor de una variable de contexto. nota Solo se admiten los caracteres especiales . y _.
Variable de etapa	$stageVariables.variableName o ${stageVariables.variableName}	El valor de una variable de etapa.
Valor estático	string	Un valor constante.

nota

Para utilizar distintas variables en una expresión de selección, incluya la variable entre corchetes. Por ejemplo, ${request.path.name} ${request.path.id}.

Transformación de respuestas de API

Los parámetros de respuesta se utilizan para transformar la respuesta HTTP de una integración de backend antes de devolver la respuesta a los clientes. Puede modificar los encabezados o el código de estado de una respuesta antes de que API Gateway devuelva la respuesta a los clientes.

Los parámetros de respuesta se configuran para cada código de estado que devuelve la integración. Los parámetros de respuesta son un mapa de valor-clave. La clave identifica la ubicación del parámetro de solicitud que se va a cambiar y cómo cambiarlo. El valor especifica los datos nuevos para el parámetro.

En la siguiente tabla se muestran las claves admitidas.

Claves del mapeo de parámetros de respuesta
Tipo	Sintaxis
Encabezado	append|overwrite|remove:header.headername
Código de estado	overwrite:statuscode

En la siguiente tabla se muestran los valores admitidos que se pueden mapear a los parámetros.

Valores del mapeo de parámetros de respuesta
Tipo	Sintaxis	Notas
Valor del encabezado	$response.header.name o ${response.header.name}	Los nombres del encabezado no distinguen entre mayúsculas y minúsculas. API Gateway combina varios valores de encabezado con comas, por ejemplo, "header1": "value1,value2". Algunos encabezados están reservados. Para obtener más información, consulte Encabezados reservados.
Cuerpo de respuesta	$response.body.name o ${response.body.name}	Una expresión de ruta de acceso JSON. El descenso recursivo ($response.body..name) y las expresiones de filtro (?(expression)) no son compatibles. nota Cuando se especifica una ruta JSON, API Gateway trunca el cuerpo de la respuesta en 100 KB y, a continuación, aplica la expresión de selección. Para enviar cargas de más de 100 KB, especifique $response.body.
Variable de contexto	$context.variableName o ${context.variableName}	El valor de una variable de contexto compatible.
Variable de etapa	$stageVariables.variableName o ${stageVariables.variableName}	El valor de una variable de etapa.
Valor estático	string	Un valor constante.

nota

Para utilizar distintas variables en una expresión de selección, incluya la variable entre corchetes. Por ejemplo, ${request.path.name} ${request.path.id}.

Encabezados reservados

Los siguientes encabezados están reservados. No puede configurar mapeos de solicitud o respuesta para estos encabezados.

• access-control-*

• apigw-*

• Autorización

• Conexión

• Content-Encoding

• Longitud del contenido

• Content-Location

• Forwarded

• Keep-Alive

• Origen

• Proxy-Authenticate

• Proxy-Authorization

• TE

• Trailers

• Transfer-Encoding

• Upgrade

• x-amz-*

• x-amzn-*

• X-Forwarded-For

• X-Forwarded-Host

• X-Forwarded-Proto

• Via

Ejemplos

En los siguientes ejemplos de la AWS CLI, se configuran mapeos de parámetros. Para obtener plantillas de AWS CloudFormation de ejemplo, consulte GitHub.

Agregar un encabezado a una solicitud de API

En el siguiente ejemplo se agrega un encabezado denominado header1 a una solicitud de API antes de que llegue a su integración de backend. API Gateway rellena el encabezado con el ID de solicitud.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header1": "$context.requestId" }' 

Cambiar el nombre de un encabezado de solicitud

En el ejemplo siguiente se cambia el nombre de un encabezado de solicitud de header1 a header2.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header2": "$request.header.header1",  "remove:header.header1": "''"}'

Cambiar la respuesta de una integración

En el siguiente ejemplo se configuran los parámetros de respuesta para una integración. Cuando las integraciones devuelven un código de estado 500, API Gateway cambia el código de estado a 403 y agrega header11 a la respuesta. Cuando la integración devuelve un código de estado 404, API Gateway agrega un error encabezado a la respuesta.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"}  }'

Eliminar mapeos de parámetros configurados

El siguiente comando de ejemplo elimina los parámetros de solicitud configurados previamente para append:header.header1. También elimina los parámetros de respuesta configurados previamente para un código de estado 200.

aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'