# Transformaciones de datos para las API de REST en API Gateway
**nota**
En esta sección se explican las características que se utilizan con una integración sin proxy. No obstante, recomendamos que, siempre que sea posible, utilice una integración de proxy para la API de REST. Una integración de proxy HTTP tiene una configuración de integración simplificada y puede evolucionar con el backend sin tener que eliminar la configuración existente. Para obtener más información, consulte [Elegir un tipo de integración de API de API Gateway](api-gateway-api-integration-types.md).
Si utiliza una integración sin proxy, puede utilizar dos características de API Gateway para transformar la solicitud de método y la respuesta de integración. Podría transformar la solicitud de método si esta tiene un formato de carga útil diferente al de la carga útil de la solicitud de integración. Podría transformar la respuesta de integración si devuelve un formato de carga útil diferente al formato que necesita devolver en la respuesta del método. Para obtener más información sobre el ciclo de vida de la solicitud, consulte [Recurso de ejemplo para una API de REST](rest-api-develop.md#rest-api-develop-example).
En el siguiente ejemplo se muestra una transformación de datos en la que, para el encabezado `"x-version:beta"`, el parámetro de encabezado `x-version` se transforma en el parámetro de encabezado `app-version`. La transformación de datos de `x-version` a `app-version` se produce en la solicitud de integración. De esta manera, el punto de conexión de integración recibe el valor del parámetro de encabezado transformado. Cuando el punto de conexión de integración devuelve un código de estado, este se transforma de `200` a `204` antes de la respuesta de método.
![\[Diagrama de transformación de datos de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/develop-non-proxy.png)
Para crear una transformación de datos, puede utilizar las siguientes características:
**Asignación de parámetros**
En la asignación de parámetros, puede modificar los parámetros de ruta de URL de solicitud de integración, los parámetros de cadena de consulta de URL o los valores de encabezado HTTP, pero no puede modificar la carga útil de solicitud de integración. También puede modificar los valores de encabezado de respuesta HTTP. Utilice la asignación de parámetros para crear valores de encabezado estáticos para el uso compartido de recursos entre orígenes (CORS).
Puede usar la asignación de parámetros en la solicitud de integración para integraciones de proxy y de no proxy, pero para usar la asignación de parámetros para una respuesta de integración, necesita una integración de no proxy. La asignación de parámetros no requiere ningún script en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Para obtener más información, consulte [Asignación de parámetros para las API de REST en API Gateway](rest-api-parameter-mapping.md).
**Transformaciones de plantillas de asignación**
En las transformaciones de plantillas de asignación, se utiliza una plantilla de asignación para asignar parámetros de ruta de URL, parámetros de cadena de consulta de URL, encabezados HTTP y el cuerpo de solicitud de integración o de respuesta de integración. Una *plantilla de asignación* es un script expresado en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) mediante [expresiones JSONPath](https://goessner.net/articles/JsonPath/) y aplicado a la carga útil en función del encabezado `Content-type`.
Con una plantilla de asignación, puede hacer lo siguiente:
+ Seleccionar los datos que desee enviar mediante la integración con Servicios de AWS, como las funciones de Amazon DynamoDB o de Lambda o los puntos de conexión HTTP. Para obtener más información, consulte [Tutorial: modificación de la solicitud y respuesta de integración para integraciones con servicios de AWS](set-up-data-transformations-in-api-gateway.md).
+ Anular condicionalmente los parámetros de solicitud de integración y de respuesta de integración de una API, crear nuevos valores de encabezado y anular códigos de estado. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md).
También puede especificar el comportamiento de la API cuando el cuerpo de una solicitud de integración tenga un encabezado `Content-type` sin plantillas de asignación que coincidan. Esto se denomina comportamiento de acceso directo a la integración. Para obtener más información, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md).
## Elección entre la asignación de parámetros y las transformaciones de plantillas de asignación
Le recomendamos que utilice la asignación de parámetros para transformar los datos siempre que sea posible. Si la API requiere que cambie el cuerpo o que realice modificaciones y anulaciones condicionales basadas en la solicitud de integración entrante o en la respuesta de integración y no puede utilizar una integración de proxy, utilice las transformaciones de plantillas de asignación.
# Asignación de parámetros para las API de REST en API Gateway
**nota**
Si utiliza una API de HTTP, consulte [Transformación de las solicitudes y respuestas de API para las API HTTP en API Gateway](http-api-parameter-mapping.md).
En la asignación de parámetros, asigne parámetros de solicitud o de respuesta. Puede asignar parámetros mediante expresiones de asignación de parámetros o valores estáticos. Para obtener una lista de expresiones de asignación, consulte [Referencia de origen de asignación de parámetros para las API de REST en API Gateway](rest-api-parameter-mapping-sources.md). Puede usar la asignación de parámetros en la solicitud de integración para integraciones de proxy y de no proxy, pero para usar la asignación de parámetros para una respuesta de integración, necesita una integración de no proxy.
Por ejemplo, puede asignar el parámetro de encabezado de solicitud de método `puppies` al parámetro de encabezado de solicitud de integración `DogsAge0`. A continuación, si un cliente envía el encabezado `puppies:true` a la API, la solicitud de integración envía el encabezado de solicitud `DogsAge0:true` al punto de conexión de integración. En el siguiente diagrama se muestra el ciclo de vida de la solicitud de este ejemplo.
![\[Diagrama del ejemplo de asignación de parámetros de API Gateway para una solicitud\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
Para crear este ejemplo con API Gateway, consulte [Ejemplo 1: asignar un parámetro de solicitud de método a un parámetro de solicitud de integración](request-response-data-mappings.md#request-response-data-mappings-example-1).
Como otro ejemplo, también puede asignar el parámetro de encabezado de respuesta de integración `kittens` al parámetro de encabezado de respuesta de método `CatsAge0`. Si el punto de conexión de integración devuelve `kittens:false`, el cliente recibe el encabezado `CatsAge0:false`. En el siguiente diagrama se muestra el ciclo de vida de la solicitud de este ejemplo.
![\[Diagrama del ejemplo de asignación de parámetros de API Gateway para una respuesta\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [Ejemplos de asignación de parámetros para las API de REST en API Gateway](request-response-data-mappings.md)
+ [Referencia de origen de asignación de parámetros para las API de REST en API Gateway](rest-api-parameter-mapping-sources.md)
# Ejemplos de asignación de parámetros para las API de REST en API Gateway
En los siguientes ejemplos se muestra cómo crear expresiones de asignación de parámetros mediante la consola de API Gateway, OpenAPI y plantillas de CloudFormation. Para ver un ejemplo de cómo utilizar la asignación de parámetros para crear los encabezados CORS necesarios, consulte [CORS para las API de REST en API Gateway](how-to-cors.md).
## Ejemplo 1: asignar un parámetro de solicitud de método a un parámetro de solicitud de integración
En el siguiente ejemplo se asigna el parámetro de encabezado de solicitud de método `puppies` al parámetro de encabezado de solicitud de integración `DogsAge0`.
------
#### [ Consola de administración de AWS ]
**Asignación del parámetro de solicitud de método**
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija una API de REST.
1. Elija un método.
El método debe tener una integración sin proxy.
1. En **Configuración de solicitud de método**, elija **Editar**.
1. Elija **Encabezados de solicitud HTTP**.
1. Elija **Agregar encabezado**.
1. En **Nombre**, escriba **puppies**.
1. Seleccione **Save**.
1. Elija la pestaña **Solicitud de integración** y, a continuación, en **Configuración de solicitud de integración**, elija **Editar**.
La Consola de administración de AWS agrega automáticamente una asignación de parámetros de `method.request.header.puppies ` a `puppies` por usted, pero debe cambiar el **Nombre** para que coincida con el parámetro de encabezado de solicitud que espera el punto de conexión de integración.
1. En **Nombre**, escriba **DogsAge0**.
1. Seleccione **Save**.
1. Vuelva a implementar la API para que los cambios se apliquen.
En los siguientes pasos se muestra cómo verificar que la asignación de parámetros se ha realizado correctamente.
**(Opcional) Prueba de la asignación de parámetros**
1. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
1. Para los encabezados, introduzca **puppies:true**.
1. Seleccione **Probar**
1. En **Registros**, el resultado debería tener el siguiente aspecto:
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
El parámetro de encabezado de solicitud ha cambiado de `puppies` a `DogsAge0`.
------
#### [ CloudFormation ]
En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## Ejemplo 2: asignar varios parámetros de solicitud de método a diferentes parámetros de solicitud de integración
En el siguiente ejemplo, se asigna el parámetro de cadena de consulta de solicitud de método de varios valores `methodRequestQueryParam` al parámetro de cadena de consulta de solicitud de integración `integrationQueryParam` y se asigna el parámetro de encabezado de solicitud de método `methodRequestHeaderParam` al parámetro de ruta de solicitud de integración `integrationPathParam`.
------
#### [ Consola de administración de AWS ]
**Asignación de los parámetros de solicitud de método**
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija una API de REST.
1. Elija un método.
El método debe tener una integración sin proxy.
1. En **Configuración de solicitud de método**, elija **Editar**.
1. Elija **Parámetros de cadenas de consulta de URL**.
1. Elija **Añadir cadena de consulta**.
1. En **Nombre**, escriba **methodRequestQueryParam**.
1. Elija **Encabezados de solicitud HTTP**.
1. Elija **Agregar encabezado**.
1. En **Nombre**, escriba **methodRequestHeaderParam**.
1. Seleccione **Save**.
1. Elija la pestaña **Solicitud de integración** y, a continuación, en **Configuración de solicitud de integración**, elija **Editar**.
1. Elija los **Parámetros de la ruta URL**.
1. Elija **Añadir parámetro de ruta**.
1. En **Nombre**, escriba **integrationPathParam**.
1. En **Asignado desde**, introduzca **method.request.header.methodRequestHeaderParam**.
Esto asigna el encabezado de solicitud de método que especificó en la solicitud de método a un nuevo parámetro de ruta de solicitud de integración.
1. Elija **Parámetros de cadenas de consulta de URL**.
1. Elija **Añadir cadena de consulta**.
1. En **Nombre**, escriba **integrationQueryParam**.
1. En **Asignado desde**, introduzca **method.request.multivaluequerystring.methodRequestQueryParam**.
Esto asigna el parámetro de cadena de consulta de varios valores a un nuevo parámetro de cadena de consulta de solicitud de integración de valor único.
1. Seleccione **Save**.
1. Vuelva a implementar la API para que los cambios se apliquen.
------
#### [ CloudFormation ]
En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway.
La siguiente definición de OpenAPI crea las siguientes asignaciones de parámetros para una integración de HTTP:
+ El encabezado de la solicitud de método, llamado `methodRequestHeaderParam`, al parámetro de ruta de la solicitud de integración, llamado `integrationPathParam`
+ La cadena de consulta de la solicitud de método de varios valores, llamada `methodRequestQueryParam`, a la cadena de consulta de la solicitud de integración, llamada `integrationQueryParam`
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La siguiente definición de OpenAPI crea las siguientes asignaciones de parámetros para una integración de HTTP:
+ El encabezado de la solicitud de método, llamado `methodRequestHeaderParam`, al parámetro de ruta de la solicitud de integración, llamado `integrationPathParam`
+ La cadena de consulta de la solicitud de método de varios valores, llamada `methodRequestQueryParam`, a la cadena de consulta de la solicitud de integración, llamada `integrationQueryParam`
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Ejemplo 3: asignar campos del cuerpo de la solicitud JSON a los parámetros de la solicitud de integración
También puede asignar parámetros de solicitud de integración desde campos del cuerpo de la solicitud JSON mediante una [expresión JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). El siguiente ejemplo asigna el cuerpo de solicitud de método a un encabezado de solicitud de integración denominado `body-header` y asigna parte del cuerpo de solicitud, expresado mediante una expresión JSON, a un encabezado de solicitud de integración denominado `pet-price`.
Para probar este ejemplo, proporcione una entrada que contenga una categoría de precio, como la siguiente:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ Consola de administración de AWS ]
**Asignación de los parámetros de solicitud de método**
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija una API de REST.
1. Elija un método `POST`, `PUT`, `PATCH` o `ANY`.
El método debe tener una integración sin proxy.
1. En **Configuración de solicitud de integración**, elija **Editar**.
1. Elija **Parámetros de encabezado de solicitud de URL**.
1. Elija **Agregar parámetro de encabezado de solicitud**.
1. En **Nombre**, escriba **body-header**.
1. En **Asignado desde**, introduzca **method.request.body**.
Esto asigna el cuerpo de solicitud de método a un nuevo parámetro de encabezado de solicitud de integración.
1. Elija **Agregar parámetro de encabezado de solicitud**.
1. En **Nombre**, escriba **pet-price**.
1. En **Asignado desde**, introduzca ** method.request.body[0].price**.
Esto asigna una parte del cuerpo de solicitud de método a un nuevo parámetro de encabezado de solicitud de integración.
1. Seleccione **Save**.
1. Vuelva a implementar la API para que los cambios se apliquen.
------
#### [ CloudFormation ]
En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La siguiente definición de OpenAPI asigna los parámetros de solicitud de integración de los campos del cuerpo de solicitud JSON.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Ejemplo 4: asignar la respuesta de integración a la respuesta de método
También puede asignar la respuesta de integración a la respuesta de método. En el siguiente ejemplo se asigna el cuerpo de respuesta de integración a un encabezado de respuesta de método denominado `location`, se asigna el encabezado de respuesta de integración `x-app-id` al encabezado de respuesta de método `id` y se asigna el encabezado de respuesta de integración de varios valores `item` al encabezado de respuesta de método `items`.
------
#### [ Consola de administración de AWS ]
**Asignación de la respuesta de integración**
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija una API de REST.
1. Elija un método.
El método debe tener una integración sin proxy.
1. Elija la pestaña **Respuesta de método** y, a continuación, para **Respuesta 200**, elija **Editar**.
1. En **Nombre de encabezado**, elija **Agregar encabezado**.
1. Cree tres encabezados llamados **id**, **item** y **location**.
1. Seleccione **Save**.
1. Elija la pestaña **Respuesta de integración** y, a continuación, en **Predeterminado: respuesta**, elija **Editar**.
1. En **Asignaciones de encabezado**, introduzca lo siguiente.
1. En **id**, introduzca **integration.response.header.x-app-id**
1. En **item**, introduzca **integration.response.multivalueheader.item**
1. En **location**, introduzca **integration.response.body.redirect.url**
1. Seleccione **Save**.
1. Vuelva a implementar la API para que los cambios se apliquen.
------
#### [ CloudFormation ]
En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La siguiente definición de OpenAPI asigna la respuesta de integración a la respuesta de método.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# Referencia de origen de asignación de parámetros para las API de REST en API Gateway
Cuando crea una asignación de parámetro, especifica los parámetros de solicitud de método o de respuesta de integración que desea modificar y especifica cómo modificarlos.
En la siguiente tabla se muestran los parámetros de solicitud de método que puede asignar y la expresión para crear la asignación. En estas expresiones, *name* es el nombre de un parámetro de solicitud de método. Por ejemplo, para asignar el parámetro de encabezado de solicitud `puppies`, utilice la expresión `method.request.header.puppies`. La expresión debe coincidir con la expresión regular `'^[a-zA-Z0-9._$-]+$]'`. Puede utilizar la asignación de parámetros en la solicitud de integración para integraciones de proxy y de no proxy.
| **Origen de datos asignado** | **Expresión de asignación** |
| --- | --- |
| Ruta de solicitud de método | method.request.path.name |
| Cadena de consulta de solicitud de método | method.request.querystring.name |
| Cadena de consulta de solicitud de método multivalor | method.request.multivaluequerystring.name |
| Encabezado de solicitud de método | method.request.header.name |
| Encabezado de solicitud de método multivalor | method.request.multivalueheader.name |
| Cuerpo de solicitud de método | method.request.body |
| Cuerpo de solicitud de método (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* es una expresión JSONPath para un campo JSON del cuerpo de una solicitud. Para obtener más información, consulte [Expresión JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variables de etapa | stageVariables.name |
| Variables de contexto | `context.name` El nombre debe ser una de las [variables de contexto admitidas](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valor estático | `'static_value'`. El valor de *static\$1value* es un literal de cadena que se debe incluir entre comillas simples. Por ejemplo, `'https://www.example.com'`. |
En la siguiente tabla se muestran los parámetros de respuesta de integración que puede asignar y la expresión para crear la asignación. En estas expresiones, *name* es el nombre de un parámetro de respuesta de integración. Puede asignar encabezados de respuesta de método desde cualquier encabezado de respuesta de integración o cuerpo de respuesta de integración, variables de contexto o valores estáticos. Para utilizar la asignación de parámetros para una respuesta de integración, necesita una integración de no proxy.
| Origen de datos asignado | Expresión de asignación |
| --- | --- |
| Encabezado de respuesta de integración | integration.response.header.name |
| Encabezado de respuesta de integración | integration.response.multivalueheader.name |
| Cuerpo de respuesta de integración | integration.response.body |
| Cuerpo de respuesta de integración (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* es una expresión JSONPath para un campo JSON del cuerpo de una respuesta. Para obtener más información, consulte [Expresión JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variable de etapa | stageVariables.name |
| Variable de contexto | `context.name` El nombre debe ser una de las [variables de contexto admitidas](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valor estático | ` 'static_value'` El valor de *static\$1value* es un literal de cadena que se debe incluir entre comillas simples. Por ejemplo, `'https://www.example.com'`. |
# Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway
Las transformaciones de plantillas de asignación utilizan una plantilla de asignación para modificar la solicitud de integración o respuesta de integración. Una *plantilla de asignación* es un script expresado en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) y aplicado a una carga útil mediante [JSONPath](https://goessner.net/articles/JsonPath/) basado en el encabezado `Content-type`. Utiliza plantillas de asignación cuando utiliza las transformaciones de plantillas de asignación. En esta sección se describe la información conceptual relacionada con las plantillas de asignación.
En el siguiente diagrama se muestra el ciclo de vida de la solicitud de un recurso `POST /pets` que tiene una integración con un punto de conexión de integración de PetStore. En esta API, un usuario envía datos sobre una mascota y el punto de conexión de integración devuelve la tarifa de adopción asociada a una mascota. En este ciclo de vida de la solicitud, las transformaciones de plantillas de asignación filtran el cuerpo de la solicitud al punto de conexión de integración y filtran el cuerpo de la respuesta desde el punto de conexión de integración.
![\[Ciclo de vida de solicitud de ejemplo\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/mapping-template-transforms.png)
En esta sección se explica el ciclo de vida de la solicitud y la respuesta.
## Solicitud de método y solicitud de integración
En el ejemplo anterior, si este es el cuerpo de solicitud enviado al método de solicitud:
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
Este cuerpo de solicitud no tiene el formato correcto para que lo utilice el punto de conexión de integración, por lo que API Gateway realiza las transformaciones de plantilla de asignación. API Gateway solo realiza las transformaciones de plantilla de asignación porque hay una plantilla de asignación definida para Content-Type `application/json`. Si no define una plantilla de asignación para Content-Type, de forma predeterminada, API Gateway pasa el cuerpo a través de la solicitud de integración al punto de conexión de integración. Para modificar este comportamiento, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md).
La siguiente plantilla de asignación transforma los datos de solicitud de método en la solicitud de integración antes de que se envíen al punto de conexión de integración:
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. La variable `$inputRoot` representa el objeto raíz en los datos JSON originales de la sección anterior. Las directivas comienzan con el símbolo `#`.
1. El valor `dog` es una concatenación del `id` del usuario y un valor de cadena.
1. `Age` es del cuerpo de solicitud de método.
A continuación, se reenvía el siguiente resultado al punto de conexión de integración:
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## Respuesta de integración y respuesta de método
Después de que la solicitud se haya enviado correctamente al punto de conexión de integración, el punto de conexión envía una respuesta a la respuesta de integración de API Gateway. A continuación, se muestran los datos de salida de ejemplo del punto de conexión de integración:
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
La respuesta de método espera una carga útil diferente a la que devuelve la respuesta de integración. API Gateway realiza las transformaciones de plantillas de asignación. API Gateway solo realiza las transformaciones de plantilla de asignación porque hay una plantilla de asignación definida para Content-Type `application/json`. Si no define una plantilla de asignación para Content-Type, de forma predeterminada, API Gateway pasa el cuerpo a través de la respuesta de integración a la respuesta de método. Para modificar este comportamiento, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md).
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
El siguiente resultado se envía a la respuesta del método:
```
{"adoptionFee": 19.95}
```
Esto completa el ejemplo de transformación de plantilla de asignación. Recomendamos que, cuando sea posible, en lugar de utilizar las transformaciones de plantilla de asignación, utilice una integración de proxy para transformar los datos. Para obtener más información, consulte [Elegir un tipo de integración de API de API Gateway](api-gateway-api-integration-types.md).
# Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway
Si la solicitud de método tiene una carga útil y no tiene una plantilla de asignación definida para el encabezado `Content-Type`, puede elegir pasar la carga útil de la solicitud suministrada por el cliente a través de la solicitud de integración al backend sin transformación. Este proceso se denomina "acceso directo a la integración".
El comportamiento de acceso directo real de una solicitud entrante viene determinado por esta configuración. Hay tres opciones:
**Cuando ninguna plantilla coincide con el encabezado Tipo de contenido solicitado**
Elija esta opción si desea que el cuerpo de la solicitud de método se transmita a través de la solicitud de integración al backend sin transformación cuando el tipo de contenido de la solicitud de método no coincida con ningún tipo de contenido asociado a las plantillas de mapeo.
Al llamar a la API de API Gateway, se elige esta opción estableciendo `WHEN_NO_MATCH` como el valor de la propiedad `passthroughBehavior` en [Integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Cuando no hay plantillas definidas (recomendado)**
Elija esta opción si desea que el cuerpo de la solicitud de método se transmita a través de la solicitud de integración al backend sin transformación cuando no se haya definido ninguna plantilla de mapeo en la solicitud de integración. Si se define una plantilla cuando se selecciona esta opción, la solicitud de método con una carga útil y un tipo de contenido que no coincida con ninguna plantilla de asignación definida se rechazará con una respuesta HTTP 415 Tipo de medio no admitido.
Al llamar a la API de API Gateway, se elige esta opción estableciendo `WHEN_NO_TEMPLATES` como el valor de la propiedad `passthroughBehavior` en [Integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Nunca**
Elija esta opción si no desea que el cuerpo de la solicitud de método se transmita a través de la solicitud de integración al backend sin transformación cuando no se haya definido ninguna plantilla de mapeo en la solicitud de integración. Si se define una plantilla cuando esta opción está seleccionada, la solicitud de método de un tipo de contenido sin asignar se rechazará con una respuesta HTTP 415 Unsupported Media Type.
Al llamar a la API de API Gateway, se elige esta opción estableciendo `NEVER` como el valor de la propiedad `passthroughBehavior` en [Integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
Los siguientes ejemplos muestran los posibles comportamientos del acceso directo.
Ejemplo 1: Se define una plantilla de asignación en la solicitud de integración para el tipo de contenido `application/json`.
| content-type | Opción de acceso directo | Comportamiento |
| --- | --- | --- |
| Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1MATCH | La carga de solicitud se transforma mediante la plantilla. |
| Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1TEMPLATES | La carga de solicitud se transforma mediante la plantilla. |
| Ninguno El valor predeterminado de API Gateway es `application/json` | NEVER | La carga de solicitud se transforma mediante la plantilla. |
| application/json | WHEN\$1NO\$1MATCH | La carga de solicitud se transforma mediante la plantilla. |
| application/json | WHEN\$1NO\$1TEMPLATES | La carga de solicitud se transforma mediante la plantilla. |
| application/json | NEVER | La carga de solicitud se transforma mediante la plantilla. |
| application/xml | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
| application/xml | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
Ejemplo 2: Se define una plantilla de asignación en la solicitud de integración para el tipo de contenido `application/xml`.
| Content-type | Opción de acceso directo | Comportamiento |
| --- | --- | --- |
| Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. |
| Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1TEMPLATES | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
| Ninguno El valor predeterminado de API Gateway es `application/json` | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. |
| application/json | WHEN\$1NO\$1TEMPLATES | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
| application/json | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | La carga de solicitud se transforma mediante la plantilla. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La carga de solicitud se transforma mediante la plantilla. |
| application/xml | NEVER | La carga de solicitud se transforma mediante la plantilla. |
Ejemplo 3: no se han definido plantillas de asignación en la solicitud de integración.
| Content-type | Opción de acceso directo | Comportamiento |
| --- | --- | --- |
| Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. |
| Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1TEMPLATES | La carga de solicitud no se transforma y se envía al backend tal como está. |
| Ninguno El valor predeterminado de API Gateway es `application/json` | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. |
| application/json | WHEN\$1NO\$1TEMPLATES | La carga de solicitud no se transforma y se envía al backend tal como está. |
| application/json | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La carga de solicitud no se transforma y se envía al backend tal como está. |
| application/xml | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. |
# Ejemplo de plantilla de asignación adicional para las API de REST en API Gateway
En el siguiente ejemplo se muestra una API de álbum de fotos en API Gateway que utiliza plantillas de asignación para transformar los datos de solicitud de integración y respuesta de integración. También utiliza modelos de datos para definir la carga útil de las solicitudes de métodos y las respuestas de integración. Para obtener más información acerca de los modelos de datos, consulte [Modelos de datos para las API de REST](models-mappings-models.md).
## Solicitud de método y solicitud de integración
A continuación se muestra un modelo que define el cuerpo de solicitud de método. Este modelo de entrada requiere que el intermediario cargue una página de fotos y un mínimo de 10 fotos por cada página. Puede utilizar este modelo de entrada para generar un SDK o para utilizar la validación de solicitudes para la API. Durante la validación de la solicitud, si el cuerpo de solicitud de método no se adhiere a la estructura de datos del modelo, API Gateway rechaza la solicitud.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
A continuación, se muestra un ejemplo de cuerpo de solicitud de método que se adhiere a la estructura de datos del modelo de datos anterior.
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
En este ejemplo, si el cliente ha enviado el cuerpo de solicitud de método anterior, esta plantilla de asignación transforma la carga útil para que coincida con el formato requerido por el punto de conexión de integración.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
En el siguiente ejemplo se muestran los datos de salida de la transformación:
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Estos datos se envían a la solicitud de integración y, a continuación, al punto de conexión de integración.
## Respuesta de integración y respuesta de método
A continuación, se muestra un modelo de salida de ejemplo para los datos fotográficos del punto de conexión de integración. Puede usar este modelo como modelo de respuesta de método, que es necesario al generar un SDK con establecimiento inflexible de tipos para la API. Esto provoca que el resultado se traduzca a una clase apropiada en Java u Objective-C.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
El punto de conexión de integración podría no responder con una respuesta que se adhiera a la estructura de datos de este modelo. Por ejemplo, la respuesta de integración podría tener el siguiente aspecto:
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
El siguiente ejemplo de plantilla de asignación transforma los datos de respuesta de integración al formato esperado por la respuesta de método:
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
En el siguiente ejemplo se muestran los datos de salida de la transformación:
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Estos datos se envían a la respuesta del método y luego se devuelven al cliente.
# Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway
Puede utilizar las transformaciones de plantilla de asignación para anular cualquier tipo de parámetro de solicitud, encabezado de respuesta o código de estado de respuesta. Utiliza una plantilla de asignación para hacer lo siguiente:
+ Realizar asignaciones de parámetros muchos a uno
+ Anular parámetros una vez aplicadas las asignaciones de API Gateway estándar
+ Asignar parámetros condicionalmente en función del contenido del cuerpo u otros valores de parámetro
+ Crear nuevos parámetros mediante programación
+ Anular los códigos de estado devueltos por el punto de conexión de integración
Las invalidaciones son definitivas. Una invalidación solo puede aplicarse a cada parámetro una vez. Si intenta anular el mismo parámetro varias veces, API Gateway devuelve una respuesta `5XX`. Si tiene que invalidar el mismo parámetro varias veces en la plantilla, le recomendamos crear una variable y aplicar la invalidación al final de la plantilla. La plantilla solo se aplica una vez analizada en su totalidad.
## Ejemplo 1: anular el código de estado en función del cuerpo de integración
En el siguiente ejemplo se utiliza la [API de ejemplo](api-gateway-create-api-from-example.md) para anular el código de estado en función del cuerpo de la respuesta de integración.
------
#### [ Consola de administración de AWS ]
**Anulación de un código de estado basado en el cuerpo de respuesta de integración**
1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Seleccione **Crear API**.
1. En **API de REST**, elija **Compilación**.
1. En **Detalles de la API**, elija **API de ejemplo**.
1. Seleccione **Crear API**.
API Gateway crea una API de tienda de mascotas de ejemplo. Para recuperar información sobre una mascota, utilice la solicitud de método de API de `GET /pets/{petId}`, donde `{petId}` es un parámetro de ruta correspondiente a un número de identificación de una mascota.
En este ejemplo, anula el código de respuesta del método `GET` a `400` cuando se detecta una condición de error.
1. En el árbol **Recursos**, elija el método `GET` en `/{petId}`.
1. Primero, pruebe la implementación actual de la API.
Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
1. En **petId**, introduzca **-1** y, a continuación, seleccione **Prueba**.
El **Cuerpo de respuesta** indica un error de fuera de intervalo:
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Además, la última línea bajo **Registros** termina por `Method completed with status: 200`.
La integración se ha completado correctamente, pero se ha producido un error. Ahora, anulará el código de estado basado en el cuerpo de respuesta de integración.
1. En la pestaña **Respuesta de integración**, en **Predeterminado: respuesta**, seleccione **Editar**.
1. Elija **Plantillas de mapeo**.
1. Elija **Add mapping template (Añadir plantilla de asignación)**.
1. En **Tipo de contenido**, ingrese **application/json**.
1. En **Cuerpo de la plantilla**, introduzca lo siguiente:
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Esta plantilla de asignación utiliza la variable `$context.responseOverride.status` para anular el código de estado a `400` si la respuesta de integración contiene la cadena `error`.
1. Seleccione **Save**.
1. Elija la pestaña **Prueba**.
1. En **petId**, introduzca **-1**.
1. En los resultados, el **Response Body (Cuerpo de respuesta)** indica un error de fuera de intervalo:
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Sin embargo, la última línea de **Registros** termina ahora por `Method completed with status: 400`.
------
#### [ CloudFormation ]
En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La siguiente definición de OpenAPI crea el recurso `GET pets/{petId}` y anula el código de estado en función del cuerpo de integración.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## Ejemplo 2: anular el encabezado de solicitud y crear nuevos encabezados
En el siguiente ejemplo se utiliza la [API de ejemplo](api-gateway-create-api-from-example.md) para anular el encabezado de solicitud y crear nuevos encabezados.
------
#### [ Consola de administración de AWS ]
**Anulación del encabezado de solicitud de un método mediante la creación de un nuevo encabezado**
1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija la API de ejemplo que creó en el tutorial anterior. El nombre de la API debe ser **PetStore**.
1. En el árbol **Recursos**, elija el método `GET` en `/pet`.
1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**.
1. Elija **Encabezados de solicitud HTTP** y, a continuación, elija **Agregar encabezado**.
1. En **Nombre**, escriba **header1**.
1. Elija **Agregar encabezado** y, a continuación, cree un segundo encabezado llamado **header2**.
1. Seleccione **Save**.
Ahora, combina estos encabezados en un valor de encabezado mediante una plantilla de asignación.
1. En la pestaña **Solicitud de integración**, en **Configuración de la solicitud de integración**, seleccione **Editar**.
1. En **Acceso directo de cuerpo de la solicitud**, elija **Cuando no haya plantillas definidas (recomendado)**.
1. Elija **Plantillas de mapeo** y, a continuación, haga lo siguiente:
1. Elija **Add mapping template (Añadir plantilla de asignación)**.
1. En **Tipo de contenido**, ingrese **application/json**.
1. En **Cuerpo de la plantilla**, introduzca lo siguiente:
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
Esta plantilla de asignación anula `header1` con la cadena `pets` y crea un encabezado de varios valores llamado `$header3Value` que combina `header1` y `header2`.
1. Seleccione **Save**.
1. Elija la pestaña **Prueba**.
1. En **Encabezados**, copie el siguiente código:
```
header1:header1Val
header2:header2Val
```
1. Seleccione **Test (Probar)**.
En el cuadro **Registros**, debería ver una entrada que incluye este texto:
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La siguiente definición de OpenAPI crea el recurso `GET pets` y anula el encabezado de solicitud y crea nuevos encabezados.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
Para utilizar una anulación de plantilla de asignación, agregue una o más de las siguientes variables `$context`. Para ver una lista de variables `$context`, consulte [Variables de contexto para transformaciones de datos](api-gateway-mapping-template-reference.md#context-variable-reference).
# Tutorial: modificación de la solicitud y respuesta de integración para integraciones con servicios de AWS
En el siguiente tutorial se muestra cómo utilizar las transformaciones de plantilla de asignación para configurar plantillas de asignación con el fin de transformar las solicitudes y respuestas de integración mediante la consola y la CLI de AWS.
**Topics**
+ [Configuración de la transformación de datos en la consola de API Gateway](#mapping-example-console)
+ [Configuración de la transformación de datos mediante la CLI de AWS](#mapping-example-cli)
+ [Plantilla CloudFormation de transformación de datos completada](#api-gateway-data-transformations-full-cfn-stack)
## Configuración de la transformación de datos en la consola de API Gateway
En este tutorial, creará una API y una tabla de DynamoDB incompletas con el siguiente archivo .zip [data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip). Esta API incompleta tiene un recurso `/pets` con los métodos `GET` y `POST`.
+ El método `GET` obtendrá datos del punto de conexión HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Los datos de salida se transformarán según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md).
+ El método `POST` permitirá al usuario `POST` información de la mascota en una tabla de Amazon DynamoDB mediante una plantilla de mapeo.
Descargue y descomprima [la plantilla de creación de aplicaciones para CloudFormation](samples/data-transformation-tutorial-console.zip). Utilizará esta plantilla para crear una tabla de DynamoDB para publicar información sobre la mascota y una API incompleta. Finalizará el resto de los pasos en la consola de API Gateway.
**Para crear una pila de CloudFormation**
1. Abra la consola de CloudFormation en [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Seleccione **Create stack (Crear pila)** y, a continuación, seleccione **With new resources (standard) (Con nuevos recursos [estándar])**.
1. En **Specify template (Especificar plantilla)**, elija **Upload a template file (Cargar un archivo de plantilla)**.
1. Seleccione la plantilla que ha descargado.
1. Elija **Next (Siguiente)**.
1. En **Stack name (Nombre de pila)**, escriba **data-transformation-tutorial-console** y, a continuación, elija **Next (Siguiente)**.
1. En **Configure stack options (Configurar opciones de pila)**, elija **Next (Siguiente)**.
1. Para **Capabilities** (Capacidades), sepa que CloudFormation puede crear recursos de IAM en su cuenta.
1. Elija **Siguiente** y, a continuación, elija **Enviar**.
CloudFormation aprovisiona los recursos especificados en la plantilla. Puede tardar varios minutos en finalizar el aprovisionamiento de los recursos. Cuando el estado de la pila de CloudFormation sea **CREATE\$1COMPLETE**, estará listo para continuar con el paso siguiente.
**Para probar la respuesta de integración de `GET`**
1. En la pestaña **Recursos** de la pila CloudFormation de **data-transformation-tutorial-console**, seleccione el ID físico de su API.
1. En el panel de navegación principal, seleccione **Recursos** y, a continuación, seleccione el método **GET**.
1. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
El resultado de la prueba mostrará lo siguiente:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Transformará este resultado según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md).
**Para transformar la respuesta de integración de `GET`**
1. Elija la pestaña **Respuesta de integración**.
Actualmente, no hay plantillas de mapeo definidas, por lo que la respuesta de integración no se transformará.
1. En **Predeterminado: respuesta**, seleccione **Editar**.
1. Elija **Plantillas de mapeo** y, a continuación, haga lo siguiente:
1. Elija **Add mapping template (Añadir plantilla de asignación)**.
1. En **Tipo de contenido**, ingrese **application/json**.
1. En **Cuerpo de la plantilla**, introduzca lo siguiente:
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
Seleccione **Save**.
**Para probar la respuesta de integración de `GET`**
+ Elija la pestaña **Prueba** y, a continuación, seleccione **Prueba**.
El resultado de la prueba mostrará la respuesta transformada.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Para transformar los datos de entrada del método `POST`**
1. Elija el método **POST**.
1. Elija la pestaña **Solicitud de integración** y, a continuación, en **Configuración de solicitud de integración**, elija **Editar**.
La plantilla CloudFormation ha rellenado algunos de los campos de la solicitud de integración.
+ El tipo de integración es Servicio de AWS.
+ El Servicio de AWS es DynamoDB.
+ El método HTTP es `POST`.
+ La acción es `PutItem`.
+ La función de ejecución que permite a API Gateway incluir un elemento en la tabla de DynamoDB es `data-transformation-tutorial-console-APIGatewayRole`. CloudFormation ha creado este rol para permitir que API Gateway tuviera los permisos mínimos para interactuar con DynamoDB.
No se ha especificado el nombre de la tabla de DynamoDB. Especificará el nombre en los pasos siguientes.
1. En **Acceso directo de cuerpo de la solicitud**, seleccione **Nunca**.
Esto significa que la API rechazará los datos con tipos de contenido que no tengan una plantilla de mapeo.
1. Elija **Plantillas de mapeo**.
1. El **Tipo de contenido** está establecido en `application/json`. Esto significa que la API rechazará un tipo de contenido que no sea application/json. Para obtener más información sobre los comportamientos del acceso directo a la integración, consulte . [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md)
1. Especifique el siguiente código en el editor de texto.
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
Esta plantilla especifica la tabla como `data-transformation-tutorial-console-ddb` y establece los elementos como `id`, `type` y `price`. Los elementos procederán del cuerpo del método `POST`. También puede usar un modelo de datos para ayudar a crear una plantilla de mapeo. Para obtener más información, consulte [Solicitud de la validación de las API de REST en API Gateway](api-gateway-method-request-validation.md).
1. Elija **Guardar** para guardar la plantilla de mapeo.
**Para añadir un método y una respuesta de integración desde el método `POST`**
CloudFormation ha creado un método y una respuesta de integración en blanco. Editará esta respuesta para proporcionar más información. Para obtener más información sobre cómo editar las respuestas, consulte [Ejemplos de asignación de parámetros para las API de REST en API Gateway](request-response-data-mappings.md).
1. En la pestaña **Respuesta de integración**, en **Predeterminado: respuesta**, seleccione **Editar**.
1. Elija **Plantillas de mapeo** y, a continuación, elija **Agregar plantilla de mapeo**.
1. En **Content-type**, introduzca **application/json**.
1. En el editor de código, introduzca la siguiente plantilla de mapeo de salida para enviar un mensaje de salida:
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
Para obtener más información acerca de las variables de contexto, consulte [Variables de contexto para transformaciones de datos](api-gateway-mapping-template-reference.md#context-variable-reference).
1. Elija **Guardar** para guardar la plantilla de mapeo.
**Probar el método `POST`**
Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
1. En el cuerpo de la solicitud, introduzca el siguiente ejemplo.
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. Seleccione **Probar**
El resultado debería mostrar su mensaje de éxito.
Puede abrir la consola de DynamoDB en [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) para comprobar que el elemento de ejemplo esté en la tabla.
**Para eliminar una pila de CloudFormation**
1. Abra la consola de CloudFormation en [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Seleccione su pila de CloudFormation.
1. Elija **Delete (Eliminar)** y, a continuación, confirme su elección.
## Configuración de la transformación de datos mediante la CLI de AWS
En este tutorial, creará una API y una tabla de DynamoDB incompletas con el siguiente archivo .zip [data-transformation-tutorial-cli.zip](samples/data-transformation-tutorial-cli.zip). Esta API incompleta tiene un recurso `/pets` con un método `GET` integrado en el punto de conexión HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Creará un método `POST` para conectarse a una tabla de DynamoDB y utilizará plantillas de mapeo para introducir datos en una tabla de DynamoDB.
+ Transformará los datos de salida según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md).
+ Creará un método `POST` para permitir al usuario `POST` información de la mascota en una tabla de Amazon DynamoDB mediante una plantilla de mapeo.
**Para crear una pila de CloudFormation**
Descargue y descomprima [la plantilla de creación de aplicaciones para CloudFormation](samples/data-transformation-tutorial-cli.zip).
Para completar el siguiente tutorial, necesita la [versión 2 de la AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Para comandos largos, se utiliza un carácter de escape (`\`) para dividir un comando en varias líneas.
**nota**
En Windows, algunos comandos de la CLI de Bash que utiliza habitualmente (por ejemplo, `zip`) no son compatibles con los terminales integrados del sistema operativo. Para obtener una versión de Ubuntu y Bash integrada con Windows, [instale el subsistema de Windows para Linux](https://learn.microsoft.com/en-us/windows/wsl/install). Los comandos de la CLI de ejemplo de esta guía utilizan el formato Linux. Los comandos que incluyen documentos JSON en línea deben reformatearse si utiliza la CLI de Windows.
1. Utilice el siguiente comando para crear la pila CloudFormation.
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation aprovisiona los recursos especificados en la plantilla. Puede tardar varios minutos en finalizar el aprovisionamiento de los recursos. Use el siguiente comando para ver el estado de su pila CloudFormation.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. Cuando el estado de su pila CloudFormation sea `StackStatus: "CREATE_COMPLETE"`, utilice el siguiente comando para recuperar los valores de salida relevantes para los pasos futuros.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
A continuación se muestran los valores de salida:
+ ApiRole, que es el nombre del rol que permite a API Gateway incluir elementos en la tabla de DynamoDB. En este tutorial, el nombre de rol es `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`.
+ DDBTableName, que es el nombre de la tabla de DynamoDB. En este tutorial, el nombre de la tabla es `data-transformation-tutorial-cli-ddb`.
+ ResourceId, que es el identificador del recurso de las mascotas donde están expuestos los métodos `GET` y `POST`. Para este tutorial, el ID del recurso es `efg456`.
+ ApiID, que es el identificador de la API. Para este tutorial, el ID de la API es `abc123`.
**Para probar el método `GET` antes de la transformación de datos**
+ Utilice el siguiente comando para probar el método `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
El resultado de la prueba mostrará lo siguiente.
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Transformará este resultado según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md).
**Para transformar la respuesta de integración de `GET`**
+ Use el siguiente comando para actualizar la respuesta de integración del método `GET`. Reemplace *rest-api-id* y *resource-id* con sus valores.
Utilice el siguiente comando para crear la respuesta de integración.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**Para probar el método `GET`**
+ Utilice el siguiente comando para probar el método `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
El resultado de la prueba mostrará la respuesta transformada.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Para crear un método `POST`**
1. Use el siguiente comando para crear un método nuevo en el recurso `/pets`.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
Este método le permitirá enviar información de mascotas a la tabla de DynamoDB que creó en la pila CloudFormation.
1. Utilice el siguiente comando para una integración Servicio de AWS en el método `POST`.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. Utilice el siguiente comando para crear una respuesta de método para una llamada correcta del método `POST`.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Utilice el siguiente comando para crear una respuesta de integración para una llamada correcta del método `POST`.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**Para probar el método `POST`**
+ Utilice el siguiente comando para probar el método `POST`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
El resultado mostrará el mensaje correcto.
**Para eliminar una pila de CloudFormation**
+ Use el siguiente comando para eliminar los recursos CloudFormation.
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## Plantilla CloudFormation de transformación de datos completada
El siguiente ejemplo es una plantilla CloudFormation completada, que crea una API y una tabla de DynamoDB con un recurso `/pets` con los métodos `GET` y `POST`.
+ El método `GET` obtendrá datos del punto de conexión HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Los datos de salida se transformarán según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md).
+ El método `POST` permitirá al usuario `POST` información de la mascota en una tabla de DynamoDB mediante una plantilla de mapeo.
### Plantilla de CloudFormation de ejemplo
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# Ejemplos que utilizan variables para las transformaciones de plantilla de asignación para API Gateway
En los siguientes ejemplos se muestra cómo utilizar las variables `$context`, `input` y `util` en las plantillas de asignación. Puede utilizar una integración simulada o una integración sin proxy de Lambda que devuelva el evento de entrada a API Gateway. Para obtener una lista de todas las variables admitidas para las transformaciones de datos, consulte [Variables para transformaciones de datos para API Gateway](api-gateway-mapping-template-reference.md).
## Ejemplo 1: pase de múltiples variables `$context` al punto de conexión de integración
El siguiente ejemplo muestra una plantilla de asignación que mapea variables `$context` de entrada a las variables de backend con nombres ligeramente diferentes en una carga de la solicitud de integración:
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
La salida de esta plantilla de asignación debe tener el siguiente aspecto:
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
Una de las variables es una clave de API. En este ejemplo se supone que el método requiere una clave de API.
## Ejemplo 2: pase de todos los parámetros de solicitud al punto de conexión de integración a través de una carga útil JSON
El siguiente ejemplo pasa todos los parámetros de solicitud, como los parámetros `path`, `querystring` y `header`, a través del punto de conexión de integración mediante una carga útil de JSON:
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
Si una solicitud tiene los siguientes parámetros de entrada:
+ Un parámetro de ruta denominado `myparam`
+ Parámetros de cadenas de consulta `querystring1=value1,value2`
+ Encabezados `"header1" : "value1"`.
La salida de esta plantilla de asignación debe tener el siguiente aspecto:
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## Ejemplo 3: pase de una subsección de una solicitud de método al punto de conexión de integración
En el siguiente ejemplo se utiliza el parámetro de entrada `name` para recuperar solo el parámetro `name` y el parámetro de entrada `input.json('$')` para recuperar todo el cuerpo de la solicitud de método:
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
Para una solicitud que incluye los parámetros de cadena de consulta `name=Bella&type=dog` y el cuerpo siguiente:
```
{
"Price" : "249.99",
"Age": "6"
}
```
La salida de esta plantilla de asignación debe tener el siguiente aspecto:
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
Esta plantilla de asignación elimina el parámetro de cadena de consulta `type=dog`.
Si la entrada JSON contiene caracteres sin escape que no puede analizar JavaScript, es posible que API Gateway devuelva una respuesta 400. Aplique `$util.escapeJavaScript($input.json('$'))` para asegurarse de que la entrada JSON se pueda analizar correctamente.
El ejemplo anterior con `$util.escapeJavaScript($input.json('$'))` se aplica de la siguiente manera:
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
En este caso, la salida de esta plantilla de asignación debe tener el siguiente aspecto:
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## Ejemplo 4: uso de una expresión JSONPath para pasar una subsección de una solicitud de método al punto de conexión de integración
En el siguiente ejemplo se utilizan expresiones JSONPath para recuperar solo el parámetro de entrada `name` y el valor de `Age` del cuerpo de solicitud:
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
Para una solicitud que incluye los parámetros de cadena de consulta `name=Bella&type=dog` y el cuerpo siguiente:
```
{
"Price" : "249.99",
"Age": "6"
}
```
La salida de esta plantilla de asignación debe tener el siguiente aspecto:
```
{
"name" : "Bella",
"body" : "6"
}
```
Esta plantilla de asignación elimina el parámetro de cadena de consulta `type=dog` y el campo `Price` del cuerpo.
Si una carga de solicitud de método contiene caracteres sin escape que no puede analizar JavaScript, es posible que API Gateway devuelva una respuesta `400`. Aplique `$util.escapeJavaScript()` para asegurarse de que la entrada JSON se pueda analizar correctamente.
El ejemplo anterior con `$util.escapeJavaScript($input.json('$.Age'))` se aplica de la siguiente manera:
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
En este caso, la salida de esta plantilla de asignación debe tener el siguiente aspecto:
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## Ejemplo 5: uso de una expresión JSONPath para pasar información sobre una solicitud de método al punto de conexión de integración
En el siguiente ejemplo se utilizan `$input.params()`, `$input.path()` y `$input.json()` para enviar información sobre una solicitud de método al punto de conexión de integración. Esta plantilla de asignación utiliza el método `size()` para proporcionar el número de elementos de una lista.
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
Para una solicitud que incluye el parámetros de ruta `123` y el cuerpo siguiente:
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
La salida de esta plantilla de asignación debe tener el siguiente aspecto:
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
Si una carga de solicitud de método contiene caracteres sin escape que no puede analizar JavaScript, es posible que API Gateway devuelva una respuesta `400`. Aplique `$util.escapeJavaScript()` para asegurarse de que la entrada JSON se pueda analizar correctamente.
El ejemplo anterior con `$util.escapeJavaScript($input.json('$.things'))` se aplica de la siguiente manera:
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
La salida de esta plantilla de asignación debe tener el siguiente aspecto:
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# Variables para transformaciones de datos para API Gateway
Cuando cree una asignación de parámetro, puede utilizar variables de contexto como origen de datos. Cuando cree las transformaciones de plantilla de asignación, puede utilizar variables de contexto, de entrada y de utilidad en los scripts que escriba en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Por obtener ejemplos de plantillas de asignación que utilizan estas variables de referencia, consulte [Ejemplos que utilizan variables para las transformaciones de plantilla de asignación para API Gateway](api-gateway-mapping-variable-examples.md).
Para obtener una lista de variables de referencia para el registro de acceso, consulte [Variables para el registro de acceso para API Gateway](api-gateway-variables-for-access-logging.md).
## Variables de contexto para transformaciones de datos
Puede utilizar las siguientes variables `$context` que distinguen entre mayúsculas y minúsculas para transformaciones de datos.
| Parámetro | Descripción |
| --- | --- |
| \$1context.accountId | El ID de cuenta de AWS del propietario de la API. |
| \$1context.apiId | El identificador que API Gateway asigna a su API. |
| \$1context.authorizer.claims.property | Una propiedad de las notificaciones devueltas por el grupo de usuarios de Amazon Cognito una vez que se ha autenticado correctamente al intermediario del método. Para obtener más información, consulte [Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). La llamada a `$context.authorizer.claims` devuelve null. |
| \$1context.authorizer.principalId | La identificación de usuario principal asociada con el token enviado por el cliente y devuelto por el autorizador de Lambda de API Gateway (que anteriormente se denominaba autorizador personalizado). Para obtener más información, consulte [Uso de autorizadores Lambda de API Gateway](apigateway-use-lambda-authorizer.md). |
| \$1context.authorizer.property | El valor en forma de cadena del par clave-valor especificado de la asignación `context` que devuelve la función de Lambda del autorizador de Lambda de API Gateway. Por ejemplo, si el autorizador devuelve la siguiente asignación de `context`: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} La llamada a `$context.authorizer.key` devuelve la cadena `"value"`, la llamada a `$context.authorizer.numKey` devuelve la cadena `"1"` y la llamada a `$context.authorizer.boolKey` devuelve la cadena `"true"`. En el caso de la *propiedad*, el único carácter especial admitido es el carácter `(_)` de subrayado. Para obtener más información, consulte [Uso de autorizadores Lambda de API Gateway](apigateway-use-lambda-authorizer.md). |
| \$1context.awsEndpointRequestId | El ID de solicitud del punto de enlace de AWS. |
| \$1context.deploymentId | El ID de la implementación de la API. |
| \$1context.domainName | El nombre de dominio completo que se utiliza para invocar la API. Este debe ser el mismo que el encabezado `Host` entrante. |
| \$1context.domainPrefix | La primera etiqueta del `$context.domainName`. |
| \$1context.error.message | Una cadena que contiene un mensaje de error de API Gateway. Esta variable solo se puede usar para una sustitución sencilla de variables en una plantilla de mapeo de cuerpo [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), que no procesa el motor de Velocity Template Language, y en el registro de acceso. Para obtener más información, consulte [Supervisión de la ejecución de la API de WebSocket con métricas de CloudWatch](apigateway-websocket-api-logging.md) y [Configuración de respuestas de gateway para personalizar respuestas de errores](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.messageString | El valor entrecomillado de \$1context.error.message, es decir, "\$1context.error.message". |
| \$1context.error.responseType | Un [tipo](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Esta variable solo se puede usar para una sustitución sencilla de variables en una plantilla de mapeo de cuerpo [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), que no procesa el motor de Velocity Template Language, y en el registro de acceso. Para obtener más información, consulte [Supervisión de la ejecución de la API de WebSocket con métricas de CloudWatch](apigateway-websocket-api-logging.md) y [Configuración de respuestas de gateway para personalizar respuestas de errores](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.validationErrorString | Una cadena que contiene un mensaje de error de validación detallado. |
| \$1context.extendedRequestId | El ID ampliado que API Gateway genera y asigna a la solicitud de API. El ID de solicitud ampliado contiene información útil para la depuración y la resolución de problemas. |
| \$1context.httpMethod | El método HTTP utilizado. Los valores válidos son: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` y `PUT`. |
| \$1context.identity.accountId | El ID de cuenta de AWS asociado con la solicitud. |
| \$1context.identity.apiKey | Para los métodos de API que necesitan una clave de API, esta variable es la clave de API asociada a la solicitud del método. Para métodos que no requieren una clave de API, esta variable corresponde a valores null. Para obtener más información, consulte [Planes de uso y clave de API para las API de REST en API Gateway](api-gateway-api-usage-plans.md). |
| \$1context.identity.apiKeyId | El ID de clave de API asociado a una solicitud de API que requiere una clave de API. |
| \$1context.identity.caller | El identificador principal del intermediario que firmó la solicitud. Compatible con recursos que utilizan la autorización de IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Una lista separada por comas de todos los proveedores de autenticación de Amazon Cognito utilizados por el intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. Por ejemplo, para una identidad de un grupo de usuarios de Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Consulte [Uso de las identidades federadas](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) en la *Guía para desarrolladores de Amazon Cognito* para obtener información sobre los proveedores de autenticación de Amazon Cognito disponibles. |
| \$1context.identity.cognitoAuthenticationType | El tipo de autenticación de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. Los valores posibles incluyen `authenticated` para identidades autenticadas y `unauthenticated` para identidades no autenticadas. |
| \$1context.identity.cognitoIdentityId | El ID de identidad de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | El ID del grupo de identidades de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. |
| \$1context.identity.principalOrgId | El [ID de organización de AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). |
| \$1context.identity.sourceIp | La dirección IP de origen de la conexión TCP inmediata que realiza la solicitud al punto de conexión de API Gateway. |
| \$1context.identity.clientCert.clientCertPem | El certificado de cliente codificado en PEM que el cliente presentó durante la autenticación TLS mutua. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. |
| \$1context.identity.clientCert.subjectDN | Nombre distintivo del asunto del certificado que presenta un cliente. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. |
| \$1context.identity.clientCert.issuerDN | Nombre distintivo del emisor del certificado que presenta un cliente. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. |
| \$1context.identity.clientCert.serialNumber | Número de serie del certificado. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. |
| \$1context.identity.clientCert.validity.notBefore | Fecha antes de la cual el certificado no es válido. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. |
| \$1context.identity.clientCert.validity.notAfter | Fecha después de la cual el certificado no es válido. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. |
| \$1context.identity.vpcId | El ID de VPC de la VPC que realiza la solicitud al punto de conexión de API Gateway. |
| \$1context.identity.vpceId | El ID de punto de conexión de VPC del punto de conexión de VPC que realiza la solicitud al punto de conexión de API Gateway. Está presente solo cuando tiene una API privada. |
| \$1context.identity.user | El identificador principal del usuario que se autorizará a acceder al recurso. Compatible con recursos que utilizan la autorización de IAM. |
| \$1context.identity.userAgent | El encabezado [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) del intermediario de la API. |
| \$1context.identity.userArn | El Nombre de recurso de Amazon (ARN) del usuario identificado después de la autenticación. Para obtener más información, consulte [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.isCanaryRequest | Devuelve `true` si la solicitud se dirigió al canario y `false` si no se dirigió al canario. Está presente solo cuando tiene un canario activado. |
| \$1context.path | Ruta de acceso de la solicitud. Por ejemplo, en el caso del URL de una solicitud que no es de proxy https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, el valor de \$1context.path es /\$1stage\$1/root/child. |
| \$1context.protocol | Protocolo de la solicitud; por ejemplo, HTTP/1.1. Las API de API Gateway pueden aceptar solicitudes HTTP/2, pero API Gateway envía solicitudes a las integraciones de backend mediante HTTP/1.1. Como resultado, el protocolo de solicitud se registra como HTTP/1.1 incluso si un cliente envía una solicitud que usa HTTP/2. |
| \$1context.requestId | ID de la solicitud. Los clientes pueden anular este ID de solicitud. Utilice `$context.extendedRequestId` para un ID de solicitud único que genera API Gateway. |
| \$1context.requestOverride.header.header\$1name | La invalidación del encabezado de solicitud. Si este parámetro se define, contiene los encabezados que se utilizarán en lugar de los **HTTP Headers (Encabezados HTTP)** que se definen en el panel **Integration Request (Solicitud de integración)**. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.path.path\$1name | La invalidación de la ruta de acceso de la solicitud. Si este parámetro se define, contiene la ruta de acceso de la solicitud que se utilizará en lugar de los **URL Path Parameters (Parámetros de ruta URL)** que se definen en el panel **Integration Request (Solicitud de integración)**. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.querystring.querystring\$1name | La invalidación de la cadena de consulta de solicitud. Si este parámetro se define, contiene las cadenas de consulta de solicitud que se utilizarán en lugar de los **URL Query String Parameters (Parámetros de cadena de consulta URL)** que se definen en el panel **Integration Request (Solicitud de integración)**. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.header.header\$1name | La invalidación del encabezado de respuesta. Si este parámetro se define, contiene el encabezado que se devolverá en lugar del Response header (Encabezado de respuesta) que se define como Default mapping (Asignación predeterminada) en el panel Integration Response (Respuesta de integración). Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.status | La invalidación del código de estado de respuesta. Si este parámetro se define, contiene el código de estado que se devolverá en lugar del Method response status (Estado de respuesta de método) que se define como Default mapping (Asignación predeterminada) en el panel Integration Response (Respuesta de integración). Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestTime | Hora de la solicitud en formato [CLF](https://httpd.apache.org/docs/current/logs.html#common)-(dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Hora de la solicitud en formato [Epoch](https://en.wikipedia.org/wiki/Unix_time) en milisegundos. |
| \$1context.resourceId | El identificador que API Gateway asigna a su recurso. |
| \$1context.resourcePath | La ruta a su recurso. Por ejemplo, en el caso del URI de una solicitud que no es de proxy `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, el valor de `$context.resourcePath` es `/root/child`. Para obtener más información, consulte [Tutorial: Creación de una API de REST con integración no de proxy HTTP](api-gateway-create-api-step-by-step.md). |
| \$1context.stage | La etapa de implementación de la solicitud de la API (por ejemplo, `Beta` o `Prod`). |
| \$1context.wafResponseCode | La respuesta recibida desde [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` o `WAF_BLOCK`. No se establecerá si la etapa no está asociada a una ACL web. Para obtener más información, consulte [Uso de AWS WAF para proteger sus API de REST en API Gateway](apigateway-control-access-aws-waf.md). |
| \$1context.webaclArn | El ARN completo de la ACL web que se utiliza para decidir si se debe permitir o bloquear la solicitud. No se establecerá si la etapa no está asociada a una ACL web. Para obtener más información, consulte [Uso de AWS WAF para proteger sus API de REST en API Gateway](apigateway-control-access-aws-waf.md). |
## Variables de entrada
Puede utilizar las siguientes variables `$input` que distinguen entre mayúsculas y minúsculas para hacer referencia a la carga útil de solicitud del método y a los parámetros de solicitud del método. Están disponibles las siguientes funciones:
| Variable y función | Descripción |
| --- | --- |
| \$1input.body | Devuelve la carga de solicitud bruta como una cadena. Puede utilizar `$input.body` para conservar números enteros de punto flotante, como `10.00`. |
| \$1input.json(x) | Esta función evalúa una expresión JSONPath y devuelve los resultados como una cadena JSON. Por ejemplo, `$input.json('$.pets')` devuelve una cadena JSON que representa la estructura de `pets` (mascotas). Para obtener más información acerca de JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) o [JSONPath for Java](https://github.com/json-path/JsonPath). |
| \$1input.params() | Devuelve una asignación de todos los parámetros de solicitud. Recomendamos que se utilice `$util.escapeJavaScript` para sanear el resultado a fin de evitar un posible ataque de inyección. Para un control total del saneamiento de solicitudes, utilice una integración de proxy sin plantilla y gestione dicho saneamiento en su integración. |
| \$1input.params(x) | Devuelve el valor de un parámetro de solicitud de método de la ruta, cadena de consulta o valor de encabezado (buscado en este orden) dada una cadena de nombre de parámetro `x`. Recomendamos que se utilice `$util.escapeJavaScript` para sanear el parámetro a fin de evitar un posible ataque de inyección. Para un control total del saneamiento de parámetros, utilice una integración de proxy sin plantilla y gestione dicho saneamiento en su integración. |
| \$1input.path(x) | Toma una cadena de expresión JSONPath (`x`) y devuelve una representación del resultado en forma de objeto JSON. Esto le permite tener acceso y manipular los elementos de la carga de forma nativa en [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Por ejemplo, si la expresión `$input.path('$.pets')` devuelve un objeto como este: [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').size()` devolvería `"3"`. Para obtener más información acerca de JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) o [JSONPath for Java](https://github.com/json-path/JsonPath). |
## Variables de etapa
Puede utilizar las siguientes variables de etapa como marcadores de posición para ARN y URL en integraciones de método. Para obtener más información, consulte [Uso de variables de etapa para una API de REST en API Gateway](stage-variables.md).
| Sintaxis | Descripción |
| --- | --- |
| \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'], o bien \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* representa un nombre de variable de etapa. |
## Variables de utilidad
Puede utilizar las siguientes variables `$util` que distinguen entre mayúsculas y minúsculas para utilizar funciones de utilidad en las plantillas de asignación. A menos que se especifique lo contrario, el conjunto de caracteres predeterminado es UTF-8.
| Función | Descripción |
| --- | --- |
| \$1util.escapeJavaScript() | Aplica caracteres de escape a los caracteres de una cadena usando reglas de cadena de JavaScript. Esta función convertirá todas las comillas simples (`'`) en caracteres de escape (`\'`). Sin embargo, JSON no admite comillas simples con caracteres de escape. Por lo tanto, cuando la salida de esta función se utiliza en una propiedad de JSON, debe convertir todas las comillas simples con caracteres de escape (`\'`) en comillas simples normales (`'`). Esto se muestra en el siguiente ejemplo: "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")" |
| \$1util.parseJson() | Toma un elemento JSON en forma de cadena y devuelve una representación del resultado en forma de objeto. Puede utilizar el resultado de esta función para tener acceso y manipular los elementos de la carga de forma nativa en Apache Velocity Template Language (VTL). Por ejemplo, si tiene la siguiente carga: {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} y usa la siguiente plantilla de asignación #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Obtendrá el siguiente resultado: {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | Convierte una cadena en formato "application/x-www-form-urlencoded". |
| \$1util.urlDecode() | Descodifica una cadena "application/x-www-form-urlencoded". |
| \$1util.base64Encode() | Codifica los datos en una cadena codificada en base64. |
| \$1util.base64Decode() | Descodifica los datos de una cadena codificada en base64. |