# Transformación de las solicitudes y respuestas de API para las API HTTP en API Gateway
<a name="http-api-parameter-mapping"></a>

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
<a name="http-api-mapping-request-parameters"></a>

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\$1overwrite\$1remove:header.headername | 
| Cadena de consulta | append\$1overwrite\$1remove: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 | \$1request.header.name o \$1\$1request.header.name\$1 | 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](#http-api-mapping-reserved-headers). | 
| Valor de la cadena de consulta | \$1request.querystring.name o \$1\$1request.querystring.name\$1 | 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 | \$1request.body.name o \$1\$1request.body.name\$1 | Una expresión de ruta JSON. El descenso recursivo (\$1request.body..name) y las expresiones de filtro (?(expression)) no son compatibles.  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 | \$1request.path o \$1\$1request.path\$1 | La ruta de la solicitud, sin el nombre de la etapa. | 
| Parámetro de ruta | \$1request.path.name o \$1\$1request.path.name\$1 | El valor de un parámetro de ruta en la solicitud. Por ejemplo, si la ruta es /pets/\$1petId\$1, puede asignar el parámetro petId de la solicitud a \$1request.path.petId. | 
| Variable de contexto | \$1context.variableName o \$1\$1context.variableName\$1 | El valor de una [variable de contexto](http-api-logging-variables.md). Solo se admiten los caracteres especiales `.` y `_`. | 
| Variable de etapa | \$1stageVariables.variableName o \$1\$1stageVariables.variableName\$1 | El valor de una [variable de etapa](http-api-stages.stage-variables.md). | 
| 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
<a name="http-api-mapping-response-parameters"></a>

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\$1overwrite\$1remove: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 | \$1response.header.name o \$1\$1response.header.name\$1 | 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](#http-api-mapping-reserved-headers). | 
| Cuerpo de respuesta | \$1response.body.name o \$1\$1response.body.name\$1 | Una expresión de ruta JSON. El descenso recursivo (\$1response.body..name) y las expresiones de filtro (?(expression)) no son compatibles.  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 | \$1context.variableName o \$1\$1context.variableName\$1 | El valor de una [variable de contexto](http-api-logging-variables.md) compatible. | 
| Variable de etapa | \$1stageVariables.variableName o \$1\$1stageVariables.variableName\$1 | El valor de una [variable de etapa](http-api-stages.stage-variables.md). | 
| 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
<a name="http-api-mapping-reserved-headers"></a>

Los siguientes encabezados están reservados. No puede configurar asignaciones de solicitud o respuesta para estos encabezados.
+ access-control-\$1
+ apigw-\$1
+ 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-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via

## Ejemplos
<a name="http-api-parameter-mapping-examples"></a>

En los siguientes ejemplos de la AWS CLI, se configuran asignaciones de parámetros. Para obtener plantillas de CloudFormation de ejemplo, consulte [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates).

### Adición de un encabezado a una solicitud de API
<a name="http-api-parameter-mapping-examples-request-header"></a>

El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 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
<a name="http-api-parameter-mapping-examples-response"></a>

El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 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
<a name="http-api-parameter-mapping-examples-response"></a>

El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 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 `header1`1 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
<a name="http-api-parameter-mapping-examples-remove"></a>

El siguiente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 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" : {}}'
```