Configuración de las transformaciones de datos en API Gateway

En esta sección se muestra cómo configurar plantillas de mapeo para transformar las solicitudes y respuestas de integración mediante la consola y la CLI de AWS.

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. 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 Plantilla de mapeo PetStore.

• 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 AWS CloudFormation. 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 AWS CloudFormation

1. Abra la consola de AWS CloudFormation en https://console.aws.amazon.com/cloudformation.

2. Seleccione Create stack (Crear pila) y, a continuación, seleccione With new resources (standard) (Con nuevos recursos [estándar]).

3. En Specify template (Especificar plantilla), elija Upload a template file (Cargar un archivo de plantilla).

4. Seleccione la plantilla que ha descargado.

5. Elija Next (Siguiente).

6. En Stack name (Nombre de pila), escriba data-transformation-tutorial-console y, a continuación, elija Next (Siguiente).

7. En Configure stack options (Configurar opciones de pila), elija Next (Siguiente).

8. Para Capabilities (Capacidades), sepa que AWS CloudFormation puede crear recursos de IAM en su cuenta.

9. Seleccione Enviar.

AWS 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 AWS CloudFormation sea CREATE_COMPLETE, 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 AWS CloudFormation de data-transformation-tutorial-console, seleccione el ID físico de su API.

2. En el panel de navegación principal, seleccione Recursos y, a continuación, seleccione el método GET.

3. 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 Plantilla de mapeo PetStore.

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á.

2. En Predeterminado: respuesta, seleccione Editar.

3. Elija Plantillas de mapeo y, a continuación, haga lo siguiente:

   1. Elija Add mapping template (Añadir plantilla de asignación).

   2. En Tipo de contenido, ingrese application/json.

   3. 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 Guardar.

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.

2. Elija la pestaña Solicitud de integración y, a continuación, en Configuración de solicitud de integración, elija Editar.

   La plantilla AWS 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. AWS 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.

3. 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.

4. Elija Plantillas de mapeo.

5. 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 Comportamientos del acceso directo a la integración.

6. 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.

7. 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

AWS 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 Referencia de mapeo de datos de solicitud y respuesta de API de Amazon API Gateway.

1. En la pestaña Respuesta de integración, en Predeterminado: respuesta, seleccione Editar.

2. Elija Plantillas de mapeo y, a continuación, elija Agregar plantilla de mapeo.

3. En Content-type, introduzca application/json.

4. 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 $context para modelos de datos, autorizadores, plantillas de mapeo y registro de acceso de CloudWatch.

5. 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"
   }

2. Seleccione Probar.

   El resultado debería mostrar su mensaje de éxito.

   Puede abrir la consola de DynamoDB en https://console.aws.amazon.com/dynamodb/ para comprobar que el elemento de ejemplo esté en la tabla.

Para eliminar una pila de AWS CloudFormation

1. Abra la consola de AWS CloudFormation en https://console.aws.amazon.com/cloudformation.

2. Seleccione su pila de AWS CloudFormation.

3. 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. 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 Plantilla de mapeo PetStore.

• 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 AWS CloudFormation

Descargue y descomprima la plantilla de creación de aplicaciones para AWS CloudFormation.

Para completar el siguiente tutorial, necesita la versión 2 de la AWS Command Line Interface (AWS CLI).

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. 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 AWS CloudFormation.

   aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM 

2. AWS 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 AWS CloudFormation.

   aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli

3. Cuando el estado de su pila AWS 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 Plantilla de mapeo PetStore.

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 AWS CloudFormation.

2. 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\")} }}"}'
   

3. 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

4. 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 AWS CloudFormation

• Use el siguiente comando para eliminar los recursos AWS CloudFormation.

  aws cloudformation delete-stack  --stack-name data-transformation-tutorial-cli

Plantilla AWS CloudFormation de transformación de datos completada

El siguiente ejemplo es una plantilla AWS 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 Plantilla de mapeo PetStore.

• El método POST permitirá al usuario POST información de la mascota en una tabla de DynamoDB mediante una plantilla de mapeo.

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

Siguientes pasos

Para examinar plantillas de asignación más complejas, consulte los siguientes ejemplos:

• Vea modelos y plantillas de mapeo más complejos con el álbum de fotos de ejemplo Ejemplo de álbum de fotos.

• Para obtener más información acerca de los modelos, consulte Modelos de datos para las API de REST.

• Para obtener información sobre cómo mapear diferentes resultados de códigos de respuesta,Configuración de mapeo de datos de solicitud y respuesta mediante la consola de API Gateway.

• Para obtener información sobre cómo configurar los mapeos de datos a partir de los datos de solicitud de método de una API, Plantilla de mapeo de API Gateway y referencia de la variable de registro de acceso.