API Gateway에서 데이터 변환 설정

이 섹션에서는 콘솔과 AWS CLI를 사용하여 통합 요청 및 응답을 변환하도록 매핑 템플릿을 설정하는 방법을 보여줍니다.

API Gateway 콘솔을 사용하여 데이터 변환 설정

이 자습서에서는 .zip 파일(data-transformation-tutorial-console.zip)을 사용하여 불완전한 API 및 DynamoDB 테이블을 생성합니다. 이 불완전한 API에는 GET 및 POST 메서드가 포함된 /pets 리소스가 있습니다.

• GET 메서드는 http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP 엔드포인트에서 데이터를 가져옵니다. 출력 데이터는 PetStor 매핑 템플릿:의 매핑 템플릿에 따라 변환됩니다.

• POST 메서드를 사용하면 사용자가 매핑 템플릿을 사용하여 Amazon DynamoDB 테이블에 POST 반려동물 정보를 입력할 수 있습니다.

AWS CloudFormation용 앱 생성 템플릿을 다운로드하고 압축을 해제합니다. 이 템플릿을 사용하여 반려동물 정보와 불완전한 API를 게시하기 위한 DynamoDB 테이블을 생성할 것입니다. API Gateway 콘솔에서 나머지 단계를 완료하게 됩니다.

AWS CloudFormation 스택을 생성하려면

1. AWS CloudFormation 콘솔(https://console.aws.amazon.com/cloudformation)을 엽니다.

2. 스택 생성을 선택한 다음 새 리소스 사용(표준)을 선택합니다.

3. 템플릿 지정에서 템플릿 파일 업로드를 선택합니다.

4. 다운로드한 템플릿을 선택합니다.

5. 다음을 선택합니다.

6. 스택 이름에 data-transformation-tutorial-console을 입력하고 다음을 선택합니다.

7. 스택 옵션 구성에서 다음을 선택합니다.

8. 기능의 경우 AWS CloudFormation이 계정에 IAM 리소스를 생성할 수 있음을 확인합니다.

9. 제출을 선택합니다.

AWS CloudFormation은 템플릿에 지정된 리소스를 프로비저닝합니다. 리소스 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. AWS CloudFormation 스택 상태가 CREATE_COMPLETE인 경우 다음 단계로 넘어갈 준비가 된 것입니다.

GET 통합 응답을 테스트하는 방법

1. data-transformation-tutorial-console의 AWS CloudFormation 스택에 있는 리소스 탭에서 API의 물리적 ID를 선택합니다.

2. 기본 탐색 창에서 리소스를 선택하고 GET 메서드를 선택합니다.

3. 테스트 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.

   테스트 결과는 다음과 같습니다.

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

   PetStor 매핑 템플릿:의 매핑 테이블에 따라 이 출력 데이터를 변환합니다.

GET 통합 응답을 변환하는 방법

1. 통합 응답 탭을 선택합니다.

   현재 정의된 매핑 템플릿이 없으므로 통합 응답은 변환되지 않습니다.

2. 기본값 - 응답에서 편집을 선택합니다.

3. 매핑 템플릿을 선택한 후 다음을 수행합니다.

   1. 매핑 템플릿 추가(Add mapping template)를 선택합니다.

   2. 콘텐츠 유형에 application/json을 입력합니다.

   3. 템플릿 본문에 다음을 입력합니다.

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

   Save(저장)를 선택합니다.

GET 통합 응답을 테스트하는 방법

• 테스트 탭을 선택한 다음 테스트를 선택합니다.

  테스트 출력에는 변환된 응답이 표시됩니다.

  [
    {
      "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
    }
  ]

POST 메서드의 입력 데이터를 변환하는 방법

1. POST 메서드를 선택합니다.

2. 통합 요청 탭을 선택한 다음 통합 요청 설정에서 편집을 선택합니다.

   AWS CloudFormation 템플릿에 일부 통합 요청 필드가 채워져 있습니다.

   • 통합 유형은 AWS 서비스입니다.

   • AWS 서비스는 DynamoDB입니다.

   • HTTP 메서드는 POST입니다.

   • 작업은 PutItem입니다.

   • API Gateway가 DynamoDB 테이블에 항목을 넣을 수 있도록 하는 실행 역할은 data-transformation-tutorial-console-APIGatewayRole입니다. API Gateway가 DynamoDB와 상호 작용하는 데 필요한 최소한의 권한을 가질 수 있도록 하기 위해 AWS CloudFormation이 생성한 역할입니다.

   DynamoDB 테이블의 이름이 지정되지 않았습니다. 다음 단계에서 이름을 지정합니다.

3. 요청 본문 패스스루에서 없음을 선택합니다.

   이렇게 하면 API는 매핑 템플릿이 없는 Content-Types의 데이터를 거부합니다.

4. 매핑 템플릿을 선택합니다.

5. 콘텐츠 유형이 application/json으로 설정되어 있습니다. 이는 application/json이 아닌 콘텐츠 유형은 API에서 거부함을 의미합니다. 통합 패스스루 동작에 관한 자세한 정보는 통합 패스스루 동작 섹션을 참조하세요.

6. 텍스트 편집기에 다음 코드를 입력합니다.

   {
       "TableName":"data-transformation-tutorial-console-ddb",
       "Item": {
           "id": {
               "N": $input.json("$.id")
           },
           "type": {
               "S": $input.json("$.type")
           },
           "price": {
               "N": $input.json("$.price")
           }
       }
   }

   이 템플릿은 테이블을 data-transformation-tutorial-console-ddb로 지정하고 항목을 id, type 및 price로 설정합니다. 항목은 POST 메서드 본문에서 가져옵니다. 또한 매핑 템플릿을 만드는 데 데이터 모델을 사용할 수 있습니다. 자세한 내용은 API Gateway의 REST API API 검증 요청 단원을 참조하십시오.

7. 저장을 선택하여 매핑 템플릿을 저장합니다.

메서드 및 POST 메서드의 통합 응답을 추가하는 방법

AWS CloudFormation이 빈 메서드와 통합 응답을 만들었습니다. 이 응답을 편집하여 자세한 정보를 제공할 수 있습니다. 응답을 편집하는 방법에 대한 자세한 내용은 Amazon API Gateway API 요청 및 응답 데이터 매핑 참조 섹션을 참조하세요.

1. 통합 응답 탭의 기본값 - 응답에서 편집을 선택합니다.

2. 매핑 템플릿을 선택한 다음 매핑 템플릿 추가를 선택합니다.

3. Content-type에 application/json을 입력합니다.

4. 코드 편집기에서 다음 출력 매핑 템플릿을 입력하여 출력 메시지를 보냅니다.

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

   컨텍스트 변수에 대한 자세한 내용은 데이터 모델, 권한 부여자, 매핑 템플릿, CloudWatch 액세스 로깅을 위한 $context 변수 섹션을 참조하세요.

5. 저장을 선택하여 매핑 템플릿을 저장합니다.

POST 메서드 테스트

테스트 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.

1. 요청 본문에 다음 예를 입력합니다.

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

2. 테스트를 선택합니다.

   출력에 성공 메시지가 표시되어야 합니다.

   https://console.aws.amazon.com/dynamodb/에서 DynamoDB 콘솔을 열어 예시 항목이 테이블에 있는지 확인할 수 있습니다.

AWS CloudFormation 스택을 삭제하려면

1. AWS CloudFormation 콘솔(https://console.aws.amazon.com/cloudformation)을 엽니다.

2. AWS CloudFormation 스택을 선택합니다.

3. 삭제를 선택한 다음 해당 선택을 확인합니다.

AWS CLI를 사용하여 데이터 변환 설정

이 자습서에서는 .zip 파일(data-transformation-tutorial-cli.zip)을 사용하여 불완전한 API 및 DynamoDB 테이블을 생성합니다. 이 불완전한 API에는 http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP 엔드포인트와 통합된 GET 메서드가 포함된 /pets 리소스가 있습니다. DynamoDB 테이블에 연결할 POST 메서드를 생성하고 매핑 템플릿을 사용하여 DynamoDB 테이블에 데이터를 입력합니다.

• PetStor 매핑 템플릿:의 매핑 템플릿에 따라 출력 데이터를 변화합니다.

• 사용자가 매핑 템플릿을 사용하여 Amazon DynamoDB 테이블에 POST 반려동물 정보를 입력할 수 있도록 POST 메서드를 생성합니다.

AWS CloudFormation 스택을 생성하려면

AWS CloudFormation용 앱 생성 템플릿을 다운로드하고 압축을 해제합니다.

다음 자습서를 완료하려면 AWS Command Line Interface(AWS CLI) 버전 2가 필요합니다.

긴 명령의 경우 이스케이프 문자(\)를 사용하여 명령을 여러 행으로 분할합니다.

참고

Windows에서는 일반적으로 사용하는 일부 Bash CLI 명령(예: zip)은 운영 체제의 기본 제공 터미널에서 지원되지 않습니다. Ubuntu와 Bash의 Windows 통합 버전을 가져오려면 Linux용 Windows Subsystem을 설치합니다. 이 안내서의 예제 CLI 명령은 Linux 형식을 사용합니다. Windows CLI를 사용하는 경우 인라인 JSON 문서를 포함하는 명령의 형식을 다시 지정해야 합니다.

1. 다음 명령을 사용하여 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은 템플릿에 지정된 리소스를 프로비저닝합니다. 리소스 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 다음 명령을 실행하여 AWS CloudFormation 스택의 상태를 확인합니다.

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

3. AWS CloudFormation 스택의 상태가 StackStatus: "CREATE_COMPLETE"이면 다음 명령을 사용하여 향후 단계에 대한 관련 출력 값을 검색합니다.

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

   출력 값은 다음과 같습니다.

   • ApiRole은 API Gateway가 DynamoDB 테이블에 항목을 배치할 수 있도록 하는 역할 이름입니다. 이 자습서에서 역할 이름은 data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG입니다.

   • DDBTableName은 DynamoDB 테이블의 이름입니다. 이 자습서에서 테이블 이름은 data-transformation-tutorial-cli-ddb입니다.

   • ResourceId는 GET 및 POST 메서드가 노출되는 반려동물 리소스의 ID입니다. 이 자습서에서 리소스 ID는 efg456입니다.

   • APIID는 API의 ID입니다. 이 자습서에서 API ID는 abc123입니다.

데이터 변환 전에 GET 메서드를 테스트하는 방법

• 다음 명령을 사용하여 GET 메서드를 테스트합니다.

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

  테스트의 출력은 다음과 같습니다.

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

  PetStor 매핑 템플릿:의 매핑 테이블에 따라 이 출력 데이터를 변환합니다.

GET 통합 응답을 변환하는 방법

• 다음 명령을 사용하여 GET 메서드 통합 응답을 업데이트합니다. rest-api-id와 resource-id를 실제 값으로 바꿉니다.

  다음 명령을 사용하여 통합 응답을 생성합니다.

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

GET 메서드를 테스트하는 방법

• 다음 명령을 사용하여 GET 메서드를 테스트합니다.

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

  테스트 출력에는 변환된 응답이 표시됩니다.

  [
    {
      "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
    }
  ]

POST 메서드를 생성하는 방법

1. 다음 명령을 사용하여 /pets 리소스에 새로운 메서드를 생성합니다.

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

   이 방법을 사용하면 AWS CloudFormation 스택에 생성한 DynamoDB 테이블로 반려동물 정보를 보낼 수 있습니다.

2. 다음 명령을 사용하여 POST 메서드에 AWS 서비스 통합을 생성합니다.

   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. 다음 명령을 사용하여 성공적인 POST 메서드 호출에 대한 메서드 응답을 생성합니다.

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

4. 다음 명령을 사용하여 성공적인 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\"}"}'

POST 메서드를 테스트하는 방법

• 다음 명령을 사용하여 POST 메서드를 테스트합니다.

  aws apigateway test-invoke-method --rest-api-id abc123 \
    --resource-id efg456 \
    --http-method POST \
    --body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'

  출력에 성공 메시지가 표시됩니다.

AWS CloudFormation 스택을 삭제하려면

• 다음 명령을 사용하여 AWS CloudFormation 리소스를 삭제합니다.

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

완성된 데이터 변환 AWS CloudFormation 템플릿

다음 예시는 GET 및 POST 메서드가 있는 /pets 리소스가 포함된 DynamoDB 테이블과 API를 생성하는 완성된 AWS CloudFormation 템플릿입니다.

• GET 메서드는 http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP 엔드포인트에서 데이터를 가져옵니다. 출력 데이터는 PetStor 매핑 템플릿:의 매핑 템플릿에 따라 변환됩니다.

• POST 메서드를 사용하면 사용자가 매핑 템플릿을 사용하여 DynamoDB 테이블에 POST 반려동물 정보를 입력할 수 있습니다.

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

다음 단계

더 복잡한 매핑 템플릿을 알아보려면 다음 예를 참조하세요.

• 예시 사진 앨범(사진 앨범 예시)을 통해 더 복잡한 모델과 매핑 템플릿을 볼 수 있습니다.

• 모델에 대한 자세한 내용은 REST API에 대한 데이터 모델 섹션을 참조하세요.

• 다양한 응답 코드 출력을 매핑하는 방법에 대한 자세한 내용은 API Gateway 콘솔을 사용하여 요청 및 응답 데이터 매핑 설정 섹션을 참조하세요.

• API의 메서드 요청 데이터에서 데이터 매핑을 설정하는 방법에 대한 자세한 내용은 API Gateway 매핑 템플릿과 액세스 로깅 변수 참조 섹션을 참조하세요.