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 스택을 생성하려면
AWS CloudFormation 콘솔(https://console.aws.amazon.com/cloudformation
)을 엽니다. -
스택 생성을 선택한 다음 새 리소스 사용(표준)을 선택합니다.
-
템플릿 지정에서 템플릿 파일 업로드를 선택합니다.
-
다운로드한 템플릿을 선택합니다.
-
다음을 선택합니다.
-
스택 이름에
data-transformation-tutorial-console
을 입력하고 다음을 선택합니다. -
스택 옵션 구성에서 다음을 선택합니다.
-
기능의 경우 AWS CloudFormation이 계정에 IAM 리소스를 생성할 수 있음을 확인합니다.
-
제출을 선택합니다.
AWS CloudFormation은 템플릿에 지정된 리소스를 프로비저닝합니다. 리소스 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. AWS CloudFormation 스택 상태가 CREATE_COMPLETE인 경우 다음 단계로 넘어갈 준비가 된 것입니다.
GET
통합 응답을 테스트하는 방법
-
data-transformation-tutorial-console
의 AWS CloudFormation 스택에 있는 리소스 탭에서 API의 물리적 ID를 선택합니다. -
기본 탐색 창에서 리소스를 선택하고 GET 메서드를 선택합니다.
-
테스트 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
테스트 결과는 다음과 같습니다.
[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]
PetStor 매핑 템플릿:의 매핑 테이블에 따라 이 출력 데이터를 변환합니다.
GET
통합 응답을 변환하는 방법
-
통합 응답 탭을 선택합니다.
현재 정의된 매핑 템플릿이 없으므로 통합 응답은 변환되지 않습니다.
-
기본값 - 응답에서 편집을 선택합니다.
-
매핑 템플릿을 선택한 후 다음을 수행합니다.
매핑 템플릿 추가(Add mapping template)를 선택합니다.
콘텐츠 유형에
application/json
을 입력합니다.템플릿 본문에 다음을 입력합니다.
#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
메서드의 입력 데이터를 변환하는 방법
-
POST 메서드를 선택합니다.
-
통합 요청 탭을 선택한 다음 통합 요청 설정에서 편집을 선택합니다.
AWS CloudFormation 템플릿에 일부 통합 요청 필드가 채워져 있습니다.
-
통합 유형은 AWS 서비스입니다.
-
AWS 서비스는 DynamoDB입니다.
-
HTTP 메서드는
POST
입니다. -
작업은
PutItem
입니다. -
API Gateway가 DynamoDB 테이블에 항목을 넣을 수 있도록 하는 실행 역할은
data-transformation-tutorial-console-APIGatewayRole
입니다. API Gateway가 DynamoDB와 상호 작용하는 데 필요한 최소한의 권한을 가질 수 있도록 하기 위해 AWS CloudFormation이 생성한 역할입니다.
DynamoDB 테이블의 이름이 지정되지 않았습니다. 다음 단계에서 이름을 지정합니다.
-
요청 본문 패스스루에서 없음을 선택합니다.
이렇게 하면 API는 매핑 템플릿이 없는 Content-Types의 데이터를 거부합니다.
매핑 템플릿을 선택합니다.
콘텐츠 유형이
application/json
으로 설정되어 있습니다. 이는 application/json이 아닌 콘텐츠 유형은 API에서 거부함을 의미합니다. 통합 패스스루 동작에 관한 자세한 정보는 통합 패스스루 동작 섹션을 참조하세요.-
텍스트 편집기에 다음 코드를 입력합니다.
{ "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 검증 요청 단원을 참조하십시오. -
저장을 선택하여 매핑 템플릿을 저장합니다.
메서드 및 POST
메서드의 통합 응답을 추가하는 방법
AWS CloudFormation이 빈 메서드와 통합 응답을 만들었습니다. 이 응답을 편집하여 자세한 정보를 제공할 수 있습니다. 응답을 편집하는 방법에 대한 자세한 내용은 Amazon API Gateway API 요청 및 응답 데이터 매핑 참조 섹션을 참조하세요.
-
통합 응답 탭의 기본값 - 응답에서 편집을 선택합니다.
매핑 템플릿을 선택한 다음 매핑 템플릿 추가를 선택합니다.
Content-type에
application/json
을 입력합니다.코드 편집기에서 다음 출력 매핑 템플릿을 입력하여 출력 메시지를 보냅니다.
{ "message" : "Your response was recorded at $context.requestTime" }
컨텍스트 변수에 대한 자세한 내용은 데이터 모델, 권한 부여자, 매핑 템플릿, CloudWatch 액세스 로깅을 위한 $context 변수 섹션을 참조하세요.
저장을 선택하여 매핑 템플릿을 저장합니다.
POST
메서드 테스트
테스트 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
-
요청 본문에 다음 예를 입력합니다.
{ "id": "4", "type" : "dog", "price": "321" }
-
테스트를 선택합니다.
출력에 성공 메시지가 표시되어야 합니다.
https://console.aws.amazon.com/dynamodb/
에서 DynamoDB 콘솔을 열어 예시 항목이 테이블에 있는지 확인할 수 있습니다.
AWS CloudFormation 스택을 삭제하려면
AWS CloudFormation 콘솔(https://console.aws.amazon.com/cloudformation
)을 엽니다. -
AWS CloudFormation 스택을 선택합니다.
-
삭제를 선택한 다음 해당 선택을 확인합니다.
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을 설치
다음 명령을 사용하여 AWS CloudFormation 스택을 생성합니다.
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
-
AWS CloudFormation은 템플릿에 지정된 리소스를 프로비저닝합니다. 리소스 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 다음 명령을 실행하여 AWS CloudFormation 스택의 상태를 확인합니다.
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
-
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-idefg456
\ --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-idefg456
\ --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-idefg456
\ --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
메서드를 생성하는 방법
-
다음 명령을 사용하여
/pets
리소스에 새로운 메서드를 생성합니다.aws apigateway put-method --rest-api-id
abc123
\ --resource-idefg456
\ --http-method POST \ --authorization-type "NONE" \이 방법을 사용하면 AWS CloudFormation 스택에 생성한 DynamoDB 테이블로 반려동물 정보를 보낼 수 있습니다.
-
다음 명령을 사용하여
POST
메서드에 AWS 서비스 통합을 생성합니다.aws apigateway put-integration --rest-api-id
abc123
\ --resource-idefg456
\ --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\")} }}"}' -
다음 명령을 사용하여 성공적인
POST
메서드 호출에 대한 메서드 응답을 생성합니다.aws apigateway put-method-response --rest-api-id
abc123
\ --resource-idefg456
\ --http-method POST \ --status-code 200 -
다음 명령을 사용하여 성공적인
POST
메서드 호출에 대한 통합 응답을 생성합니다.aws apigateway put-integration-response --rest-api-id
abc123
\ --resource-idefg456
\ --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-idefg456
\ --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 매핑 템플릿과 액세스 로깅 변수 참조 섹션을 참조하세요.