Plantillas de asignación para las API de REST
En API Gateway, una solicitud o respuesta de método de la API puede tomar una carga en un formato diferente al de la respuesta o solicitud de integración.
Puede transformar sus datos para:
Hacer coincidir la carga con un formato especificado por la API.
Invalidar códigos de estado y parámetros de solicitud y de respuesta de una API.
Devolver los encabezados de respuesta seleccionados por el cliente.
Asociar los parámetros de ruta, los parámetros de la cadena de consulta o los parámetros de encabezado a la solicitud de método del proxy de HTTP o el proxy de Servicio de AWS.
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.
Puede utilizar plantillas de mapeo para transformar sus datos. Una plantilla de mapeo es un script expresado en lenguaje Velocity Template Language (VTL)
En esta sección se describe la información conceptual relacionada con las plantillas de asignación. Para obtener instrucciones sobre cómo crear una plantilla de asignación para una API de REST de API Gateway, consulte Configuración de las transformaciones de datos en API Gateway.
Ejemplo de plantilla de asignación
En el siguiente ejemplo se muestran los datos de entrada de una solicitud de integración.
[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]
En el siguiente ejemplo se muestra una plantilla de asignación para transformar los datos de solicitud de integración.
#set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ]
En el siguiente ejemplo se muestran los datos de salida de la transformación.
[ { "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 } ]
En el siguiente diagrama se muestran los detalles de esta plantilla de mapeo.
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#
.Un bucle
foreach
recorre cada objeto de los datos JSON originales.La descripción es una concatenación del
id
ytype
de la mascota de los datos JSON originales.askingPrice
es elprice
es el precio de los datos JSON originales.
1 #set($inputRoot = $input.path('$')) 2 [ 3 #foreach($elem in $inputRoot) 4 { 5 "description" : "Item $elem.id is a $elem.type.", 6 "askingPrice" : $elem.price 7 }#if($foreach.hasNext),#end 8 #end 9 ]
En esta plantilla de mapeo:
-
En la línea 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#
. -
En la línea 3, un bucle
foreach
recorre cada objeto de los datos JSON originales. -
En la línea 5, la
description
es una concatenación delid
ytype
de la mascota de los datos JSON originales. -
En la línea 6,
askingPrice
es elprice
es el precio de los datos JSON originales.
Para obtener más información sobre Velocity Template Language, consulte la referencia de Apache Velocity - VTL
En la plantilla de asignación se asume que los datos subyacentes son de un objeto JSON. No se requiere definir un modelo para los datos. Sin embargo, un modelo para los datos de salida permite que los datos anteriores se devuelvan como un objeto específico del idioma. Para obtener más información, consulte Modelos de datos para las API de REST.
Ejemplos de plantillas de asignación complejas
También puede crear plantillas de mapeo más complicadas. El siguiente ejemplo muestra la concatenación de referencias y un límite de 100 para determinar si una mascota es asequible.
En el siguiente ejemplo se muestran los datos de entrada de una solicitud de integración.
[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]
En el siguiente ejemplo se muestra una plantilla de asignación para transformar los datos de solicitud de integración.
#set($inputRoot = $input.path('$')) #set($cheap = 100) [ #foreach($elem in $inputRoot) { #set($name = "${elem.type}number$elem.id") "name" : $name, "description" : "Item $elem.id is a $elem.type.", #if($elem.price > $cheap )#set ($afford = 'too much!') #{else}#set ($afford = $elem.price)#end "askingPrice" : $afford }#if($foreach.hasNext),#end #end ]
En el siguiente ejemplo se muestran los datos de salida de la transformación.
[ { "name" : dognumber1, "description" : "Item 1 is a dog.", "askingPrice" : too much! }, { "name" : catnumber2, "description" : "Item 2 is a cat.", "askingPrice" : too much! }, { "name" : fishnumber3, "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ]
También puede ver modelos de datos más complicados. Consulte Ejemplo de modelos de datos y plantillas de asignación de API Gateway.