Configurar transformações de dados no API Gateway

Esta seção mostra como configurar modelos de mapeamento para transformar solicitações e respostas de integração usando o console e a CLI da AWS.

Configurar transformações de dados no console do API Gateway

Neste tutorial, você criará uma API incompleta e uma tabela do DynamoDB usando o seguinte arquivo .zip data-transformation-tutorial-console.zip. Essa API incompleta tem um recurso /pets com os métodos GET e POST.

• O método GET obterá dados do endpoint HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Os dados de saída serão transformados de acordo com o modelo de mapeamento em Modelo de mapeamento PetStore.

• O método POST possibilitará que o usuário POST informações sobre animais de estimação em uma tabela do Amazon DynamoDB usando um modelo de mapeamento.

Baixe e descompacte o modelo de criação de aplicativos para AWS CloudFormation. Você usará esse modelo para criar uma tabela do DynamoDB para publicar informações sobre animais de estimação e uma API incompleta. Você concluirá o restante das etapas no console do API Gateway.

Como criar uma pilha do AWS CloudFormation

1. Abra o console do AWS CloudFormation em https://console.aws.amazon.com/cloudformation.

2. Selecione Create stack (Criar pilha) e With new resources (standard) (Com novos recursos (padrão)).

3. Em Specify template (Especificar modelo), escolha Upload a template file (Fazer upload de um arquivo de modelo).

4. Selecione o modelo que você baixou.

5. Escolha Next (Próximo).

6. Em Nome da pilha, insira data-transformation-tutorial-console e escolha Avançar.

7. Para Configurar opções de pilha, escolha Avançar.

8. Para Capabilities (Recursos), reconheça que AWS CloudFormation pode criar recursos do IAM em sua conta.

9. Selecione Enviar.

O AWS CloudFormation fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Quando o status da sua pilha do AWS CloudFormation for CREATE_COMPLETE, você estará pronto para passar para a próxima etapa.

Como testar a resposta de integração GET

1. Na guia Recursos da pilha de AWS CloudFormation para data-transformation-tutorial-console, selecione o ID físico de sua API.

2. No painel de navegação, selecione Recursos e, depois, selecione o método GET.

3. Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

   A saída do teste mostrará o seguinte:

   [
     {
       "id": 1,
       "type": "dog",
       "price": 249.99
     },
     {
       "id": 2,
       "type": "cat",
       "price": 124.99
     },
     {
       "id": 3,
       "type": "fish",
       "price": 0.99
     }
   ]

   Você transformará esse resultado de acordo com o modelo de mapeamento em Modelo de mapeamento PetStore.

Como transformar a resposta de integração GET

1. Selecione a guia Resposta de integração.

   Atualmente, não há modelos de mapeamento definidos, portanto, a resposta de integração não será transformada.

2. Em Padrão - Resposta, selecione Editar.

3. Selecione Modelos de mapeamento e, depois, faça o seguinte:

   1. Escolha Add mapping template (Adicionar modelo de mapeamento).

   2. Em Tipo de conteúdo, insira application/json.

   3. Em Corpo do modelo, insira o seguinte:

      #set($inputRoot = $input.path('$'))
      [
      #foreach($elem in $inputRoot)
        {
          "description" : "Item $elem.id is a $elem.type.",
          "askingPrice" : $elem.price
        }#if($foreach.hasNext),#end
      
      #end
      ]

   Escolha Salvar.

Como testar a resposta de integração GET

• Selecione a guia Testar e, depois, Testar.

  A saída do teste mostrará a resposta 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
    }
  ]

Como transformar dados de entrada do método POST

1. Selecione o método POST.

2. Selecione a guia Solicitação de integração e, em Configurações de solicitação de integração, selecione Editar.

   O modelo AWS CloudFormation preencheu alguns dos campos da solicitação de integração.

   • O tipo de integração é AWS service (Serviço da AWS).

   • O AWS service (Serviço da AWS) é o DynamoDB.

   • O método HTTP é o POST.

   • A ação é PutItem.

   • O perfil de execução que possibilita que o API Gateway coloque um item na tabela do DynamoDB é data-transformation-tutorial-console-APIGatewayRole. O AWS CloudFormation criou esse perfil para possibilitar que o API Gateway tenha as permissões mínimas para interagir com o DynamoDB.

   O nome da tabela do DynamoDB não foi especificado. Você especificará o nome nas etapas a seguir.

3. Em Passagem do corpo da solicitação, selecione Nunca.

   Isso significa que a API rejeitará dados com tipos de conteúdo que não tenham um modelo de mapeamento.

4. Selecione Modelos de mapeamento.

5. O Tipo de conteúdo é definido como application/json. Isso significa que tipos de conteúdo que não sejam application/json serão rejeitados pela API. Para obter mais informações sobre os comportamentos de passagem direta de integração, consulte Comportamentos de passagem direta de integração.

6. Insira o código a seguir no 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")
           }
       }
   }

   Esse modelo especifica a tabela como data-transformation-tutorial-console-ddb e define os itens como id, type e price. Os itens virão do corpo do método POST. Você também pode usar um modelo de dados para ajudar a criar um modelo de mapeamento. Para ter mais informações, consulte Solicitar validação para APIs REST no API Gateway.

7. Escolha Salvar para salvar seu modelo de mapeamento.

Como adicionar um método e uma resposta de integração do método POST

O AWS CloudFormation criou um método em branco e uma resposta de integração. Você editará essa resposta para fornecer mais informações. Para ter mais informações sobre como editar respostas, consulte Referência de mapeamento de dados de resposta e de solicitação de API do Amazon API Gateway.

1. Na guia Resposta de integração, em Padrão - Resposta, selecione Editar.

2. Selecione Modelos de mapeamento e, depois, Adicionar modelo de mapeamento.

3. Em Tipo de conteúdo, insira application/json.

4. No editor de código, insira o seguinte modelo de mapeamento de saída para enviar uma mensagem de saída:

   { "message" : "Your response was recorded at $context.requestTime" }

   Para ter mais informações sobre variáveis de contexto, consulte Variáveis $context para modelos de dados, autorizadores, modelos de mapeamento e registro de acesso em logs do CloudWatch.

5. Escolha Salvar para salvar seu modelo de mapeamento.

Testar o método POST

Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

1. No corpo da solicitação, insira o exemplo a seguir.

   {
             "id": "4",
             "type" : "dog",
             "price": "321"
   }

2. Escolha Testar.

   A saída deve mostrar sua mensagem de êxito.

   Você pode abrir o console do DynamoDB em https://console.aws.amazon.com/dynamodb/ para verificar se o item de exemplo está na sua tabela.

Para excluir uma pilha do AWS CloudFormation

1. Abra o console do AWS CloudFormation em https://console.aws.amazon.com/cloudformation.

2. Selecione sua pilha do AWS CloudFormation.

3. Escolha Excluir e, em seguida, confirme sua escolha.

Configurar a transformação de dados usando a CLI da AWS

Neste tutorial, você criará uma API incompleta e uma tabela do DynamoDB usando o arquivo .zip data-transformation-tutorial-console.zip a seguir. Essa API incompleta tem um recurso /pets com um método GET integrado ao endpoint HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Você criará um método POST para se conectar a uma tabela do DynamoDB e usará modelos de mapeamento para inserir dados em uma tabela do DynamoDB.

• Você transformará os dados de saída de acordo com o modelo de mapeamento em Modelo de mapeamento PetStore.

• Você criará um método POST para possibilitar que o usuário POST informações sobre animais de estimação em uma tabela do Amazon DynamoDB usando um modelo de mapeamento.

Como criar uma pilha do AWS CloudFormation

Baixe e descompacte o modelo de criação de aplicativos para AWS CloudFormation.

Para concluir o tutorial a seguir, é necessária a AWS Command Line Interface (AWS CLI) versão 2.

Para comandos longos, um caractere de escape (\) é usado para dividir um comando em várias linhas.

nota

No Windows, alguns comandos da CLI do Bash que você costuma usar (como zip) não são compatíveis com os terminais integrados do sistema operacional. Para obter uma versão do Ubuntu com o Bash integrada no Windows, instale o Subsistema do Windows para Linux. Os exemplos de comandos da CLI neste guia usam a formatação Linux. Os comandos que incluem documentos JSON em linha deverão ser reformatados se você estiver usando a CLI do Windows.

1. Use o comando a seguir para criar a pilha de 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. O AWS CloudFormation fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Use o comando a seguir para ver o status de sua pilha de AWS CloudFormation.

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

3. Quando o status da sua pilha de AWS CloudFormation for StackStatus: "CREATE_COMPLETE", use o comando a seguir para recuperar valores de saída relevantes para etapas futuras.

    aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"

   Os valores de saída são os seguintes:

   • ApiRole, que é o nome do perfil que possibilita que o API Gateway coloque itens na tabela do DynamoDB. Para este tutorial, o nome do perfil é data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG.

   • DDBTableName, que é o nome da tabela do DynamoDB. Para este tutorial, o nome da tabela é data-transformation-tutorial-cli-ddb.

   • ResourceId, que é o ID do recurso de animais de estimação em que os métodos GET e POST são expostos. Para este tutorial, o ID do recurso é efg456.

   • ApiId, que é o ID da API. Para este tutorial, o ID da API é abc123.

Como testar o método GET antes da transformação de dados

• Use o comando a seguir para testar o método GET.

  aws apigateway test-invoke-method --rest-api-id abc123 \
            --resource-id efg456 \
            --http-method GET

  A saída do teste mostrará o seguinte:

  [
    {
      "id": 1,
      "type": "dog",
      "price": 249.99
    },
    {
      "id": 2,
      "type": "cat",
      "price": 124.99
    },
    {
      "id": 3,
      "type": "fish",
      "price": 0.99
    }
  ]

  Você transformará esse resultado de acordo com o modelo de mapeamento em Modelo de mapeamento PetStore.

Como transformar a resposta de integração GET

• Use o comando a seguir para atualizar a resposta de integração do método GET. Substitua o rest-api-id e o resource-id pelos seus valores.

  Use o comando a seguir para criar uma resposta de integração.

  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]"}'

Como testar o método GET

• Use o comando a seguir para testar o método GET.

  aws apigateway test-invoke-method --rest-api-id abc123 \
    --resource-id efg456 \
    --http-method GET \
  

  A saída do teste mostrará a resposta 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
    }
  ]

Como criar um método POST

1. Use o comando a seguir para criar um novo método no recurso /pets.

   aws apigateway put-method --rest-api-id abc123 \
     --resource-id efg456 \
     --http-method POST \
     --authorization-type "NONE" \
   

   Esse método possibilitará que você envie informações sobre animais de estimação para a tabela do DynamoDB que você criou na pilha de AWS CloudFormation.

2. Use o comando a seguir para criar uma integração do AWS service (Serviço da AWS) no 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. Use o comando a seguir para criar uma resposta de método para uma chamada bem-sucedida do método POST.

   aws apigateway put-method-response --rest-api-id abc123 \
     --resource-id efg456 \
     --http-method POST \
     --status-code 200

4. Use o comando a seguir para criar uma resposta de integração para uma chamada bem-sucedida do 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\"}"}'

Como testar o método POST

• Use o comando a seguir para testar o 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\"}'

  A saída mostrará a mensagem de êxito.

Para excluir uma pilha do AWS CloudFormation

• Use o comando a seguir para excluir seus recursos de AWS CloudFormation.

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

Modelo AWS CloudFormation de transformação de dados concluído

O exemplo a seguir é um modelo de AWS CloudFormation completo, que cria uma API e uma tabela do DynamoDB com um recurso /pets com os métodos GET e POST.

• O método GET obterá dados do endpoint HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Os dados de saída serão transformados de acordo com o modelo de mapeamento em Modelo de mapeamento PetStore.

• O método POST possibilitará que o usuário POST informações sobre animais de estimação em uma tabela do DynamoDB usando um modelo de mapeamento.

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

Próximas etapas

Para explorar modelos de mapeamento mais complexos, consulte os exemplos a seguir:

• Veja modelos e modelos de mapeamento mais complexos com o exemplo de álbum de fotos Exemplo de álbum de fotos.

• Para obter mais informações sobre modelos, consulte Modelos de dados para APIs REST.

• Para ter informações sobre como mapear diferentes saídas de código de resposta, Configurar mapeamentos de dados de solicitação e resposta usando o console do API Gateway.

• Para ter informações sobre como definir mapeamentos de dados a partir dos dados de solicitação de método de uma API, Referência de variáveis de registro em log de acesso e modelo de mapeamento do API Gateway.