# 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
```