Transformación de las solicitudes y respuestas de API para las API HTTP en API Gateway - Amazon API Gateway
Transformación de solicitudes de APITransformación de respuestas de APIEncabezados reservadosEjemplos

Transformación de las solicitudes y respuestas de API para las API HTTP en API Gateway

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. La asignación de parámetros sirve para modificar las solicitudes y respuestas de API para las API HTTP. Para utilizar la asignación 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 una asignación de tipo 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.

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 asignar a los parámetros.

Tipo Sintaxis Notas
Valor del encabezado $request.header.name o ${request.header.name} Los nombres de 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 cadenas de consulta distinguen entre 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 asignar el parámetro petId de la solicitud a $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 una asignación de tipo 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.

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 asignar a los parámetros.

Tipo Sintaxis Notas
Valor del encabezado $response.header.name o ${response.header.name} Los nombres de 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 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 asignaciones 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 asignaciones de parámetros. Para obtener plantillas de AWS CloudFormation de ejemplo, consulte GitHub.

Adición de un encabezado a una solicitud de API

El siguiente comando create-integration permite crear 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" }'

Cambio de nombre de un encabezado de solicitud

El siguiente comando create-integration permite cambiar el nombre de encabezado de una 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": "''"}'

Cambio de la respuesta de una integración

El siguiente comando create-integration permite configurar los parámetros de respuesta de 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"}  }'

Eliminación de asignaciones de parámetros configuradas

El siguiente comando update-integration permite eliminar 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" : {}}'