# API Gateway에서 REST API 개발
Amazon API Gateway에서 Amazon API Gateway [리소스](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)로 알려진 프로그래밍 가능 엔터티 모음으로 REST API를 구축합니다. 예를 들어 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스를 사용하여 [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) 엔터티 모음을 포함할 수 있는 API를 나타냅니다.
각 `Resource` 엔터티마다 [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 리소스가 하나 이상 있을 수 있습니다. `Method`는 클라이언트가 제출한 수신 요청이며 경로 파라미터, 헤더 또는 쿼리 문자열 파라미터와 같은 요청 파라미터를 포함할 수 있습니다. 또한 HTTP 메서드에 따라 요청에 본문이 포함될 수 있습니다. 메서드는 클라이언트가 노출된 `Resource`에 액세스하는 방법을 정의합니다. `Method`를 통합 엔드포인트라고도 하는 백엔드 엔드포인트에 통합하려면 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스를 생성합니다. 그러면 수신 요청이 지정된 통합 엔드포인트 URI로 전달됩니다. 필요한 경우 백엔드 요구 사항을 충족하도록 요청 파라미터 또는 요청 본문을 변환하거나 프록시 통합을 만들 수 있습니다. 여기서 API Gateway는 전체 요청을 표준화된 형식으로 통합 엔드포인트 URI에 전송한 다음 클라이언트에 직접 응답을 전송합니다.
응답에 대해 [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) 리소스를 만들어 클라이언트가 수신하는 응답을 표시하고 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스를 만들어 백엔드에서 반환되는 응답을 표시할 수 있습니다. 통합 응답을 사용하여 클라이언트에 데이터를 반환하기 전에 백엔드 응답 데이터를 변환하거나 클라이언트에 백엔드 응답을 있는 그대로 전달할 수 있습니다.
## REST API에 대한 리소스 예제
다음 다이어그램은 API Gateway가 HTTP 프록시에 대해 이 요청/응답 모델을 구현하고 `GET /pets` 리소스에 대해 HTTP 비프록시 통합을 구현하는 방법을 보여줍니다. 클라이언트는 `x-version:beta` 헤더를 API Gateway로 전송하고 API Gateway는 `204` 상태 코드를 클라이언트로 전송합니다.
비프록시 통합에서 API Gateway는 통합 요청 및 통합 응답을 수정하여 백엔드 요구 사항을 충족하기 위해 데이터 변환을 수행합니다. 비프록시 통합에서는 메서드 요청의 본문에 액세스할 수 있지만 통합 요청에서는 변환할 수 있습니다. 통합 엔드포인트가 본문과 함께 응답을 반환하면 통합 응답에서 응답에 액세스하고 이를 변환합니다. 메서드 응답에서 본문을 수정할 수 없습니다.
프록시 통합에서 통합 엔드포인트는 요청 및 응답을 수정합니다. API Gateway는 통합 요청 또는 통합 응답을 수정하지 않고 수신 요청을 백엔드로 있는 그대로 보냅니다.
통합 유형에 관계없이 클라이언트는 API Gateway에 요청을 전송했으며 API Gateway는 동기식으로 응답했습니다.
------
#### [ Non-proxy integration ]
![\[API Gateway 비프록시 통합 다이어그램\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/develop-non-proxy.png)
------
#### [ Proxy integration ]
![\[API Gateway 프록시 통합 다이어그램\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/develop-proxy.png)
------
다음 예제 실행 로그는 이전 예제에서 로깅할 API Gateway를 보여줍니다. 명확성을 위해 일부 값과 초기 로그가 제거되었습니다.
------
#### [ Non-proxy integration ]
```
Wed Feb 12 23:56:44 UTC 2025 : Starting execution for request: abcd-1234-5678
Wed Feb 12 23:56:44 UTC 2025 : HTTP Method: GET, Resource Path: /pets
Wed Feb 12 23:56:44 UTC 2025 : Method request path: {}
Wed Feb 12 23:56:44 UTC 2025 : Method request query string: {}
Wed Feb 12 23:56:44 UTC 2025 : Method request headers: {x-version=beta}
Wed Feb 12 23:56:44 UTC 2025 : Method request body before transformations:
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request headers: {app-version=beta}
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request body after transformations:
Wed Feb 12 23:56:44 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:56:45 UTC 2025 : Received response. Status: 200, Integration latency: 123 ms
Wed Feb 12 23:56:45 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:56:45 GMT}
Wed Feb 12 23:56:45 UTC 2025 : Endpoint response body before transformations:
Wed Feb 12 23:56:45 UTC 2025 : Method response body after transformations: (null)
Wed Feb 12 23:56:45 UTC 2025 : Method response headers: {X-Amzn-Trace-Id=Root=1-abcd-12345}
Wed Feb 12 23:56:45 UTC 2025 : Successfully completed execution
Wed Feb 12 23:56:45 UTC 2025 : Method completed with status: 204
```
------
#### [ Proxy integration ]
```
Wed Feb 12 23:59:42 UTC 2025 : Starting execution for request: abcd-1234-5678
Wed Feb 12 23:59:42 UTC 2025 : HTTP Method: GET, Resource Path: /pets
Wed Feb 12 23:59:42 UTC 2025 : Method request path: {}
Wed Feb 12 23:59:42 UTC 2025 : Method request query string: {}
Wed Feb 12 23:59:42 UTC 2025 : Method request headers: {x-version=beta}
Wed Feb 12 23:59:42 UTC 2025 : Method request body before transformations:
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request headers: { x-version=beta}
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request body after transformations:
Wed Feb 12 23:59:42 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:59:43 UTC 2025 : Received response. Status: 204, Integration latency: 123 ms
Wed Feb 12 23:59:43 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT}
Wed Feb 12 23:59:43 UTC 2025 : Endpoint response body before transformations:
Wed Feb 12 23:59:43 UTC 2025 : Method response body after transformations:
Wed Feb 12 23:59:43 UTC 2025 : Method response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT}
Wed Feb 12 23:59:43 UTC 2025 : Successfully completed execution
Wed Feb 12 23:59:43 UTC 2025 : Method completed with status: 204
```
------
유사한 API를 가져와서 AWS Management Console에서 테스트하려면 [예제 API](api-gateway-create-api-from-example.md)를 참조하시기 바랍니다.
## 개발용 추가 REST API 기능
API Gateway는 REST API 개발을 위한 추가 기능을 지원합니다. 예를 들어 고객이 API를 이해하는 데 도움이 되도록 API에 대한 설명서를 제공할 수 있습니다. 이를 활성화하려면 지원되는 API 엔터티에 대한 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가하세요.
클라이언트가 API를 호출하는 방법을 제어하려면 [IAM 권한](permissions.md), [Lambda 권한 부여자](apigateway-use-lambda-authorizer.md), 또는 [Amazon Cognito 사용자 풀](apigateway-integrate-with-cognito.md)을 사용합니다. API 사용을 측정하려면 API 요청을 조절하도록 [사용량 계획](api-gateway-api-usage-plans.md)을 설정하세요. API를 생성 또는 업데이트할 때 이를 활성화할 수 있습니다.
다음 다이어그램은 REST API 개발에 사용할 수 있는 기능과 요청/응답 모델에서 이러한 기능이 구성된 위치를 보여줍니다.
![\[API Gateway 기능 다이어그램\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/develop-features.png)
API를 생성하는 방법 소개는 [자습서: Lambda 프록시 통합을 통해 REST API 생성](api-gateway-create-api-as-simple-proxy-for-lambda.md) 섹션을 참조하세요. REST API를 개발하는 동안 사용할 수 있는 API Gateway의 기능에 대한 자세한 내용은 다음 주제를 참조하세요. 이러한 주제에는 개념 정보와 API Gateway 콘솔, API Gateway REST API, AWS CLI 또는 AWS SDK 중 하나를 사용하여 수행할 수 있는 절차가 포함되어 있습니다.
**Topics**
+ [REST API에 대한 리소스 예제](#rest-api-develop-example)
+ [개발용 추가 REST API 기능](#rest-api-develop-details)
+ [API Gateway의 REST API에 대한 API 엔드포인트 유형](api-gateway-api-endpoint-types.md)
+ [API Gateway의 REST API 보안 정책](apigateway-security-policies.md)
+ [API Gateway의 REST API에 대한 IP 주소 유형](api-gateway-ip-address-type.md)
+ [API Gateway의 REST API 메서드](how-to-method-settings.md)
+ [API Gateway에서 REST API에 대한 액세스 제어 및 관리](apigateway-control-access-to-api.md)
+ [API Gateway에서 REST API 통합](how-to-integration-settings.md)
+ [API Gateway의 REST API API 검증 요청](api-gateway-method-request-validation.md)
+ [API Gateway에서 REST API의 데이터 변환](rest-api-data-transformations.md)
+ [API Gateway의 REST API에 대한 게이트웨이 응답](api-gateway-gatewayResponse-definition.md)
+ [API Gateway의 REST API CORS](how-to-cors.md)
+ [API Gateway의 REST API에 대한 이진 미디어 유형](api-gateway-payload-encodings.md)
+ [API Gateway에서 REST API 간접 호출](how-to-call-api.md)
+ [API Gateway에서 OpenAPI를 사용하여 REST API 개발](api-gateway-import-api.md)
# API Gateway의 REST API에 대한 API 엔드포인트 유형
*[API 엔드포인트](api-gateway-basic-concept.md#apigateway-definition-api-endpoints)* 유형은 API의 호스트 이름을 나타냅니다. API 엔드포인트 유형은 대다수 API 트래픽의 출처에 따라 *엣지 최적화*, *리전* 또는 *프라이빗* 엔드포인트일 수 있습니다.
## 엣지 최적화 API 엔드포인트
*[엣지 최적화 API 엔드포인트](api-gateway-basic-concept.md#apigateway-definition-edge-optimized-api-endpoint)*는 일반적으로 클라이언트가 지리적으로 분산된 경우 도움이 되는 가장 가까운 CloudFront 접속 지점(POP)으로 요청을 라우팅합니다. 이것은 API Gateway REST API의 기본 엔드포인트 유형입니다.
엣지 최적화 API는 [HTTP 헤더](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)의 이름을 대문자로 처리합니다(예: `Cookie`).
CloudFront에서는 요청을 오리진에 전달하기 전에 쿠키 이름을 기준으로 HTTP 쿠키를 일반 순서로 정렬합니다. CloudFront 가 쿠키를 처리하는 방법에 대해서는 [쿠키를 기반으로 콘텐츠 캐싱](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html)을 참조하세요.
엣지 최적화 API를 위해 사용되는 사용자 지정 도메인 이름은 모든 리전에 적용됩니다.
## 리전 API 엔드포인트
*[리전 API 엔드포인트](api-gateway-basic-concept.md#apigateway-definition-regional-api-endpoint)*는 동일 리전의 클라이언트를 위한 것입니다. EC2 인스턴스를 실행하는 클라이언트가 동일 리전에서 API를 직접적으로 호출하거나 API가 수요가 큰 소수의 클라이언트에게 서비스를 제공하기 위한 것이라면 리전 API는 연결 오버헤드를 줄입니다.
리전 API에 대해 API가 배포된 리전별로 고유한 사용자 지정 도메인 이름이 사용됩니다. 여러 리전에 배포된 리전 API를 배포하는 경우, 모든 리전에서 동일한 사용자 지정 도메인 이름을 사용할 수 있습니다. Amazon Route 53과 함께 사용자 지정 도메인을 사용하여 [지연 시간 기반 라우팅](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-latency) 등의 작업을 수행할 수 있습니다. 자세한 내용은 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 및 [API Gateway API에서 엣지 최적화 사용자 지정 도메인 이름 설정](how-to-edge-optimized-custom-domain-name.md) 단원을 참조하세요.
리전 API 엔드포인트는 모든 헤더 이름을 그대로 전달합니다.
**참고**
API 클라이언트가 지리적으로 분산되어 있는 경우, API Gateway가 API를 서비스 제어 CloudFront 배포와 연결하지 않도록 하기 위해 리전 API 엔드포인트를 자체 Amazon CloudFront 배포와 함께 사용할 수 있습니다. 이 사용 사례에 대한 자세한 내용은 [고유의 CloudFront 배포를 사용하여 API Gateway를 설정하려면 어떻게 해야 합니까?](https://repost.aws/knowledge-center/api-gateway-cloudfront-distribution)를 참조하세요.
## 프라이빗 API 엔드포인트
*[프라이빗 API 엔드포인트](api-gateway-basic-concept.md#apigateway-definition-private-api-endpoint)*는 인터페이스 VPC 종단점을 사용해서 Amazon Virtual Private Cloud(VPC)에서만 액세스할 수 있는 API 엔드포인트입니다. 이때 이 엔드포인트는 사용자가 VPC에서 만든 엔드포인트 네트워크 인터페이스(ENI)입니다. 자세한 내용은 [API Gateway의 프라이빗 REST API](apigateway-private-apis.md) 단원을 참조하세요.
프라이빗 API 엔드포인트는 모든 헤더 이름을 그대로 전달합니다.
# API Gateway에서 퍼블릭 또는 프라이빗 API 엔드포인트 유형 변경
API 엔드포인트 유형을 변경하려면 API의 구성을 업데이트해야 합니다. API Gateway 콘솔, AWS CLI 또는 API Gateway용 AWS SDK를 사용하여 기존 API 유형을 변경할 수 있습니다. 이 시간 동안 API를 사용할 수 있지만 현재 변경이 완료될 때까지 엔드포인트 유형을 다시 변경할 수는 없습니다.
다음과 같은 엔드포인트 유형 변경이 지원됩니다.
+ 엣지 최적화에서 리전 또는 프라이빗으로 변경
+ 리전에서 엣지 최적화 또는 프라이빗으로 변경
+ 프라이빗에서 리전으로 변경
프라이빗 API를 엣지 최적화된 API로 바꿀 수는 없습니다.
퍼블릭 API의 유형을 엣지 최적화에서 리전으로, 또는 리전에서 엣지 최적화로 변경할 때는 엣지 최적화된 API가 리전 API와 다르게 동작할 수 있다는 점에 유의해야 합니다. 예를 들어 엣지 최적화 API는 `Content-MD5` 헤더를 제거합니다. 백엔드로 전달되는 모든 MD5 해시 값은 요청 문자열 파라미터 또는 본문 속성으로 표현될 수 있습니다. 그러나 리전 API는 헤더 이름을 다른 이름으로 다시 매핑하기는 하지만 이 헤더를 빠져나갑니다. 그 차이를 이해하면 엣지 최적화 API를 리전 API로 또는 리전 API를 엣지 최적화 API로 업데이트하는 방법을 결정하는 데 도움이 됩니다.
**Topics**
+ [API Gateway 콘솔을 사용하여 API 엔드포인트 유형 변경](#migrate-api-using-console)
+ [AWS CLI를 사용하여 API 엔드포인트 유형 변경](#migrate-api-using-aws-cli)
## API Gateway 콘솔을 사용하여 API 엔드포인트 유형 변경
API의 API 엔드포인트 유형을 변경하려면 다음 단계 세트 중 하나를 수행하세요.
**지역에서 엣지 최적화로 또는 그 반대로 퍼블릭 엔드포인트를 전환하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. **API 설정**을 선택합니다.
1. **API 세부 정보** 섹션에서 **편집**을 선택합니다.
1. **API 엔드포인트 유형**으로 **엣지 최적화** 또는 **지역**을 선택합니다.
1. **변경 사항 저장**을 선택합니다.
1. API를 다시 배포하여 변경 사항을 적용합니다.
**프라이빗 엔드포인트를 리전 엔드포인트로 전환하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. API의 리소스 정책에서 VPC 또는 VPC 엔드포인트에 대한 언급을 삭제하여 VPC 내부는 물론 VPC 외부에서 오는 API 호출도 성공하도록 합니다.
1. **API 설정**을 선택합니다.
1. **API 세부 정보** 섹션에서 **편집**을 선택합니다.
1. **API 엔드포인트 유형**에서 **지역**을 선택합니다.
1. **변경 사항 저장**을 선택합니다.
1. API에서 리소스 정책을 제거합니다.
1. API를 다시 배포하여 변경 사항을 적용합니다.
엔드포인트 유형을 프라이빗에서 리전으로 마이그레이션하기 때문에 API Gateway는 IP 주소 유형을 IPv4로 변경합니다. 자세한 내용은 [API Gateway의 REST API에 대한 IP 주소 유형](api-gateway-ip-address-type.md) 섹션을 참조하세요.
**리전 엔드포인트를 프라이빗 엔드포인트로 전환하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. VPC 또는 VPC 엔드포인트에 대한 액세스 권한을 부여하는 리소스 정책을 생성합니다. 자세한 내용은 [3단계: 프라이빗 API에 대한 리소스 정책 설정](apigateway-private-api-create.md#apigateway-private-api-set-up-resource-policy) 섹션을 참조하세요.
1. **API 설정**을 선택합니다.
1. **API 세부 정보** 섹션에서 **편집**을 선택합니다.
1. **API 엔드포인트 유형**에서 **프라이빗**을 선택합니다.
1. (옵션) **VPC 엔드포인트 ID**의 경우 프라이빗 API와 연결하려는 VPC 엔드포인트 ID를 선택합니다.
1. **변경 사항 저장**을 선택합니다.
1. API를 다시 배포하여 변경 사항을 적용합니다.
엔드포인트 유형을 리전에서 프라이빗으로 마이그레이션하기 때문에 API Gateway는 IP 주소 유형을 듀얼 스택으로 변경합니다. 자세한 내용은 [API Gateway의 REST API에 대한 IP 주소 유형](api-gateway-ip-address-type.md) 섹션을 참조하세요.
## AWS CLI를 사용하여 API 엔드포인트 유형 변경
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 엣지 최적화 API를 리전 API로 업데이트합니다.
```
aws apigateway update-rest-api \
--rest-api-id a1b2c3 \
--patch-operations op=replace,path=/endpointConfiguration/types/EDGE,value=REGIONAL
```
성공적인 응답에는 다음과 같이 `200 OK` 상태 코드와 페이로드가 있습니다.
```
{
"createdDate": "2017-10-16T04:09:31Z",
"description": "Your first API with Amazon API Gateway. This is a sample API that integrates via HTTP with our demo Pet Store endpoints",
"endpointConfiguration": {
"types": "REGIONAL"
},
"id": "a1b2c3",
"name": "PetStore imported as edge-optimized"
}
```
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 리전 API를 엣지 최적화 API로 업데이트합니다.
```
aws apigateway update-rest-api \
--rest-api-id a1b2c3 \
--patch-operations op=replace,path=/endpointConfiguration/types/REGIONAL,value=EDGE
```
[put-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-rest-api.html)는 API 정의를 업데이트하기 위한 것이므로 API 엔드포인트 유형을 업데이트하는 데는 적용할 수 없습니다.
# API Gateway의 REST API 보안 정책
보안 정책은 API Gateway가 제공하는 최소 TLS 버전과 암호 제품군의 사전 정의된 조합입니다.** 클라이언트가 API 또는 사용자 맞춤형 도메인 이름에 대해 TLS 핸드셰이크를 설정할 때, 보안 정책은 API Gateway가 허용하는 TLS 버전 및 암호 제품군을 강제 적용합니다. 보안 정책은 API 및 사용자 지정 도메인 이름을 클라이언트와 서버 간의 변조 및 도청과 같은 네트워크 보안 문제로부터 보호합니다.
API Gateway는 레거시 보안 정책과 향상된 보안 정책을 지원합니다. `TLS_1_0` 및 `TLS_1_2`는 레거시 보안 정책입니다. 이전 버전과의 호환성을 위해 이러한 보안 정책을 사용합니다. `SecurityPolicy_`로 시작하는 모든 정책은 향상된 보안 정책입니다. 규제 워크로드, 고급 거버넌스 또는 양자 내성 암호를 사용하려면 이러한 정책을 사용합니다. 향상된 보안 정책을 사용하는 경우 추가 거버넌스를 위해 엔드포인트 액세스 모드도 설정해야 합니다. 자세한 내용은 [엔드포인트 액세스 모드](#apigateway-security-policies-endpoint-access-mode) 섹션을 참조하세요.
## API Gateway가 보안 정책을 적용하는 방법
다음 예제에서는 API Gateway가 보안 정책을 예로 사용하여 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책을 적용하는 방법을 보여 줍니다.
이 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책은 TLS 1.3 트래픽을 허용하고 TLS 1.2 및 TLS 1.0 트래픽은 거부합니다. TLS 1.3 트래픽의 경우 보안 정책은 다음 암호 그룹을 허용합니다.
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
API Gateway는 다른 암호 그룹을 허용하지 않습니다. 예를 들어 보안 정책은 암호 제품군을 사용하는 모든 TLS `AES128-SHA` 1.3 트래픽을 거부합니다. 지원되는 TLS 버전 및 암호에 대한 자세한 내용은 [지원되는 보안 정책](apigateway-security-policies-list.md) 섹션을 참조하세요.
API Gateway에 액세스하는 데 사용되는 TLS 프로토콜 및 암호 클라이언트를 모니터링하려면 액세스 로그에서 `$context.tlsVersion` 및 `$context.cipherSuite` 컨텍스트 변수를 사용할 수 있습니다. 자세한 내용은 [API Gateway에서 REST API 모니터링](rest-api-monitor.md) 섹션을 참조하세요.
## 엔드포인트 액세스 모드
엔드포인트 액세스 모드는 `SecurityPolicy_`로 시작하는 향상된 보안 정책을 사용하는 모든 REST API 또는 사용자 지정 도메인 이름에 대해 지정해야 하는 추가 파라미터입니다. 리소스를 생성하거나 보안 정책을 레거시 정책에서 향상된 정책으로 변경할 때 이 작업을 수행합니다.
엔드포인트 액세스 모드가 `STRICT`로 설정된 경우 REST API 또는 사용자 지정 도메인 이름에 대한 모든 요청은 다음 검사를 통과해야 합니다.
+ 요청은 리소스와 동일한 API Gateway 엔드포인트 유형에서 시작되어야 합니다. 이는 리전, 엣지 최적화 또는 프라이빗 엔드포인트에서 발생할 수 있습니다.
+ 리전 또는 프라이빗 엔드포인트를 사용하는 경우 API Gateway는 SNI 호스트 일치를 사용합니다. 엣지 최적화 엔드포인트를 사용하는 경우 API Gateway는 CloudFront의 도메인 프런트닝 보호를 준수합니다. 자세한 내용은 [도메인 프론팅](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions)을 참조하세요.
이러한 조건 중 하나가 충족되지 않으면 API Gateway는 요청을 거부합니다. 가능하면 `STRICT` 엔드포인트 액세스 모드를 사용하는 것이 좋습니다.
엄격한 엔드포인트 액세스 모드를 사용하도록 기존 API 또는 도메인 이름을 마이그레이션하려면 먼저 보안 정책을 향상된 보안 정책으로 업데이트하고 엔드포인트 액세스 모드를 `BASIC`으로 설정한 상태로 유지합니다. 트래픽 및 액세스 로그를 검증한 후 엔드포인트 액세스 모드를 `STRICT`로 설정합니다. 엔드포인트 액세스 모드를 `STRICT`에서 `BASIC`으로 마이그레이션하면 변경 사항이 전파됨에 따라 약 15분 동안 엔드포인트를 사용할 수 없습니다.
특정 애플리케이션 아키텍처에 대해 엔드포인트 액세스 모드를 `STRICT`로 설정해서는 안 되며, 대신 엔드포인트 액세스 모드를 `BASIC`으로 설정해야 합니다. 다음 표에는 REST API 또는 사용자 지정 도메인 이름이 `STRICT` 엔드포인트 액세스 모드를 사용할 수 있도록 몇 가지 애플리케이션 아키텍처와 권장 사항이 나와 있습니다.
| 아키텍처 | 권장되는 마이그레이션 |
| --- | --- |
| VPC 엔드포인트를 사용하여 퍼블릭 사용자 지정 도메인 이름에 액세스합니다. | 이 아키텍처는 교차 엔드포인트 유형 트래픽을 사용합니다. [API Gateway의 프라이빗 API에 대한 사용자 지정 도메인 이름](apigateway-private-custom-domains.md)으로 마이그레이션하는 것을 권장합니다. |
| 메서드를 사용하여 사용자 지정 도메인 이름 또는 프라이빗 DNS 이름을 사용하지 않는 프라이빗 API를 간접적으로 호출합니다. | 이 아키텍처는 호스트 헤더와 TLS 핸드셰이크에 사용되는 SNI 간에 불일치를 생성하고 CloudFront의 도메인 프런트닝 제한을 통과하지 않습니다. 프라이빗 DNS를 사용하도록 VPC를 마이그레이션하는 것이 좋습니다. |
| 도메인 샤딩을 사용하여 여러 도메인 또는 하위 도메인에 콘텐츠를 배포합니다. | 이 아키텍처는 호스트 헤더와 TLS 핸드셰이크에 사용되는 SNI 간에 불일치를 생성하고 CloudFront의 도메인 프런트닝 제한을 통과하지 않습니다. 이러한 안티 패턴을 사용하지 않고 `HTTP/2`를 사용할 것을 권장합니다. |
엔드포인트 액세스 모드 사용에 대한 고려 사항은 다음과 같습니다.
+ API 또는 도메인 이름의 엔드포인트 액세스 모드가 `STRICT`인 경우 엔드포인트 유형을 변경할 수 없습니다. 엔드포인트 유형을 변경하려면 먼저 엔드포인트 액세스 모드를 `BASIC`으로 변경합니다.
+ 엔드포인트 액세스 모드를 `BASIC`에서 `STRICT`로 변경하면 API Gateway가 엄격한 엔드포인트 액세스 모드를 적용하는 데 15분의 지연이 발생합니다.
+ `SecurityPolicy_`로 시작하는 정책에서 레거시 정책으로 보안 정책을 변경하는 경우 엔드포인트 액세스 모드를 `""`로 설정 해제해야 합니다.
## 고려 사항
API Gateway의 REST API에 대한 보안 정책에 대한 고려 사항은 다음과 같습니다.
+ OpenAPI 정의 파일에서 보안 정책을 가져올 수 있습니다. 자세한 내용은 [x-amazon-apigateway-endpoint-access-modex-amazon-apigateway-security-policy](openapi-extensions-security-policy.md) 섹션을 참조하세요.
+ API는 API와 보안 정책이 다른 사용자 지정 도메인 이름에 매핑할 수 있습니다. 해당 사용자 지정 도메인 이름을 간접적으로 호출하면 API Gateway는 API의 보안 정책을 사용하여 TLS 핸드셰이크를 협상합니다. 기본 API 엔드포인트를 비활성화하면 직접 호출자가 API를 간접적으로 호출하는 방법에 영향을 미칠 수 있습니다.
+ 보안 정책을 변경하는 경우 업데이트가 완료되는 데 약 15분이 걸립니다. API의 `apiStatus`를 모니터링할 수 있습니다. API가 업데이트되면 `apiStatus`는 `UPDATING`이고 완료되면 `AVAILABLE`이 됩니다. API 상태가 `UPDATING`인 경우에도 API를 간접적으로 호출할 수 있습니다.
+ API Gateway는 모든 API에서 보안 정책을 지원합니다. 하지만 REST API에 대해서만 보안 정책을 선택할 수 있습니다. API Gateway는 HTTP 또는 WebSocket API에 대한 `TLS_1_2` 보안 정책만 지원합니다.
+ API에 대한 보안 정책은 `TLS_1_0`에서 `TLS_1_2`로 업데이트할 수 없습니다.
+ 일부 보안 정책은 ECDSA 및 RSA 암호 제품군을 모두 지원합니다. 사용자 지정 도메인 이름과 함께 이 유형의 정책을 사용하는 경우 암호 그룹은 고객이 제공한 인증서 키 유형인 RSA 또는 ECDSA와 일치합니다. REST API에서 이 유형의 정책을 사용하는 경우 암호 제품군은 RSA 인증서 유형과 호환되는 암호 제품군과 일치합니다.
# 지원되는 보안 정책
다음 표에서는 각 REST API 엔드포인트 유형과 사용자 지정 도메인 이름 유형에 대해 지정할 수 있는 [보안 정책](apigateway-security-policies.md)을 설명합니다. 이러한 정책을 통해 수신 연결을 제어할 수 있습니다. API Gateway는 송신 시 TLS 1.2만 지원합니다. 언제든지 API 또는 사용자 지정 도메인 이름에 대한 보안 정책을 업데이트할 수 있습니다.
제목에 `FIPS`가 포함된 정책은 민감한 정보를 보호하는 암호화 모듈에 대한 보안 요구 사항을 지정하는 미국 및 캐나다 정부 표준인 연방 정보 처리 표준(FIPS)과 호환됩니다. 자세한 내용은 *AWS 클라우드 보안 규정 준수* 페이지의 [Federal Information Processing Standard(FIPS) 140](https://aws.amazon.com/compliance/fips/)을 참조하세요.
모든 FIPS 정책은 AWS-LC FIPS 검증 암호화 모듈을 활용합니다. 자세한 내용은 *NIST 암호화 모듈 검증 프로그램* 사이트의 [AWS-LC 암호화 모듈](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4631) 페이지를 참조하세요.
제목에 `PQ`가 포함된 정책은 [양자 내성 암호(PQC)](https://aws.amazon.com/security/post-quantum-cryptography/)를 사용하여 TLS에 대한 하이브리드 키 교환 알고리즘을 구현하여 향후 양자 컴퓨팅 위협에 대한 트래픽 기밀성을 보장합니다.
제목에 `PFS`가 포함된 정책은 [Perfect Forward Secrecy(PFS)](https://en.wikipedia.org/wiki/Forward_secrecy)를 사용하여 세션 키가 손상되지 않도록 합니다.
제목에 `FIPS` 및 `PQ`가 모두 포함된 정책은 이러한 기능을 모두 지원합니다.
## 기본 보안 정책
새 REST API 또는 사용자 지정 도메인을 생성하면 리소스에 기본 보안 정책이 할당됩니다. 다음 표에는 이러한 리소스에 대한 기본 보안 정책이 나와 있습니다.
| **리소스** | **기본 보안 정책 이름** |
| --- | --- |
| 리전 API | TLS\$11\$10 |
| 엣지 최적화 API | TLS\$11\$10 |
| 프라이빗 API | TLS\$11\$12 |
| 지역 도메인 | TLS\$11\$12 |
| 엣지 최적화 도메인 | TLS\$11\$12 |
| 프라이빗 도메인 | TLS\$11\$12 |
## 리전 및 프라이빗 API와 사용자 지정 도메인 이름에 지원되는 보안 정책
다음 표에서는 지역 및 프라이빗 API와 사용자 지정 도메인 이름에 대해 지정할 수 있는 보안 정책을 설명합니다.
| **보안 정책** | **지원되는 TLS 버전** | **지원되는 암호** |
| --- | --- | --- |
| SecurityPolicy\$1TLS13\$11\$13\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS13\$11\$13\$1FIPS\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS13\$11\$12\$1PFS\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS13\$11\$12\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$12 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
## 엣지 최적화 API 및 사용자 지정 도메인 이름에 지원되는 보안 정책
다음 표에서는 엣지 최적화 API와 엣지 최적화 사용자 지정 도메인 이름에 대해 지정할 수 있는 보안 정책을 설명합니다.
| **보안 정책 이름** | **지원되는 TLS 버전** | **지원되는 암호** |
| --- | --- | --- |
| SecurityPolicy\$1TLS13\$12025\$1EDGE | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS12\$1PFS\$12025\$1EDGE | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1TLS12\$12018\$1EDGE | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
## OpenSSL 및 RFC 암호 이름
OpenSSL 및 IETF RFC 5246은 동일한 암호에 대해 서로 다른 이름을 사용합니다. 다음 표에는 각 암호의 RFC 이름에 OpenSSL 이름이 매핑되어 있습니다. 자세한 내용은 OpenSSL 설명서의 [ciphers](https://docs.openssl.org/1.1.1/man1/ciphers/)를 참조하세요.
| **OpenSSL 암호 이름** | **RFC 암호 이름** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1SHA256 | TLS\$1AES\$1128\$1GCM\$1SHA256 |
| TLS\$1AES\$1256\$1GCM\$1SHA384 | TLS\$1AES\$1256\$1GCM\$1SHA384 |
| TLS\$1CHACHA20\$1POLY1305\$1SHA256 | TLS\$1CHACHA20\$1POLY1305\$1SHA256 |
| ECDHE-RSA-AES128-GCM-SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 |
| ECDHE-RSA-AES128-SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 |
| ECDHE-RSA-AES128-SHA | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
| ECDHE-RSA-AES256-GCM-SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 |
| ECDHE-RSA-AES256-SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 |
| ECDHE-RSA-AES256-SHA | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA |
| AES128-GCM-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 |
| AES256-GCM-SHA384 | TLS\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 |
| AES128-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 |
| AES256-SHA | TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA |
| AES128-SHA | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
| DES-CBC3-SHA | TLS\$1RSA\$1WITH\$13DES\$1EDE\$1CBC\$1SHA |
# 보안 정책을 변경하는 방법
API의 보안 정책을 변경할 수 있습니다. 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송하는 경우 API와 사용자 지정 도메인 이름은 동일한 보안 정책을 가질 필요가 없습니다. 해당 사용자 지정 도메인 이름을 간접적으로 호출하면 API Gateway는 API의 보안 정책을 사용하여 TLS 핸드셰이크를 협상합니다. 그러나 일관성을 위해 사용자 지정 도메인 이름 및 API에 동일한 보안 정책을 사용하는 것이 좋습니다.
보안 정책을 변경하는 경우 업데이트가 완료되는 데 약 15분이 걸립니다. API의 `apiStatus`를 모니터링할 수 있습니다. API가 업데이트되면 `apiStatus`는 `UPDATING`이고 완료되면 `AVAILABLE`이 됩니다. API를 업데이트할 때도 API를 간접적으로 호출할 수 있습니다.
------
#### [ AWS Management Console ]
**API의 보안 정책 변경**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. **API 설정**을 선택한 다음 **편집**을 선택합니다.
1. **보안 정책**에서 `SecurityPolicy_`로 시작하는 새 정책을 선택합니다.
1. **엔드포인트 액세스 모드**에서 **엄격**을 선택합니다.
1. **변경 사항 저장**을 선택합니다.
변경 사항을 적용하려면 API를 재배포합니다. 엔드포인트 액세스 모드를 엄격으로 변경했으므로 변경 사항이 완전히 전파되는 데 약 15분이 걸립니다.
------
#### [ AWS CLI ]
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책을 사용하도록 API를 업데이트합니다.
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
출력은 다음과 같습니다.
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a new security policy",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
"rootResourceId": "efg456"
}
```
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 보안 정책을 사용하기 위해 향상된 보안 `TLS_1_0` 정책을 사용하는 API를 업데이트합니다.
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "TLS_1_0"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": ""
}
]'
```
출력은 다음과 같습니다.
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a new security policy",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"securityPolicy": "TLS_1_0",
"rootResourceId": "efg456"
}
```
------
# API Gateway의 REST API에 대한 IP 주소 유형
API를 만들 때 API를 간접적으로 호출할 수 있는 IP 주소 유형을 지정합니다. IPv4를 선택하여 IPv4 주소가 API를 간접적으로 호출하도록 확인하거나, 듀얼 스택을 선택하여 IPv4 및 IPv6 주소가 모두 API를 간접적으로 호출하도록 허용할 수 있습니다. IP 공간 소진을 완화하기 위해 또는 보안 태세를 위해 IP 주소 유형을 듀얼 스택으로 설정하는 것이 좋습니다. 듀얼 스택 IP 주소 유형의 이점에 대한 자세한 내용은 [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)를 참조하세요.
API를 IPv6 트래픽으로만 제한하려면 리소스 정책을 만들고 소스 IP 주소를 IPv6 범위로만 제한할 수 있습니다. API의 구성을 업데이트하여 IP 주소 유형을 변경할 수 있습니다. 이 변경 사항은 즉시 적용되며 API를 재배포할 필요가 없습니다. 자세한 내용은 [예제: 소스 IP 주소 또는 범위에 따라 API 트래픽 거부](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example) 섹션을 참조하세요.
## IP 주소 유형에 대한 고려 사항
다음 고려 사항은 IP 주소 유형 사용에 영향을 미칠 수 있습니다.
+ 모든 리전 및 엣지 최적화 API의 기본 IP 주소 유형은 IPv4입니다.
+ 프라이빗 API는 듀얼 스택 IP 주소 유형만 가질 수 있습니다.
+ 기존 API의 IP 주소 유형을 IPv4에서 듀얼 스택으로 변경하는 경우 API에 대한 액세스를 제어하는 정책이 IPv6 직접 호출을 설명하도록 업데이트되었는지 확인합니다. IP 주소 유형을 변경하면 변경 사항이 즉시 적용됩니다.
+ API의 엔드포인트 유형을 리전 또는 엣지 최적화에서 프라이빗으로 마이그레이션하는 경우 API Gateway는 IP 주소 유형을 듀얼 스택으로 변경합니다. 자세한 내용은 [API Gateway에서 퍼블릭 또는 프라이빗 API 엔드포인트 유형 변경](apigateway-api-migration.md) 섹션을 참조하세요.
+ API의 엔드포인트 유형을 프라이빗에서 리전으로 마이그레이션하는 경우 IP 주소 유형을 듀얼 스택으로 설정해야 합니다. 엔드포인트 마이그레이션이 완료되면 IP 주소 유형을 IPv4로 변경할 수 있습니다. 자세한 내용은 [API Gateway에서 퍼블릭 또는 프라이빗 API 엔드포인트 유형 변경](apigateway-api-migration.md) 섹션을 참조하세요.
+ API는 API와 다른 IP 주소 유형의 사용자 지정 도메인 이름에 매핑할 수 있습니다. 기본 API 엔드포인트를 비활성화하면 직접 호출자가 API를 간접적으로 호출하는 방법에 영향을 미칠 수 있습니다.
+ 외부 정의 파일을 사용하여 API의 IP 주소 유형을 구성할 수 없습니다.
# REST API의 IP 주소 유형 변경
API의 구성을 업데이트하여 IP 주소 유형을 변경할 수 있습니다. AWS Management Console, AWS CLI, CloudFormation 또는 AWS SDK를 사용하여 API의 구성을 업데이트할 수 있습니다. API의 IP 주소 유형을 변경하는 경우 변경 사항이 적용되려면 API를 재배포해서는 안 됩니다. IP 주소 유형을 변경하기 전에 API에 대한 액세스를 제어하는 정책이 IPv6 직접 호출을 설명하도록 업데이트되었는지 확인합니다.
------
#### [ AWS Management Console ]
**REST API의 IP 주소 유형을 변경하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. **API 설정**을 선택한 다음 **편집**을 선택합니다.
1. IP 주소 유형에서 **IPv4** 또는 **듀얼 스택**을 선택합니다.
1. **변경 사항 저장**을 선택합니다.
API 구성에 대한 변경 사항은 즉시 적용됩니다.
------
#### [ AWS CLI ]
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 IP 주소 유형이 듀얼 스택이 되도록 API를 업데이트합니다.
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'"
```
출력은 다음과 같습니다.
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a dualstack IP address type",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"rootResourceId": "efg456"
}
```
------
# API Gateway의 REST API 메서드
API Gateway에서 API 메서드는 [ 메서드 요청](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 및 [메서드 응답](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)을 구현합니다. API 메서드를 설정하여 클라이언트가 백엔드에 있는 서비스에 대한 액세스 요청을 제출하기 위해 해야 할 것을 정의하고 클라이언트가 그 반대 급부로 수신하는 응답을 정의합니다. 입력의 경우, 메서드 요청 파라미터 또는 적용 가능 페이로드를 선택하여 클라이언트가 실행 시간에 필수 또는 선택 데이터를 제공하도록 할 수 있습니다. 출력의 경우, 메서드 응답 상태 코드, 헤더 및 적용 가능 본문을 백엔드 응답 데이터가 클라이언트에 반환되기 전에 이 데이터를 매핑할 대상으로 결정합니다. 클라이언트 개발자가 해당 API의 동작과 입력 및 출력 형식을 이해하는 데 도움을 주기 위해 [API를 문서화](api-gateway-documenting-api.md)하고 [잘못된 요청](api-gateway-method-request-validation.md)에 대해 [적절한 오류 메시지를 제공](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)할 수 있습니다.
API 메서드 요청은 HTTP 요청입니다. 메서드 요청을 설정하려면 HTTP 메서드(또는 동사), API [리소스](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) 경로, 헤더, 적용 가능한 쿼리 문자열 파라미터를 구성합니다. 또한 HTTP 메서드가 `POST`, `PUT` 또는 `PATCH`인 경우 페이로드를 구성합니다. 예를 들어 [PetStore 샘플 API](api-gateway-create-api-from-example.md)를 사용하여 반려 동물을 검색하려면 `GET /pets/{petId}`의 API 메서드 요청을 정의합니다. 여기에서 `{petId}`는 실행 시간에 숫자를 받아들일 수 있는 경로 파라미터입니다.
```
GET /pets/1
Host: apigateway.us-east-1.amazonaws.com
...
```
클라이언트가 잘못된 경로를 지정하는 경우(예: `/pet/1` 대신에 `/pets/one` 또는 `/pets/1`을 지정) 예외가 발생합니다.
API 메서드 응답은 특정 상태 코드의 HTTP 응답입니다. 비 프록시 통합의 경우에는 메서드 응답을 설정하여 매핑의 필수 또는 선택 대상을 지정해야 합니다. 이를 통해 통합 응답 헤더 또는 본문을 연결된 메서드 응답 헤더 또는 본문으로 변환합니다. 매핑은 통합을 통해 있는 그대로 헤더나 본문을 전달하는 [자격 증명 변환](https://en.wikipedia.org/wiki/Identity_transform)만큼 간단할 수 있습니다. 예를 들어 다음 `200` 메서드 응답에서는 성공적인 통합 응답을 있는 그대로 패스스루하는 예를 보여줍니다.
```
200 OK
Content-Type: application/json
...
{
"id": "1",
"type": "dog",
"price": "$249.99"
}
```
원칙적으로 백엔드에서 오는 특정 응답에 상응하는 메서드 응답을 정의할 수 있습니다. 일반적으로 이 작업에는 2XX, 4XX 및 5XX 응답이 수반됩니다. 그러나 이렇게 하는 것은 백엔드가 반환하는 모든 응답을 미리 알 수 없는 경우가 많으므로 실용적 방법이 되지 못할 수 있습니다. 실제로 한 가지 메서드 응답을 기본값으로 지정하여 백엔드에서 오는 알 수 없거나 매핑되지 않은 응답을 처리할 수 있습니다. 500 응답을 기본값으로 지정하는 것이 좋습니다. 어떤 경우에도 비 프록시 통합에 대해 메서드 응답을 최소 한 개 설정해야 합니다. 그렇게 하지 않으면 백엔드에서 요청이 성공하더라도 API Gateway는 클라이언트에게 500 오류 응답을 반환합니다.
해당 API에 대해 Java SDK와 같은 강력한 형식의 SDK를 지원하려면 메서드 요청에 대해 입력용 데이터 모델을 정의하고 메서드 응답에 대해 출력용 데이터 모델을 정의해야 합니다.
## 사전 조건
API 메서드를 설정하기 전에 다음 사항을 확인합니다.
+ API Gateway에 사용 가능한 메서드가 있어야 합니다. [자습서: HTTP 비 프록시 통합을 통해 REST API 생성](api-gateway-create-api-step-by-step.md)의 지침을 따르세요.
+ 메서드가 Lambda 함수와 통신하게 하려면 이미 IAM에서 Lambda 호출 역할과 Lambda 실행 역할을 생성했어야 합니다. 또한 에서 메서드가 통신할 Lambda 함수를 생성했어야 합니다AWS Lambda 역할 및 함수를 생성하려면 [AWS Lambda 통합 튜토리얼 선택](getting-started-with-lambda-integration.md)의 [Lambda 비 프록시 통합을 위한 Lambda 함수 만들기](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda) 지침을 따르세요.
+ 메서드가 HTTP 또는 HTTP 프록시 통합과 통신하도록 하려면 해당 메서드와 통신할 HTTP 엔드포인트 URL을 이미 생성하고 그에 대한 액세스 권한을 확보했어야 합니다.
+ HTTP 및 HTTP 프록시 엔드포인트의 인증서를 API Gateway에서 지원하는지 확인하세요. 자세한 내용은 [API Gateway의 HTTP 및 HTTP 프록시 통합에 대한 API Gateway 지원 인증 기관](api-gateway-supported-certificate-authorities-for-http-endpoints.md) 단원을 참조하세요.
**Topics**
+ [사전 조건](#method-setting-prerequisites)
+ [API Gateway에서 메서드 요청 설정](api-gateway-method-settings-method-request.md)
+ [API Gateway에서 메서드 응답 설정](api-gateway-method-settings-method-response.md)
+ [API Gateway 콘솔을 사용하여 메서드 설정](how-to-set-up-method-using-console.md)
# API Gateway에서 메서드 요청 설정
메서드 요청을 설정하는 작업에는 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스 생성 후 다음과 같은 작업이 수반됩니다.
1. 새 API 생성 또는 기존 API [리소스](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) 엔터티 선택.
1. 새로운 또는 선택된 API `Resource`에서 특정 HTTP 동사인 API [메서드](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 리소스를 생성. 이 작업은 다음과 같은 하위 작업으로 나눌 수 있습니다.
+ HTTP 메서드를 메서드 요청에 추가
+ 요청 파라미터 구성
+ 요청 본문에 모델을 정의
+ 권한 부여 체계 적용
+ 요청 검증 활성화
다음 메서드를 사용하여 이 작업을 수행할 수 있습니다.
+ [API Gateway 콘솔](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)
+ AWS CLI 명령([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) 및 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html))
+ AWS SDK 함수(예: Node.js의 [createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) 및 [putMethod](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property))
+ API Gateway REST API([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) 및 [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)).
**Topics**
+ [API 리소스 설정](#setup-method-resources)
+ [HTTP 메서드 설정](#setup-method-add-http-method)
+ [메서드 요청 파라미터 설정](#setup-method-request-parameters)
+ [메서드 요청 모델 설정](#setup-method-request-model)
+ [메서드 요청 권한 부여 설정](#setup-method-request-authorization)
+ [메서드 요청 검증 설정](#setup-method-request-validation)
## API 리소스 설정
API Gateway API에서 계층 꼭대기에 있는 루트 리소스(`/`)와 함께 주소 지정 가능 리소스를 API [리소스](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) 엔터티의 트리로 노출합니다. 루트 리소스는 API 엔드포인트 및 단계 이름으로 구성된 API의 기본 URL에 상대적입니다. API Gateway 콘솔에서 이 기본 URI는 **URI 호출(Invoke URI)**로 참조되고 API가 배포된 후에 API의 단계 편집기에 표시됩니다.
API 엔드포인트는 기본 호스트 이름 또는 사용자 지정 도메인 이름일 수 있습니다. 기본 호스트 이름은 다음 형식으로 되어 있습니다.
```
{api-id}.execute-api.{region}.amazonaws.com
```
이 형식에서 *\$1api-id\$1*는 API Gateway가 생성하는 API 식별자를 나타냅니다. `{region}` 변수는 API를 생성할 때 선택한 AWS 리전(예: `us-east-1`)을 나타냅니다. 사용자 지정 도메인 이름은 유효한 인터넷 도메인에 속한, 사용자에게 친숙한 이름입니다. 예를 들어 `example.com`의 인터넷 도메인을 등록하였다면 모든 `*.example.com`은 유효한 사용자 지정 도메인 이름입니다. 자세한 내용은 [사용자 지정 도메인 이름 생성](how-to-custom-domains.md) 단원을 참조하세요.
[PetStore 샘플 API](api-gateway-create-api-from-example.md)의 경우, 루트 리소스(`/`)는 해당 반려 동물 스토어를 공개합니다. `/pets` 리소스는 반려 동물 스토어에서 사용 가능한 반려 동물 모음을 나타냅니다. `/pets/{petId}`는 특정 식별자(`petId`)의 개별 반려 동물을 공개합니다. `{petId}`의 경로 파라미터는 요청 파라미터의 일부입니다.
API 리소스를 설정하려면 기존 리소스를 상위 리소스로 선택한 후 이 상위 리소스 아래에 하위 리소스를 생성합니다. 상위 리소스인 루트 리소스로 시작하여 이 상위 리소스에 리소스를 추가하고 이 하위 리소스에 또 다른 리소스를 새로운 상위 리소스로 추가하는 등의 작업을 상위 식별자에 이르기까지 수행합니다. 그 다음에 이름이 지정된 리소스를 상위 리소스에 추가합니다.
다음 [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) 명령은 API의 모든 리소스를 검색합니다.
```
aws apigateway get-resources --rest-api-id apiId
```
PetStore 샘플 API의 경우 출력은 다음과 같습니다.
```
{
"items": [
{
"path": "/pets",
"resourceMethods": {
"GET": {}
},
"id": "6sxz2j",
"pathPart": "pets",
"parentId": "svzr2028x8"
},
{
"path": "/pets/{petId}",
"resourceMethods": {
"GET": {}
},
"id": "rjkmth",
"pathPart": "{petId}",
"parentId": "6sxz2j"
},
{
"path": "/",
"id": "svzr2028x8"
}
]
}
```
각 항목은 리소스의 식별자(`id`)와 루트 리소스를 제외한 바로 위에 있는 상위 리소스(`parentId`)뿐 아니라 리소스 이름(`pathPart`)도 나열합니다. 루트 리소스는 상위 리소스가 없다는 점에서 특별합니다. 리소스를 상위 리소스로 선택한 후에 다음 명령을 사용하여 하위 리소스를 추가합니다.
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id parentId \
--path-part resourceName
```
예를 들어 PetStore 웹 사이트에서 판매할 반려동물 식품을 추가하려면 다음 명령을 사용합니다.
```
aws apigateway create-resource --rest-api-id a1b2c3 \
--parent-id svzr2028x8 \
--path-part food
```
출력은 다음과 같습니다.
```
{
"path": "/food",
"pathPart": "food",
"id": "xdsvhp",
"parentId": "svzr2028x8"
}
```
### 프록시 리소스를 사용하여 API 설정 간소화
비즈니스가 성장함에 딸 PetStore 소유주는 판매용으로 음식, 장난감, 기타 반려 동물 관련 항목을 추가하기로 결정할 수 있습니다. 이를 지원하기 위해 루트 리소스 아래에 `/food`, `/toys` 및 기타 리소스를 추가할 수 있습니다. 각 판매 범주에 `/food/{type}/{item}`, `/toys/{type}/{item}` 등 더 많은 리소스를 추가하고 싶을 수도 있습니다. 이는 번거로운 일일 수 있습니다. 리소스 경로에 중간 계층 `{subtype}`을 추가하여 경로 계층을 `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}` 등으로 변경하기로 한 경우, 그러한 변경으로 인해 기존 API 설정이 손상됩니다. 이를 방지하기 위해 API Gateway [프록시 리소스](api-gateway-set-up-simple-proxy.md)를 사용하여 한꺼번에 일련의 API 리소스를 공개할 수 있습니다.
API Gateway는 프록시 리소스를 해당 요청을 제출할 때 지정할 리소스의 자리 표시자로 정의합니다. 프록시 리소스는 복잡한 경로 파라미터로 자주 참조되는 `{proxy+}`의 특별 경로 파라미터로 표시됩니다. `+` 기호는 어떤 하위 리소스이든지 거기에 추가된 것을 나타냅니다. `/parent/{proxy+}` 자리 표시자는 `/parent/*`의 경로 패턴과 일치하는 모든 리소스를 나타냅니다. 최적의 경로 파라미터 이름에 어떤 문자열이든 사용할 수 있습니다.
다음 [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) 명령은 루트(`/{proxy+}`) 아래에 프록시 리소스를 생성합니다.
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id rootResourceId \
--path-part {proxy+}
```
출력은 다음과 같습니다.
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "234jdr",
"parentId": "svzr2028x8"
}
```
`PetStore` API의 예를 들면, `/{proxy+}`를 사용하여 `/pets` 및 `/pets/{petId}`를 모두 나타낼 수 있습니다. 이 프록시 리소스는 `/food/{type}/{item}`, `/toys/{type}/{item}`, 또는 `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}` 등 다른(기존 또는 추가될) 리소스를 참조할 수도 있습니다. 백엔드 개발자는 리소스 계층을 결정하고 클라이언트 개발자는 이를 이해할 책임이 있습니다. API Gateway는 클라이언트가 제출한 것은 무엇이든 백엔드에 전달할 뿐입니다.
API에는 프록시 리소스가 둘 이상 있을 수 있습니다. 예를 들어, `/parent/{proxy+}`가 `/parent/{child}/{proxy+}`와 동일한 상위 항목이 아니라고 가정할 때 API 내에서 다음 프록시 리소스가 허용됩니다.
```
/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}
```
프록시 리소스에 비 프록시 형제 리소스가 있는 경우 형제 리소스는 프록시 리소스의 표시에서 제외됩니다. 앞 예제의 경우, `/{proxy+}`는 `/parent[/*]` 리소스를 제외한 루트 리소스 아래의 모든 리소스를 가리킵니다. 즉 동일한 리소스 계층 수준에서는 특정 리소스에 대한 메서드 요청이 일반 리소스에 대한 메서드 요청에 우선합니다.
다음 표는 API Gateway가 API `prod` 스테이지에 대한 요청을 다음 리소스로 라우팅하는 방법을 보여줍니다.
```
ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog
```
| 요청 | 선택한 라우팅 | 설명 |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | 요청이 이 리소스와 완전히 일치합니다. |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | 최적의 `/pets/{proxy+}` 경로 변수가 이 요청을 포착합니다. |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | 최적의 `/{proxy+}` 경로 변수가 이 요청을 포착합니다. |
프록시 리소스에는 하위 리소스가 전혀 없을 수 있습니다. `{proxy+}` 뒤의 모든 API 리소스는 중복되며 의미가 명확하지 않습니다. 다음 프록시 리소스는 API 내에서 허용되지 않습니다.
```
/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}
```
## HTTP 메서드 설정
API 메서드 요청은 API Gateway [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 리소스로 캡슐화됩니다. 메서드 요청을 설정하려면 먼저 `Method` 리소스를 인스턴스화하여 HTTP 메서드를 최소 한 개 설정하고 그 메서드에 권한 부여 유형을 설정해야 합니다.
프록시 리소스와 긴밀히 연결된 API Gateway는 `ANY`의 HTTP 메서드를 지원합니다. 이 `ANY` 메서드는 실행 시간에 제공될 모든 HTTP 메서드를 나타냅니다. 이를 통해 `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` 및 `PUT`의 모든 지원되는 HTTP 메서드에 대해 단일 API 메서드 설정을 사용할 수 있습니다.
비 프록시 리소스에서도 `ANY` 메서드를 설정할 수 있습니다. `ANY` 메서드를 프록시 리소스와 결합하여 API의 모든 리소스에 대해 지원되는 모든 HTTP 메서드에 대한 단일 API 메서드 설정을 가져옵니다. 뿐만 아니라 백엔드는 기존 API 설정을 손상하지 않고도 발전할 수 있습니다.
API 메서드를 설정하기 전에 누가 메서드를 호출할 수 있는지 고려합니다. 계획에 따라 권한 부여 유형을 설정합니다. 오픈 액세스의 경우 그 유형을 `NONE`으로 설정합니다. IAM 권한을 사용하려면 권한 부여 유형을 `AWS_IAM`으로 설정합니다. Lambda 권한 부여자 함수를 사용하려면 이 속성을 `CUSTOM`으로 설정합니다. Amazon Cognito 사용자 풀을 사용하려면 권한 부여 유형을 `COGNITO_USER_POOLS`로 설정합니다.
다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령은 IAM 권한을 사용하여 `ANY` 구문에 대한 메서드 요청을 생성하여 액세스를 제어합니다.
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method ANY \
--authorization-type AWS_IAM
```
다른 권한 부여 유영으로 API 메서드 요청을 생성하려면 [메서드 요청 권한 부여 설정](#setup-method-request-authorization)을 참조하세요.
## 메서드 요청 파라미터 설정
메서드 요청 파라미터는 클라이언트가 메서드 요청을 완료하는 데 필요한 입력 데이터 또는 실행 컨텍스트를 제공하는 방식입니다. 메서드 파라미터는 경로 파라미터, 헤더 또는 쿼리 문자열 파라미터일 수 있습니다. 메서드 요청을 설정하는 과정에서 필수 요청 파라미터를 선언하여 클라이언트가 사용할 수 있게 해야 합니다. 비 프록시 통합의 경우 이러한 요청 파라미터를 백엔드 요구 사항과 호환되는 형식으로 변환할 수 있습니다.
예를 들어 `GET /pets/{petId}` 메서드 요청의 경우 `{petId}` 경로 변수는 필수 요청 파라미터입니다. `put-method`의 AWS CLI 명령을 호출할 때 이 경로 파라미터를 선언할 수 있습니다. 다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령은 필수 경로 파라미터가 있는 메서드를 생성합니다.
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id rjkmth \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.path.petId=true
```
파라미터가 필요하지 않은 경우 `false`에서 `request-parameters`로 설정할 수 있습니다. 예를 들어 `GET /pets` 메서드가 `type`의 선택적 쿼리 문자열 파라미터와 `age`의 선택적 헤더 파라미터를 사용하는 경우 다음과 같은 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령을 사용하여 두 파라미터를 선언할 수 있습니다.
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.type=false,method.request.header.age=false
```
이처럼 축약된 형식 대신에 다음과 같이 JSON 문자열을 사용하여 `request-parameters` 값을 설정할 수 있습니다.
```
'{"method.request.querystring.type":false,"method.request.header.age":false}'
```
클라이언트는 이 설정을 사용하여 반려 동물을 유형별로 쿼리할 수 있습니다.
```
GET /pets?type=dog
```
클라이언트는 다음과 같이 puppy인 dog를 쿼리할 수 있습니다.
```
GET /pets?type=dog
age:puppy
```
메서드 요청 파리미터를 통합 요청 파라미터로 매핑하는 방법에 대한 자세한 내용은 [API Gateway에서 REST API 통합](how-to-integration-settings.md)를 참조하세요.
## 메서드 요청 모델 설정
페이로드로 입력 데이터를 받아들일 수 있는 API 메서드의 경우에는 모델을 사용할 수 있습니다. 모델은 [JSON 스키마 draft 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04)로 표시되고 요청 본문의 데이터 구조를 설명합니다. 클라이언트는 모델을 통해 메서드 요청 페이로드를 입력으로 구성하는 방법을 결정할 수 있습니다. 더 중요한 것은 API Gateway가 모델을 사용하여 [요청의 유효성을 검증](api-gateway-method-request-validation.md)하고 [SDK를 생성](how-to-generate-sdk.md)하며 API Gateway 콘솔에서 통합을 설정하기 위한 매핑 템플릿을 초기화한다는 것입니다. [모델](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html)을 만드는 방법에 대한 자세한 내용은 [데이터 모델 이해](models-mappings-models.md)를 참조하세요.
콘텐츠 유형에 따라 메서드 페이로드에는 다양한 형식이 있을 수 있습니다. 모델은 적용된 페이로드의 미디어 유형에 대해 인덱싱됩니다. API Gateway는 `Content-Type` 요청 헤더를 사용하여 콘텐츠 유형을 결정합니다. 메서드 요청 모델을 설정하려면 `"media-type":"model-name"``requestModels` 명령을 호출할 때 AWS CLI 형식의 키 값 페어를 `put-method` 맵에 추가합니다.
콘텐츠 유형에 관계없이 동일한 모델을 사용하려면 `$default`을(를) 키로 지정합니다.
예를 들어 PetStore 예시 API의 `POST /pets` 메서드 요청의 JSON 페이로드에 모델을 설정하려면 다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령을 사용할 수 있습니다.
```
aws apigateway put-method \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method POST \
--authorization-type "NONE" \
--request-models '{"application/json":"petModel"}'
```
여기에서 `petModel`은 반려 동물을 설명하는 [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) 리소스의 `Model` 속성 값입니다. 실제 스키마 정의는 `schema` 리소스의 [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema) 속성의 JSON 문자열 값으로 표시됩니다.
API의 Java 또는 기타 강력한 형식의 SDK에서 입력 데이터는 스키마 정의에서 파생된 `petModel` 클래스로 캐스팅됩니다. 요청 모델을 사용하는 경우, 생성된 SDK 내 입력 데이터는 기본 `Empty` 모델에서 파생된 `Empty` 클래스로 캐스팅됩니다. 이 경우 클라이언트는 필수 입력을 제공하기 위해 정확한 데이터 클래스를 인스턴스화할 수는 없습니다.
## 메서드 요청 권한 부여 설정
API 메서드를 호출할 수 있는 사용자를 관리하기 위해 메서드에서 [권한 부여 유형](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)을 구성할 수 있습니다. 이 유형을 사용하여 IAM 역할과 정책(`AWS_IAM`), Amazon Cognito 사용자 풀(`COGNITO_USER_POOLS`) 또는 Lambda 권한 부여자(`CUSTOM`) 등 지원되는 권한 부여자 중 하나를 적용할 수 있습니다.
IAM 권한을 사용하여 API 메서드에 대한 액세스 권한을 부여하려면 `authorization-type`에 **AWS\$1IAM** 입력 속성을 설정합니다. 이 옵션이 설정되면 API Gateway는 호출자의 보안 인증 정보를 바탕으로 요청에 대한 호출자의 서명을 확인합니다. 확인된 사용자에게 메서드를 호출할 수 있는 권한이 있는 경우 그 요청은 수락됩니다. 그렇지 않다면 요청은 거부되고 호출자는 인증되지 않은 오류 응답을 받습니다. 호출자에게 API 메서드를 호출할 권한이 없는 한 메서드 호출은 성공하지 못합니다. 다음 IAM 정책은 호출자에게 동일한 AWS 계정에서 생성된 모든 API 메서드를 호출할 수 있는 권한을 부여합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:*:*:*"
}
]
}
```
------
자세한 내용은 [IAM 권한을 사용하여 REST API에 대한 액세스 제어](permissions.md) 섹션을 참조하세요.
현재는 API 소유자 AWS 계정 내의 사용자, 그룹 및 역할에만 이 정책을 부여할 수 있습니다. 다른 AWS 계정의 사용자는 `execute-api:Invoke` 작업을 호출하는 데 필요한 권한이 있는 역할을 API 소유자의 AWS 계정 내에서 수임하도록 허용된 경우에만 API 메서드를 호출할 수 있습니다. 교차 계정 권한에 대한 자세한 내용은 [IAM 역할 사용](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) 단원을 참조하세요.
AWS CLI, AWS SDK 또는 [Signature Version 4(SigV4) 서명](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html)을 구현하는 [Postman](https://www.postman.com/)과 같은 REST API 클라이언트를 사용할 수 있습니다.
Lambda 권한 부여자를 사용하여 API 메서드에 대한 액세스 권한을 부여하려면 `CUSTOM`에 `authorization-type` 입력 속성을 설정하고 이미 존재하는 Lambda 권한 부여자의 [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) 속성 값에 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) 입력 속성을 설정합니다. 참조된 Lambda 권한 부여자는 `TOKEN` 또는 `REQUEST` 유형일 수 있습니다. Lambda 권한 부여자를 생성하는 방법은 [API Gateway Lambda 권한 부여자 사용](apigateway-use-lambda-authorizer.md) 단원을 참조하세요.
Amazon Cognito 사용자 풀을 사용하여 API 메서드에 대한 액세스 권한을 부여하려면 `COGNITO_USER_POOLS`에 `authorization-type` 입력 속성을 설정하고 이미 생성된 `COGNITO_USER_POOLS` 권한 부여자의 [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) 속성 값에 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) 입력 속성을 설정합니다. Amazon Cognito 사용자 풀 권한 부여자 생성에 대한 자세한 내용은 [Amazon Cognito 사용자 풀을 권한 부여자로 사용하여 REST API에 대한 액세스 제어](apigateway-integrate-with-cognito.md) 단원을 참조하세요.
## 메서드 요청 검증 설정
API 메서드 요청을 설정할 때 요청 검증을 활성화할 수 있습니다. 먼저 다음과 같이 [요청 검사기](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)를 생성해야 합니다. 다음 [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html) 명령은 본문 전용 요청 검사기를 생성합니다.
```
aws apigateway create-request-validator \
--rest-api-id 7zw9uyk9kl \
--name bodyOnlyValidator \
--validate-request-body \
--no-validate-request-parameters
```
출력은 다음과 같습니다.
```
{
"validateRequestParameters": false,
"validateRequestBody": true,
"id": "jgpyy6",
"name": "bodyOnlyValidator"
}
```
이 요청 검사기를 통해 요청 검증을 메서드 요청 설정의 일부로 사용할 수 있습니다. 다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령은 수신 요청 본문이 `PetModel`과 일치해야 하는 메서드 요청을 생성하고 필요하지 않은 요청 파라미터가 두 개 있습니다.
```
aws apigateway put-method \
--rest-api-id 7zw9uyk9kl \
--resource-id xdsvhp \
--http-method PUT \
--authorization-type "NONE" \
--request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \
--request-models '{"application/json":"petModel"}' \
--request-validator-id jgpyy6
```
요청 검증에 요청 파라미터를 포함하려면 요청 검사기에 대해 `validateRequestParameters`를 `true`로 설정하고 `put-method` 명령에서 특정 요청 파라미터를 `true`로 설정해야 합니다.
# API Gateway에서 메서드 응답 설정
API 메서드 응답은 클라이언트가 수신할 API 메서드 요청의 출력을 캡슐화합니다. 출력 데이터에는 HTTP 상태 코드, 일부 헤더, 그리고 때로는 본문이 포함됩니다.
비 프록시 통합의 경우, 지정된 응답 파라미터 및 본문은 연결된 통합 응답 데이터로부터 매핑되거나 매핑에 따라 특정 정적 값이 할당될 수 있습니다. 이 매핑은 통합 응답에 지정되어 있습니다. 매핑은 통합 응답을 있는 그대로 통과하는 동일한 변환일 수 있습니다.
프록시 통합의 경우, API Gateway는 백엔드 응답을 메서드 응답으로 자동 전달합니다. API 메서드 응답을 설정할 필요는 없습니다. 그러나 Lambda 프록시 통합의 경우, 통합 응답을 메서드 응답에 성공적으로 매핑하려면 Lambda 함수는 API Gateway에 대해 [이 출력 형식](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format)의 결과를 반환해야 합니다.
프로그램에 따라 메서드 응답 설정은 API Gateway의 [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) 리소스 설정과 [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) 및 [responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels)의 속성 설정에 해당합니다.
API 메서드에 대해 상태 코드를 설정할 때는 예기치 않은 상태 코드의 모든 통합 응답을 처리하기 위해 상태 코드 하나를 기본값으로 선택해야 합니다. `500`을 기본값으로 설정하는 것이 타당합니다. 왜냐하면 이것은 그렇지 않았다면 매핑되지 않았을 응답을 서버 측 오류로 캐스팅하는 것에 해당하기 때문입니다. 지침을 제공하기 위해, API Gateway 콘솔은 `200` 응답을 기본값으로 설정합니다. 그러나 이를 `500` 응답으로 재설정할 수 있습니다.
메서드 응답을 설정하려면 메서드 요청을 생성했어야 합니다.
## 메서드 응답 상태 코드 설정
메서드 응답의 상태 코드는 응답의 유형을 정의합니다. 예를 들어 200, 400 및 500 응답은 각각 성공, 클라이언트 측 오류 및 서버 측 오류 응답을 나타냅니다.
메서드 응답 상태 코드를 설정하려면 HTTP 상태 코드에 [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode) 속성을 설정합니다. 다음 [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) 명령은 `200` 메서드 응답을 생성합니다.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200
```
## 메서드 응답 파라미터 설정
메서드 응답 파라미터는 연결된 메서드 요청에 대한 응답으로 클라이언트가 어떤 헤더를 수신하는지 정의합니다. 응답 파라미터는 API Gateway가 API 메서드의 통합 응답에 미리 지정된 매핑에 따라 통합 응답 파라미터를 매핑하는 대상을 지정하기도 합니다.
메서드 응답 파라미터를 설정하려면 `responseParameters`의 [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) 맵에 `"{parameter-name}":"{boolean}"` 형식의 키 값 페어를 추가합니다. 다음 [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) 명령은 `my-header` 헤더를 설정합니다.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.response.header.my-header=false
```
## 메서드 응답 모델 설정
메서드 응답 모델은 메서드 응답 본문의 형식을 정의합니다. 메서드 응답 모델 설정은 강력한 형식의 API용 SDK를 생성할 때 필요합니다. 이를 통해 출력은 Java 또는 Objective-C의 적절한 클래스에 캐스팅됩니다.
응답 모델을 설정하기 전에 먼저 API Gateway에 모델을 생성해야 합니다. 이를 위해 `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)` 명령을 호출할 수 있습니다. 다음 [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) 명령은 `GET /pets/{petId}` 메서드 요청에 대한 응답의 본문을 설명하기 위해 `PetStorePet` 모델을 생성합니다.
```
aws apigateway create-model \
--rest-api-id vaz7da96z6 \
--content-type application/json \
--name PetStorePet \
--schema '{ \
"$schema": "http://json-schema.org/draft-04/schema#", \
"title": "PetStorePet", \
"type": "object", \
"properties": { \
"id": { "type": "number" }, \
"type": { "type": "string" }, \
"price": { "type": "number" } \
} \
}'
```
그 결과 API Gateway [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) 리소스가 생성됩니다.
페이로드 형식을 정의하도록 메서드 응답 모델을 설정하려면 "application/json":"PetStorePet" 키-값 페어를 [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) 리소스의 [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels) 맵에 추가합니다. 다음 [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) 명령은 응답 모델을 사용하여 페이로드 형식을 정의하는 메서드 응답을 생성합니다.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.response.header.my-header=false \
--response-models '{"application/json":"PetStorePet"}'
```
# API Gateway 콘솔을 사용하여 메서드 설정
REST API 콘솔을 사용하여 메서드를 생성하는 경우 통합 요청과 메서드 요청을 모두 구성합니다. 기본적으로 API Gateway는 사용자 메서드의 `200` 메서드 응답을 생성합니다.
다음 지침은 메서드 요청 설정을 편집하는 방법과 메서드에 대한 추가 메서드 응답을 생성하는 방법을 보여줍니다.
**Topics**
+ [API Gateway 콘솔에서 API Gateway 메서드 요청 편집](#how-to-method-settings-callers-console)
+ [API Gateway 콘솔에서 API Gateway 메서드 응답 설정](#how-to-method-response-settings-console)
## API Gateway 콘솔에서 API Gateway 메서드 요청 편집
이러한 지침에서는 메서드 요청을 이미 생성한 것으로 가정합니다. 매소드를 생성하는 방법에 대한 자세한 내용은 [API Gateway 콘솔을 사용하여 API 통합 요청 설정](how-to-method-settings-console.md) 단원을 참조하세요.
1. **리소스** 창에서 메소드를 선택한 후 **메서드 요청** 탭을 선택합니다.
1. **메서드 요청 설정** 섹션에서 **편집**을 선택합니다.
1. **권한 부여**에서 사용 가능한 권한 부여자를 선택합니다.
1. 모든 사용자에게 메서드에 대한 오픈 액세스를 활성화하려면 **없음**을 선택합니다. 기본값 설정이 변경되지 않은 경우 이 단계는 건너뛸 수 있습니다.
1. IAM 권한을 사용하여 메서드에 대한 클라이언트 액세스 권한을 제어하려면 `AWS_IAM`을 선택합니다. 이 선택을 통해 올바른 IAM 정책이 연결된 IAM 역할의 사용자만 이 메서드를 호출할 수 있습니다.
IAM 역할을 생성하려면 다음과 같은 형식의 액세스 정책을 지정합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/"
]
}
]
}
```
------
이 액세스 정책에서 `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/`는 메서드의 ARN입니다. **리소스** 페이지에서 방법을 선택하면 메서드의 ARN을 찾을 수 있습니다. IAM 권한 설정에 대한 자세한 내용은 [IAM 권한을 사용하여 REST API에 대한 액세스 제어](permissions.md)를 참조하세요.
IAM 역할을 만들려면 다음 자습서 [Lambda 비 프록시 통합을 위한 Lambda 함수 만들기](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda)의 지침을 적용하면 됩니다.
1. Lambda 권한 부여자를 사용하려면 토큰 또는 요청 권한 부여자를 선택합니다. 이 선택이 드롭다운 메뉴에 표시되도록 하기 위해서는 Lambda 권한 부여자를 생성합니다. Lambda 권한 부여자를 생성하는 방법에 대한 자세한 내용은 [API Gateway Lambda 권한 부여자 사용](apigateway-use-lambda-authorizer.md) 단원을 참조하세요.
1. Amazon Cognito 사용자 풀을 사용하려면 **Cognito 사용자 풀 권한 부여자**에서 사용할 수 있는 사용자 풀을 선택합니다. 이 선택이 드롭다운 메뉴에 표시되도록 하기 위해서는 Amazon Cognito에 사용자 풀을 생성하고 API Gateway에 Amazon Cognito 사용자 풀 권한 부여자를 생성합니다. Amazon Cognito 사용자 풀 권한 부여자를 생성하는 방법에 대한 자세한 내용은 [Amazon Cognito 사용자 풀을 권한 부여자로 사용하여 REST API에 대한 액세스 제어](apigateway-integrate-with-cognito.md) 단원을 참조하세요.
1. 요청 검증을 지정하려면 **요청 검사기** 드롭다운 메뉴에서 값을 선택합니다. 요청 검증을 비활성화하려면 **없음**을 선택합니다. 각 옵션에 대한 자세한 내용은 [API Gateway의 REST API API 검증 요청](api-gateway-method-request-validation.md)를 참조하세요.
1. API 키를 요구하려면 **API 키가 필요함**을 선택합니다. API는 활성화되면 [사용량 계획](api-gateway-api-usage-plans.md)에서 클라이언트 트래픽을 조절하는 데 사용됩니다.
1. (선택 사항) API Gateway에서 생성된 이 API의 Java SDK에서 작업 이름을 할당하려면 **작업 이름**에 이름을 입력합니다. 예를 들어 `GET /pets/{petId}`의 메서드 요청에 대해 이에 상응하는 Java SDK 작업 이름은 기본적으로 `GetPetsPetId`입니다. 이 이름은 메서드의 HTTP 동사(`GET`)와 리소스 경로 변수 이름(`Pets` 및 `PetId`)으로부터 구성됩니다. 작업 이름을 `getPetById`로 설정하면 SDK 작업 이름은 `GetPetById`가 됩니다.
1. 메서드에 쿼리 문자열 파라미터를 추가하려면 다음을 수행합니다.
1. **URL 쿼리 문자열 파라미터**를 선택한 다음, **쿼리 문자열 추가**를 선택합니다.
1. **이름**에 쿼리 문자열 파라미터의 이름을 입력합니다.
1. 새로 생성된 쿼리 문자열 파라미터가 요청 검증에 사용되는 경우 **필수**를 선택합니다. 요청 검증에 대한 자세한 내용은 [API Gateway의 REST API API 검증 요청](api-gateway-method-request-validation.md)를 참조하세요.
1. 새로 생성된 쿼리 문자열 파라미터가 캐싱 키의 일부로 사용되는 경우 **캐싱**을 선택합니다. 캐싱에 대한 자세한 정보는 [메서드/통합 파라미터를 캐시 키로 사용하여 캐시된 응답 인덱싱](api-gateway-caching.md#enable-api-gateway-cache-keys)을 참조하세요.
쿼리 문자열 파라미터를 제거하려면 **제거**를 선택합니다.
1. 메서드에 헤더 파라미터를 추가하려면 다음을 수행합니다.
1. **HTTP 요청 헤더**를 선택한 다음, **헤더 추가**를 선택합니다.
1. **이름**에 헤더 이름을 입력합니다.
1. 새로 생성된 헤더가 요청 검증에 사용되는 경우 **필수**를 선택합니다. 요청 검증에 대한 자세한 내용은 [API Gateway의 REST API API 검증 요청](api-gateway-method-request-validation.md)를 참조하세요.
1. 새로 생성된 헤더가 캐싱 키의 일부로 사용되는 경우 **캐싱**을 선택합니다. 캐싱에 대한 자세한 정보는 [메서드/통합 파라미터를 캐시 키로 사용하여 캐시된 응답 인덱싱](api-gateway-caching.md#enable-api-gateway-cache-keys)을 참조하세요.
헤더를 제거하려면 **제거**를 선택합니다.
1. `POST`, `PUT` 또는 `PATCH` HTTP 동사로 메서드 요청의 페이로드 형식을 선언하려면 **요청 본문**을 선택하고 다음과 같이 합니다.
1. **모델 추가**를 선택합니다.
1. **콘텐츠 유형**에 MIME 유형(예: `application/json`)을 입력합니다.
1. **모델**의 경우 드롭다운 메뉴에서 모델을 선택합니다. API에 대해 현재 사용할 수 있는 모델에는 기본 `Empty` 및 `Error` 모델뿐 아니라 이미 생성해 API의 [모델](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) 모음에 추가한 모든 모델도 포함됩니다. 모델 생성에 대한 자세한 내용은 [REST API에 대한 데이터 모델](models-mappings-models.md)을 참조하세요.
**참고**
모델은 클라이언트에게 페이로드의 예상 데이터 형식을 알려주는 데 유용합니다. 스켈레톤 매핑 템플릿을 생성하는 것이 도움이 됩니다. Java, C\$1, Objective-C, Swift 등의 언어에서 API의 강력한 형식 SDK를 생성하는 것이 중요합니다. 이는 페이로드에 대해 요청 검증이 활성화된 경우에만 필요합니다.
1. **저장**을 선택합니다.
## API Gateway 콘솔에서 API Gateway 메서드 응답 설정
API 메서드는 응답이 하나 이상일 수 있습니다. 각 응답은 HTTP 상태 코드로 인덱싱됩니다. 기본적으로 API Gateway 콘솔은 `200` 응답을 메서드 응답에 추가합니다. 예를 들어 메서드가 `201`을 대신 반환하도록 응답을 수정할 수 있습니다. 또한 다른 응답을 추가할 수도 있는데, 예를 들면 액세스 거부의 경우 `409`를, 초기화되지 않은 단계 변수가 사용된 경우 `500`을 추가할 수 있습니다.
API Gateway 콘솔을 사용하여 API 메서드에 대한 응답을 수정, 삭제 또는 추가하려면 다음 지침을 따르세요.
1. **리소스** 창에서 메서드를 선택한 상태로 **메서드 응답** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. **메서드 응답 설정** 섹션에서 **응답 생성**을 선택합니다.
1. **HTTP 상태 코드**에 HTTP 상태 코드(예: `200`, `400`, `500`)를 입력합니다.
백엔드 반환 응답에 그에 상응하는 메서드 응답이 정의되어 있지 않으면 API Gateway는 클라이언트에게 응답을 반환하는 데 실패합니다. 그 대신에 `500 Internal server error` 오류 응답을 반환합니다.
1. **헤더 추가(Add header)**를 선택합니다.
1. **헤더 이름**에 이름을 입력합니다.
백엔드에서 클라이언트로 헤더를 반환하려면 메서드 응답에 헤더를 추가합니다.
1. 메서드 응답 본문의 형식을 정의하려면 **모델 추가**를 선택합니다.
**콘텐츠 유형**에 응답 페이로드의 미디어 유형을 입력하고 **모델** 드롭다운 메뉴에서 모델을 선택합니다.
1. **저장**을 선택합니다.
기존 응답을 수정하려면 메서드 응답으로 이동한 다음 **편집**을 선택합니다. **HTTP 상태 코드**를 변경하려면 **삭제**를 선택하고 새 메서드 응답을 생성합니다.
백엔드에서 반환되는 응답마다 메서드 응답으로 구성된 호환 가능한 응답이 있어야 합니다. 그러나 클라이언트에게 반환되기 전에 백엔드로부터 오는 결과를 메서드 응답에 매핑하지 않으면 메서드 응답 헤더 및 페이로드 모델을 구성하는 것은 선택 사항입니다. 또한 메서드 응답 페이로드 모델은 강력한 형식의 API용 SDK를 생성하는 경우에 중요합니다.
# API Gateway에서 REST API에 대한 액세스 제어 및 관리
API Gateway는 API 액세스 제어 및 관리에 다중 메커니즘을 지원합니다.
다음 메커니즘은 인증 및 권한 부여에 사용할 수 있습니다.
+ **리소스 정책**으로 리소스 기반 정책을 만들어 특정 소스의 IP 주소 또는 VPC 종단점의 API 및 메서드 액세스 권한을 부여하거나 거부할 수 있습니다. 자세한 내용은 [API Gateway 리소스 정책을 사용하여 REST API에 대한 액세스 제어](apigateway-resource-policies.md) 단원을 참조하세요.
+ **표준 AWS IAM 역할 및 정책**은 전체 API 또는 개별 메서드에 적용할 수 있는 유연하고 강력한 액세스 제어를 제공합니다. IAM 역할 및 정책을 사용하여 API를 생성하고 관리할 수 있는 사용자와 API를 호출할 수 있는 사용자를 관리할 수 있습니다. 자세한 내용은 [IAM 권한을 사용하여 REST API에 대한 액세스 제어](permissions.md) 단원을 참조하세요.
+ **IAM 태그**는 액세스 제어를 위해 IAM 정책과 함께 사용할 수 있습니다. 자세한 내용은 [태그를 사용하여 API Gateway REST API 리소스에 대한 액세스 제어](apigateway-tagging-iam-policy.md) 단원을 참조하세요.
+ **인터페이스 VPC 종단점에 대한 엔드포인트 정책**을 통해 [프라이빗 API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html)의 보안을 향상시키기 위해 인터페이스 VPC 종단점에 IAM 리소스 정책을 연결할 수 있습니다. 자세한 내용은 [API Gateway의 프라이빗 API에 대한 VPC 종단점 정책 사용](apigateway-vpc-endpoint-policies.md) 단원을 참조하세요.
+ **Lambda 권한 부여자**는 보유자 토큰 인증과 헤더, 경로, 쿼리 문자열, 단계 변수, 맥락 변수 요청 파라미터에 서술된 정보를 이용하여 REST API 메서드에 대한 액세스를 제어하는 Lambda 함수입니다. Lambda 권한 부여자는 REST API 메서드를 호출할 수 있는 사람을 제어하는 데 사용됩니다. 자세한 내용은 [API Gateway Lambda 권한 부여자 사용](apigateway-use-lambda-authorizer.md) 단원을 참조하세요.
+ **Amazon Cognito 사용자 풀**로 REST API에 대해 사용자 지정이 가능한 인증 및 권한 부여 솔루션을 만들 수 있습니다. Amazon Cognito 사용자 풀은 REST API 메서드를 호출할 수 있는 사람을 제어하는 데 사용됩니다. 자세한 내용은 [Amazon Cognito 사용자 풀을 권한 부여자로 사용하여 REST API에 대한 액세스 제어](apigateway-integrate-with-cognito.md) 단원을 참조하세요.
다음 메커니즘은 액세스 제어와 관련된 다른 작업을 수행할 때 사용할 수 있습니다.
+ **CORS(Cross-origin 리소스 공유)**로 REST API가 교차 도메인 리소스 요청에 응답하는 방식을 제어할 수 있습니다. 자세한 내용은 [API Gateway의 REST API CORS](how-to-cors.md) 단원을 참조하세요.
+ **클라이언트 측 SSL 인증서**를 사용하여 백엔드 시스템에 대한 HTTP 요청이 API Gateway에서 시작된 것인지 확인할 수 있습니다. 자세한 내용은 [API Gateway에서 백엔드 인증을 위한 SSL 인증서 생성 및 구성](getting-started-client-side-ssl-authentication.md) 단원을 참조하세요.
+ **AWS WAF**는 일반적인 웹 익스플로잇으로부터 API Gateway API를 보호하기 위해 사용할 수 있습니다. 자세한 내용은 [API Gateway에서 AWS WAF를 사용하여 REST API 보호](apigateway-control-access-aws-waf.md) 단원을 참조하세요.
다음 메커니즘은 권한이 있는 클라이언트에게 부여한 액세스 권한을 추적하고 제한하는 데 사용할 수 있습니다.
+ **사용량 계획**을 통해 고객에게 **API 키**를 제공할 수 있으며 그 후에 각 API 키에 대하여 API 단계와 메서드를 추적하고 사용량을 제한할 수 있습니다. 자세한 내용은 [API Gateway의 REST API 사용량 계획 및 API 키](api-gateway-api-usage-plans.md) 섹션을 참조하세요.
# API Gateway 리소스 정책을 사용하여 REST API에 대한 액세스 제어
Amazon API Gateway *리소스 정책*은 지정된 보안 주체(보통 IAM 역할 또는 그룹)가 API를 호출할 수 있는지 여부를 제어하기 위해 API에 연결하는 JSON 정책 문서입니다. API Gateway 리소스 정책을 사용하여 다음과 같은 엔터티의 안전한 API 호출을 허용할 수 있습니다.
+ 지정된 AWS 계정의 사용자.
+ 지정된 소스 IP 주소 범위 또는 CIDR 블록.
+ 지정된 가상 사설 클라우드(VPC) 또는 VPC 종단점(계정 무관).
AWS Management Console, AWS CLI 또는 AWS SDK를 사용하여 API Gateway에 모든 API 엔드포인트 유형에 대한 리소스 정책을 연결할 수 있습니다. [프라이빗 API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html)의 경우 VPC 종단점 정책과 함께 리소스 정책을 사용하여 어떤 주체가 어떤 리소스 및 작업에 대한 액세스를 가질지를 제어할 수 있습니다. 자세한 내용은 [API Gateway의 프라이빗 API에 대한 VPC 종단점 정책 사용](apigateway-vpc-endpoint-policies.md) 섹션을 참조하세요.
API Gateway 리소스 정책은 IAM 자격 증명 기반 정책과 다릅니다. IAM 정책은 IAM 엔터티(사용자, 그룹 또는 역할)에 연결되어 이들 엔터티가 어떤 리소스에 대해 어떤 조치를 취할 수 있는지 정의합니다. API Gateway 리소스 정책은 리소스에 연결됩니다. API Gateway 리소스 정책을 IAM 정책과 함께 사용할 수 있습니다. 자세한 내용은 [자격 증명 기반 정책 및 리소스 기반 정책](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html)을 참조하세요.
**Topics**
+ [Amazon API Gateway에 대한 액세스 정책 언어 개요](apigateway-control-access-policy-language-overview.md)
+ [API Gateway 리소스 정책이 권한 부여 워크플로우에 미치는 영향](apigateway-authorization-flow.md)
+ [API Gateway 리소스 정책 예제](apigateway-resource-policies-examples.md)
+ [API Gateway 리소스 정책을 생성하여 API에 연결](apigateway-resource-policies-create-attach.md)
+ [AWSAPI Gateway 리소스 정책에 사용할 수 있는 조건 키](apigateway-resource-policies-aws-condition-keys.md)
# Amazon API Gateway에 대한 액세스 정책 언어 개요
이 페이지에서는 Amazon API Gateway 리소스 정책에 사용되는 기본 요소를 설명합니다.
IAM 정책과 동일한 구문을 사용하여 리소스 정책이 지정됩니다. 전체 정책 언어에 대한 정보는 **IAM 사용 설명서의 [IAM 정책 개요](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) 및 [AWS Identity and Access Management 정책 참조](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html)를 참조하세요.
AWS 서비스가 어떻게 해당 요청의 허용 또는 거부 여부를 결정하는지에 대한 자세한 내용은 [요청의 허용 또는 거부 결정](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow) 단원을 참조하세요.
## 액세스 정책의 공통 요소
가장 기본적인 경우, 리소스 정책에는 다음 요소가 포함되어 있습니다.
+ **리소스** – API는 권한을 허용 또는 거부할 수 있는 Amazon API Gateway 리소스입니다. 정책에서는 Amazon 리소스 이름(ARN)을 사용하여 리소스를 식별해야 합니다. 리소스 정책을 저장할 때 API Gateway가 전체 ARN으로 자동으로 확장하는 약식 구문을 사용할 수도 있습니다. 자세한 내용은 [API Gateway 리소스 정책 예제](apigateway-resource-policies-examples.md) 단원을 참조하세요.
전체 `Resource` 요소의 형식은 [API Gateway의 API 실행 권한 리소스 형식](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-resource-format-for-executing-api) 단원을 참조하세요.
+ **작업** - 각 리소스에 대해 Amazon API Gateway는 작업의 집합을 지원합니다. 작업 키워드를 사용하여 허용(또는 거부)할 리소스 작업을 식별합니다.
예를 들어 `execute-api:Invoke` 권한은 사용자가 클라이언트 요청 시 API를 호출할 수 있도록 허용합니다.
`Action` 요소의 형식은 [API Gateway의 API 실행 권한 작업 형식](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-action-format-for-executing-api) 단원을 참조하세요.
+ **효과** - 사용자가 특정 작업을 요청하는 경우의 효과입니다. 이는 `Allow` 또는 `Deny` 중에 하나가 될 수 있습니다. 다른 정책에서 액세스 권한을 부여하는 경우라도 사용자가 해당 리소스에 액세스할 수 없도록 하기 위해 리소스에 대한 권한을 명시적으로 거부할 수도 있습니다.
**참고**
"암시적 거부"는 "기본 거부"와 동일합니다.
“암시적 거부”는 “명시적 거부”와 다릅니다. 자세한 내용은 [기본 거부와 명시적 거부의 차이](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#AccessPolicyLanguage_Interplay) 단원을 참조하세요.
+ **보안 주체** - 문에서의 작업 및 리소스에 액세스할 수 있는 계정 또는 사용자입니다. 리소스 정책에서 보안 주체는 이 권한을 수신하는 사용자나 계정입니다.
다음의 리소스 정책 예시는 이전의 공통 정책 요소를 나타냅니다. 이 정책은 소스 IP 주소가 *123.4.5.6/24* 주소 블록에 속하는 사용자에게 지정된 *region*의 지정된 *account-id*에서 API에 대한 액세스 권한을 부여합니다. 이 정책은 사용자의 소스 IP가 해당 범위 내에 있지 않으면 API에 대한 모든 액세스를 거부합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:*"
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:*",
"Condition": {
"NotIpAddress": {
"aws:SourceIp": "123.4.5.6/24"
}
}
}
]
}
```
------
# API Gateway 리소스 정책이 권한 부여 워크플로우에 미치는 영향
API Gateway가 API에 연결된 리소스 정책을 평가할 때 그 결과는, 다음 단원의 흐름 차트에 서명된 것처럼, APi에 대하여 정의한 인증 유형의 영향을 받습니다.
**Topics**
+ [API Gateway 리소스 정책만](#apigateway-authorization-flow-resource-policy-only)
+ [Lambda 권한 부여자 및 리소스 정책](#apigateway-authorization-flow-lambda)
+ [IAM 인증 및 리소스 정책](#apigateway-authorization-flow-iam)
+ [Amazon Cognito 인증 및 리소스 정책](#apigateway-authorization-flow-cognito)
+ [정책 평가 결과표](#apigateway-resource-policies-iam-policies-interaction)
## API Gateway 리소스 정책만
이 워크플로우에서 API Gateway 리소스 정책은 API에 연결되지만 API에 대하여 정의되는 인증 유형은 없습니다. 정책 평가를 위해서는 호출자의 인바운드 기준에 따른 명시적 허용이 필요합니다. 묵시적 거부 또는 명시적 거부는 호출자에 대한 거부로 이어집니다.
![\[리소스 정책의 권한 부여 흐름만.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/apigateway-auth-resource-policy-only.png)
다음은 이러한 리소스 정책의 예입니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/",
"Condition": {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
## Lambda 권한 부여자 및 리소스 정책
이 워크플로우에서 Lambda 권한 부여자는 리소스 정책과 함께 API에 대하여 구성됩니다. 리소스 정책은 2단계로 평가됩니다. Lambda 권한 부여자를 호출하기 전에 API Gateway는 먼저 정책을 평가하고 명시적 거부를 확인합니다. 명시적 거부가 확인되면 호출자는 즉시 액세스를 거부당합니다. 그렇지 않으면 Lambda 권한 보유자가 호출되어 리소스 정책과 결합하여 평가되는 [정책 문서](api-gateway-lambda-authorizer-output.md)를 반환합니다. 권한 부여자가 캐싱을 사용하는 경우 API Gateway는 캐싱된 정책 문서를 반환할 수 있습니다. 그 결과는 [테이블 A](#apigateway-resource-policies-iam-policies-interaction)에 따라 결정됩니다.
다음의 리소스 정책 예제는 그 VPC 엔드포인트 ID가 `vpce-1a2b3c4d`인 VPC 엔드포인트로부터의 호출만을 허용합니다. “인증 전” 평가 과정 중에는 예제에 나온 VPC 종단점에서의 호출만이 다음 단계로 넘어가 Lambda 권한 부여자를 평가하는 것이 허용됩니다. 나머지 모든 호출은 차단됩니다. 프라이빗 API에 사용자 지정 도메인 이름을 사용하는 경우 이 권한 부여 워크플로는 동일합니다.
![\[리소스 정책과 Lambda 권한 부여자의 권한 부여 흐름.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/apigateway-auth-lambda-resource-policy.png)
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
}
]
}
```
------
## IAM 인증 및 리소스 정책
이 워크플로에서 리소스 정책 외에도 API에 대한 IAM 인증을 구성합니다. IAM 서비스로 사용자를 인증한 후에는 API가 사용자에게 연결된 정책과 리소스 정책을 모두 평가합니다. 그 결과는 호출자가 동일한 AWS 계정에 있는지 또는 API 소유자의 별도 AWS 계정에 있는지에 따라 달라집니다.
호출자와 API 소유자가 각기 다른 계정에 있는 경우, IAM 정책과 리소스 정책 모두 호출자가 진행하도록 명시적으로 허용합니다. 자세한 내용은 [테이블 B](#apigateway-resource-policies-iam-policies-interaction)를 참조하세요.
그러나 호출자와 API 소유자가 동일한 AWS 계정에 있는 경우, IAM 사용자 정책 또는 리소스 정책 중 하나에서 호출자가 진행하도록 명시적으로 허용합니다. 자세한 내용은 [테이블 A](#apigateway-resource-policies-iam-policies-interaction)를 참조하세요.
![\[리소스 정책과 IAM 인증의 권한 부여 흐름.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/apigateway-auth-iam-resource-policy.png)
다음은 교차 계정 리소스 정책의 예입니다. IAM 정책에 허용 효과가 포함되어 있다고 가정할 때, 이 리소스 정책은 VPC ID가 `vpc-2f09a348`인 VPC로부터의 호출만을 허용합니다 자세한 내용은 [테이블 B](#apigateway-resource-policies-iam-policies-interaction)를 참조하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/"
],
"Condition" : {
"StringEquals": {
"aws:SourceVpc": "vpc-2f09a348"
}
}
}
]
}
```
------
## Amazon Cognito 인증 및 리소스 정책
이 워크플로에서는 리소스 정책 외에 API에 대해 [Amazon Cognito 사용자 풀](apigateway-integrate-with-cognito.md)이 구성됩니다. API Gateway는 먼저 Amazon Cognito를 통해 호출자에게 권한을 부여하려 합니다. 이는 보통 호출자가 제공하는 [JWT 토큰](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)을 통해 수행됩니다. 인증에 성공하면, 리소스 정책이 독립적으로 평가되고 명시적 허용이 필요해집니다. 거부 또는 “허용도 거부도 아님”인 경우에는 거부됩니다. 다음은 Amazon Cognito 사용자 풀과 함께 사용될 수 있는 리소스 정책의 예제입니다.
![\[리소스 정책과 Amazon Cognito 권한 부여자의 권한 부여 흐름.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/apigateway-auth-cognito-resource-policy.png)
다음은 Amazon Cognito 인증 토큰에 허용이 포함되어 있다는 가정하에 지정된 소스 IP로부터의 호출만을 허용하는 리소스 정책의 예제입니다 자세한 내용은 [테이블 B](#apigateway-resource-policies-iam-policies-interaction)를 참조하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/",
"Condition": {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
## 정책 평가 결과표
테이블 A에는 API Gateway API에 대한 액세스가 IAM 정책 또는 Lambda 권한 부여자 및 API Gateway 리소스 정책에 의해 제어되고, 이러한 두 정책이 모두 동일한 AWS 계정에 있을 때 결과로 수행되는 동작이 나와 있습니다.
| **IAM 정책(또는 Lambda 권한 부여자)** | **API Gateway 리소스 정책** | **결과적 동작** |
| --- | --- | --- |
| 허용 | 허용 | 허용 |
| 허용 | 허용도 거부도 아님 | 허용 |
| 허용 | 거부 | 명시적 거부 |
| 허용도 거부도 아님 | 허용 | 허용 |
| 허용도 거부도 아님 | 허용도 거부도 아님 | 암시적 거부 |
| 허용도 거부도 아님 | 거부 | 명시적 거부 |
| 거부 | 허용 | 명시적 거부 |
| 거부 | 허용도 거부도 아님 | 명시적 거부 |
| 거부 | 거부 | 명시적 거부 |
테이블 B에는 API Gateway API에 대한 액세스가 IAM 정책 또는 Amazon Cognito 사용자 풀 권한 부여자 및 API Gateway 리소스 정책 에 의해 제어되고, 이러한 정책이 서로 다른 AWS 계정에 있을 때 결과로 수행되는 동작이 나와 있습니다. 허용되지도 거부되지도 않으면, 교차 계정 액세스가 거부됩니다. 왜냐하면 크로스 계정 액세스를 위해서는 리소스 정책과 IAM 정책 또는 Amazon Cognito 사용자 풀 권한 부여자 모두에서 액세스를 명시적으로 허용해야 하기 때문입니다.
| **IAM 정책(또는 Amazon Cognito 사용자 풀 권한 부여자)** | **API Gateway 리소스 정책** | **결과적 동작** |
| --- | --- | --- |
| 허용 | 허용 | 허용 |
| 허용 | 허용도 거부도 아님 | 암시적 거부 |
| 허용 | 거부 | 명시적 거부 |
| 허용도 거부도 아님 | 허용 | 암시적 거부 |
| 허용도 거부도 아님 | 허용도 거부도 아님 | 암시적 거부 |
| 허용도 거부도 아님 | 거부 | 명시적 거부 |
| 거부 | 허용 | 명시적 거부 |
| 거부 | 허용도 거부도 아님 | 명시적 거부 |
| 거부 | 거부 | 명시적 거부 |
# API Gateway 리소스 정책 예제
이 페이지에서는 API Gateway 리소스 정책의 일반적인 사용 사례에 대한 몇 가지 예제를 제시합니다.
다음 예제 정책은 간소화된 구문을 사용하여 API 리소스를 지정합니다. 이 간소화된 구문은 전체 Amazon 리소스 이름(ARN)을 지정하는 대신 API 리소스를 참조할 수 있는 약식 방법입니다. API Gateway는 정책을 저장할 때 약어 구문을 전체 ARN으로 변환합니다. 예를 들어 리소스 정책에서 `execute-api:/stage-name/GET/pets` 리소스를 지정할 수 있습니다. API Gateway는 리소스 정책을 저장할 때 이 리소스를 `arn:aws:execute-api:us-east-2:123456789012:aabbccddee/stage-name/GET/pets`로 변환합니다. API Gateway는 현재 리전, AWS 계정 ID 및 리소스 정책이 연결된 REST API의 ID를 사용하여 전체 ARN을 구축합니다. `execute-api:/*`를 사용하여 현재 API의 모든 단계, 메서드 및 경로를 나타낼 수 있습니다. 액세스 정책 언어에 대한 자세한 내용은 [Amazon API Gateway에 대한 액세스 정책 언어 개요](apigateway-control-access-policy-language-overview.md) 단원을 참조하세요.
**Topics**
+ [예제: 다른 AWS 계정의 역할이 API를 사용하도록 허용](#apigateway-resource-policies-cross-account-example)
+ [예제: 소스 IP 주소 또는 범위에 따라 API 트래픽 거부](#apigateway-resource-policies-source-ip-address-example)
+ [예: 프라이빗 API를 사용할 때 소스 IP 주소 또는 범위를 기반으로 API 트래픽 거부](#apigateway-resource-policies-source-ip-address-vpc-example)
+ [예제: 소스 VPC 또는 VPC 종단점에 따라 프라이빗 API 트래픽 허용](#apigateway-resource-policies-source-vpc-example)
## 예제: 다른 AWS 계정의 역할이 API를 사용하도록 허용
다음의 리소스 정책 예제는 [Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html)(SigV4) 또는 [Signature Version 4a](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works)(SigV4a) 프로토콜을 통해 한 AWS 계정의 API 액세스 권한을 다른 AWS 계정의 두 역할에 부여합니다. 예를 들면 `account-id-2`로 식별된 AWS 계정의 개발자와 관리자 역할에 AWS 계정의 `pets` 리소스(API)에서 `GET` 작업을 실행할 수 있는 `execute-api:Invoke` 작업에 대한 권한이 부여됩니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/developer",
"arn:aws:iam::111122223333:role/Admin"
]
},
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/stage/GET/pets"
]
}
]
}
```
------
## 예제: 소스 IP 주소 또는 범위에 따라 API 트래픽 거부
아래의 리소스 정책 예제에서는 2개의 지정된 소스 IP 주소 블록에서 API로 들어오는 트래픽을 거부(차단)합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
IAM 사용자 정책 또는 API Gateway 리소스 정책을 사용하여 API Gateway 또는 API Gateway API에 대한 액세스를 제어하는 경우 정책이 IPv6 주소 범위를 포함하도록 업데이트되었는지 확인합니다. IPv6 주소를 처리하도록 업데이트되지 않은 정책은 클라이언트가 듀얼 스택 엔드포인트를 사용하기 시작할 때 API Gateway에 대한 클라이언트의 액세스에 영향을 미칠 수 있습니다. 자세한 내용은 [IAM 정책에서 IPv6 주소 사용](api-ref.md#api-reference-service-endpoints-dualstack-iam) 섹션을 참조하세요.
## 예: 프라이빗 API를 사용할 때 소스 IP 주소 또는 범위를 기반으로 API 트래픽 거부
아래의 리소스 정책 예제에서는 2개의 지정된 소스 IP 주소 블록에서 프라이빗 API로 들어오는 트래픽을 거부(차단)합니다. 프라이빗 API를 사용할 때 `execute-api`의 VPC 종단점은 원래 소스 IP 주소를 다시 기록합니다. `aws:VpcSourceIp` 조건은 원래 요청자 IP 주소를 기준으로 요청을 필터링합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:VpcSourceIp": ["192.0.2.0/24", "198.51.100.0/24"]
}
}
}
]
}
```
------
## 예제: 소스 VPC 또는 VPC 종단점에 따라 프라이빗 API 트래픽 허용
다음 예제의 리소스 정책에서는 지정된 Virtual Private Cloud(VPC) 또는 VPC 종단점에서 오는 수신 트래픽만 프라이빗 API에 액세스하도록 허용합니다.
이 리소스 정책 예제는 소스 VPC를 지정합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpc": "vpc-1a2b3c4d"
}
}
}
]
}
```
------
이 리소스 정책 예제는 소스 VPC 종단점을 지정합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
}
]
}
```
------
# API Gateway 리소스 정책을 생성하여 API에 연결
사용자가 API 실행 서비스를 호출하여 API에 액세스하도록 허용하려면 API Gateway 리소스 정책을 생성하고 이 정책을 API에 연결해야 합니다. API에 정책을 연결하면 정책의 해당 권한이 API의 메서드에 적용됩니다. 리소스 정책을 업데이트하는 경우 API를 배포해야 합니다.
**Topics**
+ [사전 조건](#apigateway-resource-policies-prerequisites)
+ [API Gateway API에 리소스 정책 연결](#apigateway-resource-policies-create-attach-procedure)
+ [리소스 정책 문제 해결](#apigateway-resource-policies-troubleshoot)
## 사전 조건
API Gateway 리소스 정책을 업데이트하려면 `apigateway:UpdateRestApiPolicy` 권한과 `apigateway:PATCH` 권한이 있어야 합니다.
엣지 최적화 또는 리전 API의 경우 API를 생성할 때 또는 배포한 후에 리소스 정책을 API에 연결할 수 있습니다. 프라이빗 API의 경우 리소스 정책 없이는 API를 배포할 수 없습니다. 자세한 내용은 [API Gateway의 프라이빗 REST API](apigateway-private-apis.md) 섹션을 참조하세요.
## API Gateway API에 리소스 정책 연결
다음 절차는 API Gateway API에 리소스 정책을 연결하는 방법을 보여줍니다.
------
#### [ AWS Management Console ]
**API Gateway API에 리소스 정책을 연결하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 기본 탐색 창에서 **리소스 정책**을 선택합니다.
1. **정책 생성**을 선택합니다.
1. (선택 사항) 예제 정책을 생성하려면 **템플릿 선택**을 선택합니다.
여기 나온 정책 예제에서는 자리 표시자가 이중 중괄호(`"{{placeholder}}"`)로 묶여 있습니다. 중괄호를 포함한 각각의 자리 표시자를 필요한 정보로 바꿉니다.
1. 템플릿 예제 중 하나를 사용하지 않는 경우에는 리소스 정책을 입력합니다.
1. **변경 사항 저장**을 선택합니다.
API Gateway 콘솔에서 이미 배포한 API라면 다시 배포해야 리소스 정책이 적용됩니다.
------
#### [ AWS CLI ]
AWS CLI를 사용하여 새 API를 생성하고 여기에 리소스 정책을 연결하려면 다음 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 명령을 사용합니다.
```
aws apigateway create-rest-api \
--name "api-name" \
--policy "{\"jsonEscapedPolicyDocument\"}"
```
AWS CLI를 사용하여 기존 API에 리소스 정책을 연결하려면 다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령을 사용합니다.
```
aws apigateway update-rest-api \
--rest-api-id api-id \
--patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"'
```
리소스 정책을 별도의 `policy.json` 파일로 첨부하여 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 명령에 포함할 수도 있습니다. 다음 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 명령은 리소스 정책을 사용하여 새 API를 생성합니다.
```
aws apigateway create-rest-api \
--name "api-name" \
--policy file://policy.json
```
`policy.json`은 API Gateway 리소스 정책(예: [예제: 소스 IP 주소 또는 범위에 따라 API 트래픽 거부](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example))입니다.
------
#### [ AWS CloudFormation ]
CloudFormation를 사용하여 리소스 정책을 사용하여 API를 생성할 수 있습니다. 다음 예시에서는 예제 리소스 정책인 [예제: 소스 IP 주소 또는 범위에 따라 API 트래픽 거부](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example)을 사용하여 REST API를 만듭니다.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: testapi
Policy:
Statement:
- Action: 'execute-api:Invoke'
Effect: Allow
Principal: '*'
Resource: 'execute-api:/*'
- Action: 'execute-api:Invoke'
Effect: Deny
Principal: '*'
Resource: 'execute-api:/*'
Condition:
IpAddress:
'aws:SourceIp': ["192.0.2.0/24", "198.51.100.0/24" ]
Version: 2012-10-17
Resource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'helloworld'
MethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref Resource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: MOCK
RequestTemplates:
application/json: '{"statusCode": 200}'
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: '{}'
MethodResponses:
- StatusCode: 200
ResponseModels:
application/json: 'Empty'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- MethodGet
Properties:
RestApiId: !Ref Api
StageName: test
```
------
## 리소스 정책 문제 해결
다음 문제 해결 지침은 리소스 정책 관련 문제를 해결하는 데 도움이 될 수 있습니다.
### 내 API에서 \$1"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: arn:aws:execute-api:us-east-1:\$1\$1\$1\$1\$1\$1\$1\$1/\$1\$1\$1\$1/\$1\$1\$1\$1/"\$1를 반환합니다.
리소스 정책에서 다음과 같이 보안 주체를 AWS 보안 주체로 설정하는 경우
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111111111111:role/developer",
"arn:aws:iam::111111111111:role/Admin"
]
},
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/stage/GET/pets"
]
}
]
}
```
------
API의 모든 메서드에 `AWS_IAM` 권한 부여를 사용해야 합니다. 그렇지 않으면 API가 이전 오류 메시지를 반환합니다. 메서드에 대한 `AWS_IAM` 권한 부여를 켜는 방법에 대한 자세한 지침은 [API Gateway의 REST API 메서드](how-to-method-settings.md) 섹션을 참조하세요.
### 내 리소스 정책이 업데이트되지 않습니다.
API가 생성된 후에 리소스 정책을 업데이트하려면 업데이트된 정책을 연결한 후에 변경 내용이 전파되도록 API를 배포해야 합니다. 정책을 업데이트 또는 저장하는 것만으로는 API의 실행 시간 동작이 변경되지 않습니다. API 배포에 대한 자세한 내용은 [API Gateway에서 REST API 배포](how-to-deploy-api.md) 단원을 참조하세요.
### 리소스 정책에서 ‘정책 문서가 잘못됨’이라는 오류가 반환됩니다. 정책 구문을 확인하고 보안 주체가 유효한지 확인하세요.
이 오류를 해결하려면 먼저 정책 구문을 확인하는 것이 좋습니다. 자세한 내용은 [Amazon API Gateway에 대한 액세스 정책 언어 개요](apigateway-control-access-policy-language-overview.md) 섹션을 참조하세요. 또한 지정된 모든 보안 주체가 유효하고 삭제되지 않았는지 확인하는 것이 좋습니다.
또한 API가 [옵트인 리전](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html?icmpid=docs_homepage_addtlrcs#optinregion)에 있는 경우 리소스 정책의 모든 계정에 리전이 활성화되어 있는지 확인하세요.
# AWSAPI Gateway 리소스 정책에 사용할 수 있는 조건 키
다음 표에는 각각의 권한 부여 유형에 대해 API Gateway에서 API를 위한 리소스 정책에서 사용할 수 있는 AWS 조건 키가 포함되어 있습니다.
AWS 조건 키에 대한 자세한 내용은 [AWS 전역 조건 컨텍스트 키](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) 단원을 참조하세요.
| **조건 키**: | **기준** | **이 필요합니까?`AuthN`** | **권한 부여 유형** |
| --- | --- | --- | --- |
| aws:CurrentTime | 없음 | 아니요 | 모두 |
| aws:EpochTime | 없음 | 아니요 | 모두 |
| aws:TokenIssueTime | 임시 보안 자격 증명을 사용해 서명된 요청에만 키가 존재합니다. | 예 | IAM |
| aws:MultiFactorAuthPresent | 임시 보안 자격 증명을 사용해 서명된 요청에만 키가 존재합니다. | 예 | IAM |
| aws:MultiFactorAuthAge | MFA가 요청에 존재하는 경우에만 키가 존재합니다. | 예 | IAM |
| aws:PrincipalAccount | 없음 | 예 | IAM |
| aws:PrincipalArn | 없음 | 예 | IAM |
| aws:PrincipalOrgID | 이 키는 보안 주체가 조직의 멤버인 경우에만 요청 컨텍스트에 포함됩니다. | 예 | IAM |
| aws:PrincipalOrgPaths | 이 키는 보안 주체가 조직의 멤버인 경우에만 요청 컨텍스트에 포함됩니다. | 예 | IAM |
| aws:PrincipalTag | 이 키는 보안 주체가 태그가 연결된 IAM 사용자를 사용하는 경우 요청 컨텍스트에 포함됩니다. 연결된 태그 또는 세션 태그가 있는 IAM 역할을 사용하는 보안 주체에 포함됩니다. | 예 | IAM |
| aws:PrincipalType | 없음 | 예 | IAM |
| aws:Referer | HTTP 헤더에서 호출자가 값을 제공하는 경우에만 키가 존재합니다. | 아니요 | 모두 |
| aws:SecureTransport | 없음 | 아니요 | 모두 |
| aws:SourceArn | 없음 | 아니요 | 모두 |
| aws:SourceIp | 없음 | 아니요 | 모두 |
| aws:SourceVpc | 이 키는 프라이빗 API에만 사용할 수 있습니다. | 아니요 | 모두 |
| aws:SourceVpce | 이 키는 프라이빗 API에만 사용할 수 있습니다. | 아니요 | 모두 |
| aws:VpcSourceIp | 이 키는 프라이빗 API에만 사용할 수 있습니다. | 아니요 | 모두 |
| aws:UserAgent | HTTP 헤더에서 호출자가 값을 제공하는 경우에만 키가 존재합니다. | 아니요 | 모두 |
| aws:userid | 없음 | 예 | IAM |
| aws:username | 없음 | 예 | IAM |
# IAM 권한을 사용하여 REST API에 대한 액세스 제어
다음 두 API Gateway 구성 요소 프로세스에 대한 액세스를 제어하여 [IAM 권한](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html)을 통해 Amazon API Gateway API에 대한 액세스를 제어합니다.
+ API Gateway에서 API를 생성, 배포, 관리하려면 API 개발자에게 API Gateway의 API 관리 구성 요소에서 지원되는 필수 작업을 수행할 수 있는 권한을 부여해야 합니다.
+ 배포된 API를 호출하거나 API 캐시를 새로 고치려면 API Gateway의 API 실행 구성 요소에서 지원되는 필요한 IAM 작업을 수행할 권한을 API 호출자에게 부여해야 합니다.
두 프로세스에 대한 액세스 제어에는 다음에 설명하는 서로 다른 권한 모델이 포함됩니다.
## API 생성 및 관리를 위한 API Gateway 권한 모델
API 개발자가 API Gateway에서 API를 생성하고 관리할 수 있도록 허용하려면 지정된 API 개발자가 필수 [API 엔터티](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)를 생성, 업데이트, 배포, 보기 또는 삭제할 수 있도록 허용하는 [IAM 권한 정책을 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)해야 합니다. 사용자, 역할 또는 그룹에 권한 정책을 연결합니다.
액세스 권한을 제공하려면 사용자, 그룹 또는 역할에 권한을 추가하세요.
+ AWS IAM Identity Center의 사용자 및 그룹:
권한 세트를 생성합니다. *AWS IAM Identity Center 사용자 안내서*에서 [권한 세트 생성](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)의 지침을 따릅니다.
+ ID 제공업체를 통해 IAM에서 관리되는 사용자:
ID 페더레이션을 위한 역할을 생성합니다. *IAM 사용자 설명서*의 [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)의 지침을 따릅니다.
+ IAM 사용자:
+ 사용자가 맡을 수 있는 역할을 생성합니다. *IAM 사용자 설명서*에서 [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)의 지침을 따릅니다.
+ (권장되지 않음) 정책을 사용자에게 직접 연결하거나 사용자를 사용자 그룹에 추가합니다. *IAM 사용 설명서*에서 [사용자(콘솔)에 권한 추가](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console)의 지침을 따릅니다.
이 권한 모델을 사용하는 방법에 대한 자세한 내용은 [API Gateway 자격 증명 기반 정책](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies) 단원을 참조하세요.
## API 호출을 위한 API Gateway 권한 모델
API 호출자가 API를 호출하거나 캐싱을 새로 고치도록 허용하려면 지정된 API 호출자에게 사용자 인증이 사용되는 API 메서드를 호출하도록 허용하는 IAM 정책을 생성해야 합니다. API 개발자는 메서드의 `authorizationType` 속성을 `AWS_IAM`으로 설정하여 인증받을 사용자의 보안 인증 정보를 제출하도록 호출자에게 요구합니다. API Gateway는 사용자의 자격 증명을 인증하기 위해 Signature Version 4a(SigV4a) 및 Signature Version 4(SigV4)를 지원합니다. 자세한 내용은 [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)를 참조하세요. 그런 다음 정책을 사용자, 역할 또는 그룹에 연결할 수 있습니다.
이 IAM 권한 정책 설명에서, IAM `Resource` 요소는 지정된 HTTP 동사와 API Gateway [리소스 경로](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)로 식별할 수 있는 배포된 API 메서드 목록을 포함합니다. IAM `Action` 요소는 필요한 API Gateway API 실행 작업을 포함합니다. 이러한 작업은 `execute-api:Invoke` 또는 `execute-api:InvalidateCache`를 포함합니다. 여기서 `execute-api`는 API Gateway의 기본 API 실행 구성 요소를 지정합니다.
이 권한 모델을 사용하는 방법에 대한 자세한 내용은 [API 호출을 위한 액세스 제어](api-gateway-control-access-using-iam-policies-to-invoke-api.md) 단원을 참조하세요.
API가 백엔드에서 AWS 서비스(예: AWS Lambda)와 통합될 경우 API Gateway에도 API 호출자를 대신하여 통합된 AWS 리소스(예: Lambda 함수 호출)에 액세스할 권한이 있어야 합니다. 이러한 권한을 부여하려면 **API Gateway용 AWS 서비스** 유형의 IAM 역할을 생성합니다. IAM 관리 콘솔에서 이 역할을 생성하면 이 결과 역할에는 API Gateway를 역할을 수임하도록 허용되는 신뢰할 수 있는 개체로 선언하는 다음 IAM 신뢰 정책이 포함됩니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
CLI [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) 명령 또는 동등한 SDK 메서드를 호출하여 IAM 역할을 생성할 경우 `assume-role-policy-document`의 입력 파라미터로 상기 신뢰 정책을 제공해야 합니다. IAM 관리 콘솔에서 직접, 또는 AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) 명령 또는 동등한 SDK 메서드를 호출하여 그러한 정책을 생성하려 하지 마세요.
API Gateway가 통합된 AWS 서비스를 호출하려면, 이 역할에 통합된 AWS 서비스를 호출하는 데 적절한 IAM 권한 정책도 연결해야 합니다. 예를 들어 Lambda 함수를 호출하려면 IAM 역할에 다음 IAM 권한 정책을 포함해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}
```
------
Lambda는 신뢰 정책과 권한 정책을 결합한 리소스 기반 액세스 정책을 지원합니다. API Gateway 콘솔을 사용하여 API를 Lambda 함수와 통합할 경우 콘솔에서 사용자의 동의를 받아 Lambda 함수에 대한 리소스 기반 권한을 자동으로 설정하므로 이 IAM 역할을 명시적으로 설정하라는 메시지가 표시되지 않습니다.
**참고**
AWS 서비스에 대한 액세스 제어를 적용하려면 권한 정책이 호출자의 사용자 또는 그룹에 직접 연결되는 호출자 기반 권한 모델을 사용하거나 권한 정책이 API Gateway에서 가정할 수 있는 IAM 역할에 연결되는 역할 기반 권한 모델을 사용할 수 있습니다. 두 모델의 권한 정책은 다를 수 있습니다. 예를 들어 호출자 기반 정책에서는 액세스를 차단하고 역할 기반 정책에서는 액세스를 허용할 수 있습니다. 이를 활용하여 사용자에게 API Gateway API를 통해서만 AWS 서비스에 액세스하도록 요구할 수 있습니다.
# API 호출을 위한 액세스 제어
이 섹션에서는 IAM 권한을 사용하여 API에 대한 액세스를 제어하는 권한 모델에 대해 알아봅니다. IAM 권한 부여가 활성화된 경우 클라이언트는 Signature Version 4a(SigV4a) 및 Signature Version 4(SigV4)를 사용하여 AWS 자격 증명으로 요청에 서명해야 합니다. 자세한 내용은 [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)를 참조하세요.
이 섹션에서는 템플릿 IAM 정책 설명과 정책 설명 참조를 보여줍니다. 정책 설명 참조에는 API 실행 서비스와 관련된 `Action` 및 `Resource` 필드의 형식도 포함되어 있습니다. 이러한 참조를 사용하여 IAM 정책 설명을 생성합니다. IAM 정책 설명을 생성할 때 API Gateway 리소스 정책이 권한 부여 워크플로에 미치는 영향을 고려해야 할 수 있습니다. 자세한 내용은 [API Gateway 리소스 정책이 권한 부여 워크플로우에 미치는 영향](apigateway-authorization-flow.md) 섹션을 참조하세요.
프라이빗 API의 경우 API Gateway 리소스 정책과 VPC 종단점 정책을 조합하여 사용해야 합니다. 자세한 정보는 다음 주제를 참조하세요.
+ [API Gateway 리소스 정책을 사용하여 REST API에 대한 액세스 제어](apigateway-resource-policies.md)
+ [API Gateway의 프라이빗 API에 대한 VPC 종단점 정책 사용](apigateway-vpc-endpoint-policies.md)
## IAM 정책을 사용하여 API Gateway API 메서드를 호출할 수 있는 사용자 제어
IAM 권한을 사용하여 배포된 API를 호출할 수 있는 사용자와 호출할 수 없는 사용자를 제어하려면 필요한 권한을 사용하여 IAM 정책 문서를 생성합니다. 그런 정책 문서에 대한 템플릿은 다음과 같습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Permission",
"Action": [
"execute-api:Execution-operation"
],
"Resource": [
"arn:aws:execute-api:region:123456789012:api-id/stage/METHOD_HTTP_VERB/Resource-path"
]
}
]
}
```
------
여기서 포함된 권한을 부여할지 취소할지 여부에 따라 `Permission`은 `Allow` 또는 `Deny`로 대체됩니다. `Execution-operation`은 API 실행 서비스에서 지원되는 작업으로 대체됩니다. `METHOD_HTTP_VERB`는 지정된 리소스에서 지원되는 HTTP 동사를 나타냅니다. `Resource-path`는 해당 `[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)`를 지원하는 배포된 API `METHOD_HTTP_VERB` 인스턴스의 URL 경로에 대한 자리 표시자입니다. 자세한 내용은 [API Gateway에서 API 실행을 위한 IAM 정책의 설명 참조](#api-gateway-calling-api-permissions) 단원을 참조하세요.
**참고**
IAM 정책을 적용하려면 메서드의 `AWS_IAM` 속성에 대한 `[authorizationType](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)`을 설정하여 API 메서드에서 IAM 인증을 활성화해야 합니다. 그렇지 않은 경우 API 메서드에 공개적으로 액세스할 수 있습니다.
예를 들어 사용자에게 지정된 API 노출 반려 동물 목록을 볼 수 있는 권한을 부여하고, 목록에 반려 동물을 추가할 수 있는 권한을 거부하려면 IAM 정책에 다음 명령문을 포함하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/*/POST/pets"
]
}
]
}
```
------
사용자에게 `GET /pets/{petId}`로 구성된 API를 통해 공개된 특정 반려 동물을 볼 수 있는 권한을 부여하려면, IAM 정책에 다음 명령문을 포함합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/*/GET/pets/a1b2"
]
}
]
}
```
------
## API Gateway에서 API 실행을 위한 IAM 정책의 설명 참조
다음은 API 실행을 위한 액세스 권한에 대한 IAM 정책 설명의 작업 및 리소스 형식입니다.
### API Gateway의 API 실행 권한 작업 형식
API 실행 `Action` 표현식의 일반적인 형식은 다음과 같습니다.
```
execute-api:action
```
여기서 *작업*은 사용 가능한 API 실행 작업입니다.
+ **\$1**는 다음의 모든 작업을 나타냅니다.
+ **호출**은 클라이언트 요청에 따라 API를 호출하는 데 사용됩니다.
+ **InvalidateCache**는 클라이언트 요청에 따라 API 캐시를 무효화하는 데 사용됩니다.
### API Gateway의 API 실행 권한 리소스 형식
API 실행 `Resource` 표현식의 일반적인 형식은 다음과 같습니다.
```
arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier
```
여기서 각 항목은 다음과 같습니다.
+ *region*은 메서드에 대해 배포된 API에 해당하는 AWS 리전(예: **us-east-1** 또는 **\$1**(모든 AWS 리전))입니다.
+ *account-id*는 REST API 소유자의 12자리 AWS 계정 ID입니다.
+ *api-id*는 API Gateway에서 메서드에 대한 API에 할당한 식별자입니다.
+ *stage-name*은 메서드와 연결된 스테이지의 이름입니다.
+ *HTTP-VERB*는 메서드에 대한 HTTP 동사입니다. GET, POST, PUT, DELETE, PATCH 중 하나일 수 있습니다.
+ *resource-path-specifier*는 원하는 메서드의 경로입니다.
**참고**
와일드카드(`*`)를 지정하는 경우 `Resource` 표현식에서 표현식의 나머지에 와일드카드가 적용됩니다.
다음은 리소스 표현식의 몇 가지 예입니다.
+ **arn:aws:execute-api:\$1:\$1:\$1**는 모든 단계의 모든 리소스 경로와 모든 AWS 리전의 모든 API를 나타내며,
+ **arn:aws:execute-api:us-east-1:\$1:\$1**는 모든 단계의 모든 리소스 경로와 AWS의 `us-east-1` 리전의 모든 API를 나타내며,
+ **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1**는 모든 단계의 모든 리소스 경로와 AWS 리전(us-east-1)에서 식별자가 *api-id*인 API를 나타냅니다.
+ **arn:aws:execute-api:us-east-1:\$1:*api-id*/`test`/\$1**는 `test` 단계의 리소스 경로와 AWS 리전(us-east-1)에서 식별자가 *api-id*인 API를 나타냅니다.
자세한 내용은 [API Gateway Amazon 리소스 이름(ARN) 참조](arn-format-reference.md)를 참조하세요.
# API 실행 권한에 대한 IAM 정책 예
권한 모델 및 기타 배경 정보는 [API 호출을 위한 액세스 제어](api-gateway-control-access-using-iam-policies-to-invoke-api.md) 단원을 참조하세요.
다음 정책 설명은 사용자에게 `mydemoresource` 경로를 따라 `test` 단계에서 식별자가 `a123456789`인 API에 대해 POST 메서드를 호출할 수 있는 권한을 부여합니다. 여기서는 해당 API가 AWS 리전(us-east-1)에 배포된 것으로 가정합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*"
]
}
]
}
```
------
다음 예제 정책 설명은 사용자에게 모든 단계의 `petstorewalkthrough/pets` 리소스 경로에서 해당 API가 배포된 `a123456789` 리전에서 식별자가 AWS인 API에 대해 모든 메서드를 호출할 수 있는 권한을 부여합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets"
]
}
]
}
```
------
# API Gateway의 프라이빗 API에 대한 VPC 종단점 정책 사용
프라이빗 API의 보안을 강화하기 위해 VPC 엔드포인트 정책을 생성할 수 있습니다. VPC 엔드포인트 정책은 VPC 엔드포인트에 연결할 수 있는 IAM 리소스 정책입니다. 자세한 정보는 [VPC 종단점을 통해 서비스에 대한 액세스 제어](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html)를 참조하세요.
VPC 엔드포인트 정책을 생성하여 다음을 생성하는 것이 좋습니다.
+ 특정 조직 또는 리소스만 VPC 엔드포인트에 액세스하고 API를 간접적으로 호출하도록 허용합니다.
+ 단일 정책을 사용하고 세션 기반 또는 역할 기반 정책을 피하여 API로 향하는 트래픽을 제어합니다.
+ 온프레미스에서 AWS로 마이그레이션하는 동안 애플리케이션의 보안 경계를 강화합니다.
## VPC 엔드포인트 정책 고려 사항
다음은 VPC 엔드포인트 정책에 대한 고려 사항입니다.
+ 호출자의 ID는 `Authorization` 헤더 값을 기반으로 평가됩니다. VPC 엔드포인트 정책이 먼저 평가된 후 API Gateway가 메서드 요청에 구성된 권한 부여 유형에 따라 요청을 평가합니다. 다음 표는 `Authorization` 헤더 값의 내용을 기반으로 VPC 엔드포인트 정책이 평가되는 방법을 보여줍니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-vpc-endpoint-policies.html)
+ 액세스 제어가 Lambda 또는 Amazon Cognito 권한 부여자와 같은 보유자 토큰 사용에 의존하는 경우 [리소스의 속성](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties)을 사용하여 보안 경계를 제어할 수 있습니다.
+ 권한 부여 제어에서 IAM 권한 부여를 사용하는 경우 [리소스의 속성](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties)과 [보안 주체의 속성](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-principal)을 사용하여 보안 경계를 제어할 수 있습니다.
+ VPC 종단점 정책은 API Gateway 리소스 정책과 함께 사용할 수 있습니다. API Gateway 리소스 정책은 API에 액세스할 수 있는 보안 주체를 지정합니다. 엔드포인트 정책은 VPC에 액세스할 수 있는 사용자와 VPC 엔드포인트에서 직접적으로 호출할 수 있는 API를 지정합니다. 프라이빗 API에는 리소스 정책이 필요하지만 사용자 지정 VPC 엔드포인트 정책을 생성할 필요는 없습니다.
## VPC 엔드포인트 정책 예제
Amazon API Gateway에 대한 Amazon Virtual Private Cloud 엔드포인트 정책을 생성하여 다음을 지정할 수 있습니다.
+ 작업을 수행할 수 있는 보안 주체.
+ 수행할 수 있는 작업.
+ 작업을 수행할 수 있는 리소스.
이는 권한 부여 헤더의 내용에 따라 달라질 수 있습니다. 자세한 내용은 [VPC 엔드포인트 정책 고려 사항](#apigateway-vpc-endpoint-policies-considerations) 섹션을 참조하세요. 추가 정책 예제는 GitHub 웹사이트의 [Data perimeter policy examples](https://github.com/aws-samples/data-perimeter-policy-examples)를 참조하세요.
VPC 종단점에 정책을 첨부하려면 VPC 콘솔을 사용해야 합니다. 자세한 정보는 [VPC 종단점을 통해 서비스에 대한 액세스 제어](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html)를 참조하세요.
## 예제 1: 두 API에 대한 액세스 권한을 부여하는 VPC 종단점 정책
다음 예제 정책은 정책이 첨부된 VPC 종단점을 통해 두 개의 특정 API로만 액세스 권한을 부여합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": "*",
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*",
"arn:aws:execute-api:us-east-1:123412341234:aaaaa11111/*"
]
}
]
}
```
------
## 예제 2: GET 메서드에 대한 액세스 권한을 부여하는 VPC 종단점 정책
다음 예제 정책은 해당 정책이 연결된 VPC 종단점을 통해 특정 API에 대한 `GET` 메서드에 대한 액세스 권한을 사용자에게 부여합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": "*",
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/stageName/GET/*"
]
}
]
}
```
------
## 예제 3: 특정 API에 특정 사용자 액세스 권한을 부여하는 VPC 종단점 정책
다음 예제 정책은 정책이 연결된 VPC 종단점을 통한 특정 API에 대한 특정 사용자 액세스 권한을 부여합니다.
이 경우 정책에서 특정 IAM 보안 주체에 대한 액세스를 제한하기 때문에 메서드의 `authorizationType`을 `AWS_IAM` 또는 `NONE`으로 설정해야 합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": {
"AWS": [
"arn:aws:iam::123412341234:user/MyUser"
]
},
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*"
]
}
]
}
```
------
## 예제 4: 사용자에게 특정 사용자 지정 도메인 이름과 도메인에 매핑된 모든 API에 대한 액세스 권한을 부여하는 VPC 엔드포인트 정책
다음 예제 정책은 해당 정책이 연결된 VPC 엔드포인트를 통해 특정 사용자 지정 도메인 이름에 대한 액세스 권한을 사용자에게 부여합니다. 이 정책을 사용하면 사용자가 VPC 엔드포인트와 사용자 지정 도메인 이름 간에 도메인 이름 액세스 연결을 생성하고 사용자 지정 도메인 이름과 사용자 지정 도메인 이름에 매핑된 프라이빗 API를 간접적으로 호출할 수 있는 액세스 권한이 부여되는 한, 사용자는 이 사용자 지정 도메인 이름에 매핑된 모든 API를 간접적으로 호출할 수 있습니다. 자세한 내용은 [API Gateway의 프라이빗 API에 대한 사용자 지정 도메인 이름](apigateway-private-custom-domains.md) 섹션을 참조하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"*"
],
"Condition": {
"ArnEquals": {
"execute-api:viaDomainArn": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6",
}
}
}
]
}
```
------
## 예제 5: 특정 API 및 도메인 리소스에 대한 액세스 권한을 부여하거나 거부하는 VPC 엔드포인트 정책
다음 예제 정책은 사용자에게 특정 API 및 도메인 리소스에 대한 액세스 권한을 부여합니다. 이 정책을 사용하면 사용자가 VPC 엔드포인트와 사용자 지정 도메인 이름 간에 도메인 이름 액세스 연결을 생성하고 사용자 지정 도메인 이름 및 사용자 지정 도메인 이름에 매핑된 프라이빗 API를 간접적으로 호출할 수 있는 액세스 권한이 부여되는 한 사용자는 허용된 프라이빗 API 및 도메인 리소스를 간접적으로 호출할 수 있습니다. 자세한 내용은 [API Gateway의 프라이빗 API에 대한 사용자 지정 도메인 이름](apigateway-private-custom-domains.md) 섹션을 참조하세요.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6",
"arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/*"
]
},
{
"Effect": "Deny",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/admin/*",
"arn:aws:execute-api:us-west-2:111122223333:bcd123455/*"
]
}
]
}
```
------
## 예제 6: 조직에 속한 위탁자 및 리소스별로 액세스 권한을 부여하거나 거부하는 VPC 엔드포인트 정책
다음 예제 정책은 조직에 속한 위탁자 및 리소스에 대한 액세스 권한을 부여합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Condition": {
"StringEquals": {
"aws:ResourceOrgID": "o-abcd1234",
"aws:PrincipalOrgID": "o-abcd1234"
}
},
"Action": "*",
"Resource": "*",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources"
}
]
}
```
------
# API Gateway에서 태그를 사용하여 REST API에 대한 액세스 제어
IAM 정책에서 속성 기반 액세스 제어를 사용하여 REST API 액세스 권한을 미세 조정할 수 있습니다.
자세한 내용은 [태그를 사용하여 API Gateway REST API 리소스에 대한 액세스 제어](apigateway-tagging-iam-policy.md) 단원을 참조하십시오.
# API Gateway Lambda 권한 부여자 사용
*Lambda 권한 부여자*(이전 *사용자 지정 권한 부여자*)를 사용하여 API에 대한 액세스를 제어할 수 있습니다. 클라이언트가 API의 메서드를 요청하면 API Gateway는 Lambda 권한 부여자를 직접적으로 호출합니다. Lambda 권한 부여자는 호출자의 자격 증명을 입력으로 사용하고 IAM 정책을 출력으로 반환합니다.
Lambda 권한 부여자를 사용하여 사용자 지정 권한 부여 체계를 구현할 수 있습니다. 이 체계는 요청 파라미터를 사용하여 호출자의 자격 증명을 확인하거나 OAuth 또는 SAML과 같은 보유자 토큰 인증 전략을 사용할 수 있습니다. AWS CLI 또는 AWS SDK를 사용하여 API Gateway REST API 콘솔에서 Lambda 권한 부여자를 생성합니다.
## Lambda 권한 부여자 인증 워크플로
다음 다이어그램은 Lambda 권한 부여자에 대한 인증 워크플로를 보여줍니다.
![\[API Gateway Lambda 권한 부여 워크플로\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/custom-auth-workflow.png)
**API Gateway Lambda 권한 부여 워크플로**
1. 클라이언트가 API Gateway API의 메서드를 직접적으로 호출하고 보유자 토큰 또는 요청 파라미터를 전달합니다.
1. API Gateway는 메서드 요청에 Lambda 권한 부여자가 구성되어 있는지 확인합니다. 구성되어 있으면 API Gateway가 Lambda 함수를 호출합니다.
1. Lambda 함수가 호출자를 인증합니다. 이 함수는 다음과 같은 방식으로 인증될 수 있습니다.
+ OAuth 공급자를 직접적으로 호출하여 OAuth 액세스 토큰을 받습니다.
+ SAML 공급자를 직접적으로 호출하여 SAML 어설션을 받습니다.
+ 요청 파라미터 값을 기반으로 IAM 정책을 생성합니다.
+ 데이터베이스에서 자격 증명을 가져옵니다.
1. Lambda 함수가 IAM 정책과 보안 주체 식별자를 반환합니다. Lambda 함수가 해당 정보를 반환하지 않으면 직접 호출이 실패합니다.
1. API Gateway가 IAM 정책을 평가합니다.
+ 액세스가 거부되면 API Gateway는 적절한 HTTP 상태 코드(예: `403 ACCESS_DENIED`)를 반환합니다.
+ 액세스가 허용되면 API Gateway가 메서드를 간접 호출합니다.
권한 부여 캐싱이 활성화된 경우, API Gateway는 Lambda 권한 부여자 함수가 다시 간접적으로 호출되지 않도록 정책을 캐싱합니다. 정책이 API의 모든 리소스 및 메서드에 적용 가능한지 확인합니다.
`403 ACCESS_DENIED` 또는 `401 UNAUTHORIZED` 게이트웨이 응답을 사용자 지정할 수 있습니다. 자세한 내용은 [API Gateway의 REST API에 대한 게이트웨이 응답](api-gateway-gatewayResponse-definition.md)를 참조하세요.
## Lambda 권한 부여자 유형 선택
Lambda 권한 부여자는 두 가지 유형이 있습니다.
**요청 파라미터 기반 Lambda 권한 부여자(`REQUEST` 권한 부여자)**
`REQUEST` 권한 부여자는 헤더, 쿼리 문자열 파라미터, [`stageVariables`](api-gateway-mapping-template-reference.md#stagevariables-template-reference), [`$context`](api-gateway-mapping-template-reference.md#context-variable-reference) 변수 조합에 있는 직접 호출자 자격 증명을 받습니다. `REQUEST` 권한 부여자를 사용하여 `$context.path` 및 `$context.httpMethod` 컨텍스트 변수와 같은 여러 자격 증명 소스의 정보를 기반으로 세분화된 정책을 생성할 수 있습니다.
`REQUEST` 권한 부여자에 대한 권한 부여 캐싱을 켜면 API Gateway는 요청에 지정된 모든 자격 증명 소스가 있는지 확인합니다. 지정된 자격 증명 소스가 없거나, null이거나, 비어 있을 경우 API Gateway가 Lambda 권한 부여자 함수를 호출하지 않고 `401 Unauthorized` HTTP 응답을 반환합니다. 여러 개의 자격 증명 소스가 정의된 경우, 이들은 순서가 유지된 상태로 모두 권한 부여자의 캐시 키를 도출하는 데 사용됩니다. 여러 자격 증명 소스를 사용하여 세분화된 캐시 키를 정의할 수 있습니다.
캐시 키 부분을 변경하고 API를 재배포하면 권한 부여자가 캐시된 정책 문서를 폐기하고 새로 생성합니다.
`REQUEST` 권한 부여자에 대한 권한 부여 캐싱을 끄면 API Gateway가 요청을 Lambda 함수에 직접 전달합니다.
**토큰 기반 Lambda 권한 부여자(`TOKEN` 권한 부여자)**
`TOKEN` 권한 부여자는 보유자 토큰(JSON Web Token(JWT) 또는 OAuth 토큰)에 있는 호출자의 자격 증명을 받습니다.
`TOKEN` 권한 부여자에 대한 인증 캐싱을 켜는 경우 토큰 소스에 지정된 헤더 이름이 캐시 키가 됩니다.
또한 토큰 검증을 사용하여 정규 표현식 문을 입력할 수 있습니다. API Gateway는 이 표현식에 대해 입력 토큰의 초기 검증을 수행하고 검증에 성공할 경우 Lambda 권한 부여자 함수를 간접적으로 호출합니다. 이렇게 하면 API 호출을 줄일 수 있습니다.
`IdentityValidationExpression` 속성은 `TOKEN` 권한 부여자에만 지원됩니다. 자세한 내용은 [x-amazon-apigateway-authorizer 객체](api-gateway-swagger-extensions-authorizer.md) 섹션을 참조하세요.
**참고**
`REQUEST` 권한 부여자를 사용하여 API에 대한 액세스를 제어하는 것이 좋습니다. `TOKEN` 권한 부여자를 사용할 때는 단일 자격 증명 소스를 기반으로 하지만 `REQUEST` 권한 부여자를 사용할 때는 여러 자격 증명 소스를 기반으로 하여 API에 대한 액세스를 제어할 수 있습니다. 또한 `REQUEST` 권한 부여자의 경우 여러 자격 증명 소스를 사용하여 캐시 키를 분리할 수 있습니다.
## `REQUEST` 권한 부여자 Lambda 함수 예제
다음 예제 코드는 클라이언트가 제공한 `HeaderAuth1` 헤더, `QueryString1` 쿼리 파라미터 및 스테이지 변수 `StageVar1`이 모두 `headerValue1`, `queryValue1`, `stageValue1`의 지정된 값과 각각 일치하는 경우 요청을 허용하는 Lambda 권한 부여 함수를 생성합니다.
------
#### [ Node.js ]
```
// A simple request-based authorizer example to demonstrate how to use request
// parameters to allow or deny a request. In this example, a request is
// authorized if the client-supplied HeaderAuth1 header, QueryString1
// query parameter, and stage variable of StageVar1 all match
// specified values of 'headerValue1', 'queryValue1', and 'stageValue1',
// respectively.
export const handler = function(event, context, callback) {
console.log('Received event:', JSON.stringify(event, null, 2));
// Retrieve request parameters from the Lambda function input:
var headers = event.headers;
var queryStringParameters = event.queryStringParameters;
var pathParameters = event.pathParameters;
var stageVariables = event.stageVariables;
// Parse the input for the parameter values
var tmp = event.methodArn.split(':');
var apiGatewayArnTmp = tmp[5].split('/');
var awsAccountId = tmp[4];
var region = tmp[3];
var restApiId = apiGatewayArnTmp[0];
var stage = apiGatewayArnTmp[1];
var method = apiGatewayArnTmp[2];
var resource = '/'; // root resource
if (apiGatewayArnTmp[3]) {
resource += apiGatewayArnTmp[3];
}
// Perform authorization to return the Allow policy for correct parameters and
// the 'Unauthorized' error, otherwise.
if (headers.HeaderAuth1 === "headerValue1"
&& queryStringParameters.QueryString1 === "queryValue1"
&& stageVariables.StageVar1 === "stageValue1") {
callback(null, generateAllow('me', event.methodArn));
} else {
callback(null, generateDeny('me', event.methodArn));
}
}
// Help function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
// Required output:
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17'; // default version
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke'; // default action
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
var generateAllow = function(principalId, resource) {
return generatePolicy(principalId, 'Allow', resource);
}
var generateDeny = function(principalId, resource) {
return generatePolicy(principalId, 'Deny', resource);
}
```
------
#### [ Python ]
```
# A simple request-based authorizer example to demonstrate how to use request
# parameters to allow or deny a request. In this example, a request is
# authorized if the client-supplied headerauth1 header, QueryString1
# query parameter, and stage variable of StageVar1 all match
# specified values of 'headerValue1', 'queryValue1', and 'stageValue1',
# respectively.
def lambda_handler(event, context):
print(event)
# Retrieve request parameters from the Lambda function input:
headers = event['headers']
queryStringParameters = event['queryStringParameters']
pathParameters = event['pathParameters']
stageVariables = event['stageVariables']
# Parse the input for the parameter values
tmp = event['methodArn'].split(':')
apiGatewayArnTmp = tmp[5].split('/')
awsAccountId = tmp[4]
region = tmp[3]
restApiId = apiGatewayArnTmp[0]
stage = apiGatewayArnTmp[1]
method = apiGatewayArnTmp[2]
resource = '/'
if (apiGatewayArnTmp[3]):
resource += apiGatewayArnTmp[3]
# Perform authorization to return the Allow policy for correct parameters
# and the 'Unauthorized' error, otherwise.
if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters['QueryString1'] == "queryValue1" and stageVariables['StageVar1'] == "stageValue1"):
response = generateAllow('me', event['methodArn'])
print('authorized')
return response
else:
print('unauthorized')
response = generateDeny('me', event['methodArn'])
return response
# Help function to generate IAM policy
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17'
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
return authResponse
def generateAllow(principalId, resource):
return generatePolicy(principalId, 'Allow', resource)
def generateDeny(principalId, resource):
return generatePolicy(principalId, 'Deny', resource)
```
------
이 예제에서 Lambda 권한 부여자 함수는 입력 파라미터를 확인하고 다음과 같이 동작합니다.
+ 필요한 모든 파라미터 값이 예상 값과 일치하면 권한 부여자 함수가 `200 OK` HTTP 응답 및 다음과 같은 IAM 정책을 반환하고 메서드 요청이 성공합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
+ 일치하지 않으면 권한 부여자 함수가 `401 Unauthorized` HTTP 응답을 반환하고 메서드 요청이 실패합니다.
Lambda 권한 부여자 함수는 IAM 정책을 반환하는 것 외에 호출자의 보안 주체 ID도 반환해야 합니다. 선택적으로 통합 백엔드로 전달될 수 있는 추가 정보를 포함하는 `context` 객체를 반환할 수 있습니다. 자세한 내용은 [API Gateway Lambda 권한 부여자의 출력](api-gateway-lambda-authorizer-output.md) 섹션을 참조하세요.
프로덕션 코드에서는 권한 부여를 허용하기 전에 사용자를 인증해야 할 수 있습니다. 해당 공급자의 설명서에 나온 대로 인증 공급자를 직접적으로 호출하여 Lambda 함수에 인증 로직을 추가할 수 있습니다.
## `TOKEN` 권한 부여자 Lambda 함수 예제
다음 예제 코드는 클라이언트 제공 토큰 값이 `allow`이면 호출자가 메서드를 간접적으로 호출하도록 허용하는 `TOKEN` Lambda 권한 부여자 함수를 생성합니다. 토큰 값이 `deny`이면 호출자가 요청을 간접적으로 호출할 수 없습니다. 토큰 값이 `unauthorized` 또는 빈 문자열인 경우 권한 부여자 함수는 `401 UNAUTHORIZED` 응답을 반환합니다.
------
#### [ Node.js ]
```
// A simple token-based authorizer example to demonstrate how to use an authorization token
// to allow or deny a request. In this example, the caller named 'user' is allowed to invoke
// a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke
// the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty
// string, the authorizer function returns an HTTP 401 status code. For any other token value,
// the authorizer returns an HTTP 500 status code.
// Note that token values are case-sensitive.
export const handler = function(event, context, callback) {
var token = event.authorizationToken;
switch (token) {
case 'allow':
callback(null, generatePolicy('user', 'Allow', event.methodArn));
break;
case 'deny':
callback(null, generatePolicy('user', 'Deny', event.methodArn));
break;
case 'unauthorized':
callback("Unauthorized"); // Return a 401 Unauthorized response
break;
default:
callback("Error: Invalid token"); // Return a 500 Invalid token response
}
};
// Help function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17';
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke';
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
```
------
#### [ Python ]
```
# A simple token-based authorizer example to demonstrate how to use an authorization token
# to allow or deny a request. In this example, the caller named 'user' is allowed to invoke
# a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke
# the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty
# string, the authorizer function returns an HTTP 401 status code. For any other token value,
# the authorizer returns an HTTP 500 status code.
# Note that token values are case-sensitive.
import json
def lambda_handler(event, context):
token = event['authorizationToken']
if token == 'allow':
print('authorized')
response = generatePolicy('user', 'Allow', event['methodArn'])
elif token == 'deny':
print('unauthorized')
response = generatePolicy('user', 'Deny', event['methodArn'])
elif token == 'unauthorized':
print('unauthorized')
raise Exception('Unauthorized') # Return a 401 Unauthorized response
return 'unauthorized'
try:
return json.loads(response)
except BaseException:
print('unauthorized')
return 'unauthorized' # Return a 500 error
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17'
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
authResponse_JSON = json.dumps(authResponse)
return authResponse_JSON
```
------
이 예제에서는 API가 메서드 요청을 받을 때 API Gateway가 소스 토큰을 이 Lambda 권한 부여자 함수의 `event.authorizationToken` 속성에 전달합니다. Lambda 권한 부여자 함수는 토큰을 읽고 다음과 같이 동작합니다.
+ 토큰 값이 `allow`인 경우 권한 부여자 함수는 `200 OK` HTTP 응답 및 다음과 같은 IAM 정책을 반환하고 메서드 요청이 성공합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
+ 토큰 값이 `deny`인 경우 권한 부여자 함수는 `200 OK` HTTP 응답 및 다음과 같은 `Deny` IAM 정책을 반환하고 메서드 요청이 실패합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
**참고**
테스트 환경 밖에서는 API Gateway가 `403 Forbidden` HTTP 응답을 반환하고 메서드 요청이 실패합니다.
+ 토큰 값이 `unauthorized`이나 빈 문자열인 경우 권한 부여자 함수는 `401 Unauthorized` HTTP 응답을 반환하고 메서드 호출이 실패합니다.
+ 그 외 토큰의 경우 클라이언트는 `500 Invalid token` 응답을 수신하고, 메서드 호출은 실패합니다.
Lambda 권한 부여자 함수는 IAM 정책을 반환하는 것 외에 호출자의 보안 주체 ID도 반환해야 합니다. 선택적으로 통합 백엔드로 전달될 수 있는 추가 정보를 포함하는 `context` 객체를 반환할 수 있습니다. 자세한 내용은 [API Gateway Lambda 권한 부여자의 출력](api-gateway-lambda-authorizer-output.md) 섹션을 참조하세요.
프로덕션 코드에서는 권한 부여를 허용하기 전에 사용자를 인증해야 할 수 있습니다. 해당 공급자의 설명서에 나온 대로 인증 공급자를 직접적으로 호출하여 Lambda 함수에 인증 로직을 추가할 수 있습니다.
## Lambda 권한 부여자 함수의 추가 예제
다음 목록은 Lambda 권한 부여자 함수의 추가 예제를 보여줍니다. API를 생성한 계정과 동일한 계정이나 다른 계정에서 Lambda 함수를 생성할 수 있습니다.
이전 Lambda 함수 예제는 다른 AWS 서비스를 직접적으로 호출하지 않으므로 기본으로 제공되는 [AWSLambdaBasicExecutionRole](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)을 사용할 수 있습니다. Lambda 함수가 다른 AWS 서비스를 호출한다면 Lambda 함수에 IAM 실행 역할을 할당해야 합니다. 역할을 생성하려면 [AWS Lambda 실행 역할](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)의 지침을 따르세요.
**Lambda 권한 부여자 함수의 추가 예제**
+ 예제 애플리케이션은 GitHub의 [Open Banking Brazil - Authorization Samples](https://github.com/aws-samples/openbanking-brazilian-auth-samples)를 참조하세요.
+ 더 많은 Lambda 함수 예제는 GitHub에 있는 [ aws-apigateway-lambda-authorizer-blueprints](https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints)를 참조하세요.
+ Amazon Cognito 사용자 풀을 사용하여 사용자를 인증하고 Verified Permissions를 사용하여 정책 스토어를 기반으로 호출자에게 권한을 부여하는 Lambda 권한 부여자를 생성할 수 있습니다. 자세한 내용은 [Verified Permissions를 사용하여 자격 증명의 속성을 기반으로 액세스 제어](apigateway-lambda-authorizer-verified-permissions.md) 섹션을 참조하세요.
+ Lambda 콘솔은 Python 블루프린트를 제공합니다. **블루프린트 사용**을 선택하고 **api-gateway-authorizer-python** 블루프린트를 선택하여 이 블루프린트를 사용할 수 있습니다.
# API Gateway Lambda 권한 부여자 구성
Lambda 함수를 생성한 후 Lambda 함수를 API의 권한 부여자로 구성합니다. 그런 다음 Lambda 권한 부여자를 간접적으로 호출하도록 메서드를 구성하여 호출자가 메서드를 간접적으로 호출할 수 있는지 확인합니다. API를 생성한 계정과 동일한 계정이나 다른 계정에서 Lambda 함수를 생성할 수 있습니다.
API Gateway 콘솔에 기본으로 제공되는 도구를 사용하거나 [Postman](https://www.postman.com/)을 사용하여 Lambda 권한 부여자를 테스트할 수 있습니다. Postman을 사용하여 Lambda 권한 부여 함수를 테스트하는 방법에 대한 지침은 [API Gateway Lambda 권한 부여자를 사용한 API 직접 호출](call-api-with-api-gateway-lambda-authorization.md) 섹션을 참조하세요.
## Lambda 권한 부여자 구성(콘솔)
다음 절차는 API Gateway REST API 콘솔에서 Lambda 권한 부여자를 생성하는 방법을 보여줍니다. 다른 Lambda 권한 부여자 유형에 대해 자세히 알아보려면 [Lambda 권한 부여자 유형 선택](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-choose) 섹션을 참조하세요.
------
#### [ REQUEST authorizer ]
**`REQUEST` Lambda 권한 부여자를 구성하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API를 선택한 다음 **권한 부여자**를 선택합니다.
1. **권한 부여자 생성**을 선택합니다.
1. **권한 부여자 이름**에 권한 부여자의 이름을 입력합니다.
1. **권한 부여자 유형**으로 **Lambda**를 선택합니다.
1. **Lambda 함수** 함수에서 Lambda 권한 부여자 함수를 생성한 AWS 리전을 선택하고 함수 이름을 입력합니다.
1. API Gateway REST API 콘솔이 리소스 기반 정책을 설정하도록 **Lambda 호출 역할**을 비워 둡니다. 이 정책은 API Gateway에 Lambda 권한 부여자 함수를 간접적으로 호출할 권한을 부여합니다. API Gateway가 Lambda 권한 부여자 함수를 간접적으로 호출하도록 허용하는 IAM 역할의 이름을 입력할 수도 있습니다. 예시 역할은 [맡을 수 있는 IAM 역할 생성](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies) 섹션을 참조하세요.
1. **Lambda 이벤트 페이로드**로 **요청**을 선택합니다.
1. **자격 증명 소스 유형**에서 파리미터 유형을 선택합니다. 지원되는 파라미터 유형은 `Header`, `Query string`, `Stage variable` 및 `Context`입니다. 자격 증명 소스를 더 추가하려면 **파라미터 추가**를 선택합니다.
1. 권한 부여자에 의해 생성된 권한 부여 정책을 캐싱하려면 **권한 부여 캐싱**을 설정해 둡니다. 정책 캐싱을 활성화한 경우 **TTL** 값을 수정할 수 있습니다. **TTL**을 0으로 설정하면 정책 캐싱이 비활성화됩니다.
캐싱을 활성화하는 경우 권한 부여자가 API 전체의 모든 메서드에 적용 가능한 정책을 반환해야 합니다. 메서드별 정책을 적용하려면 컨텍스트 변수 `$context.path` 및 `$context.httpMethod`를 사용하세요.
1. **권한 부여자 생성**을 선택합니다.
------
#### [ TOKEN authorizer ]
**`TOKEN` Lambda 권한 부여자를 구성하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API를 선택한 다음 **권한 부여자**를 선택합니다.
1. **권한 부여자 생성**을 선택합니다.
1. **권한 부여자 이름**에 권한 부여자의 이름을 입력합니다.
1. **권한 부여자 유형**으로 **Lambda**를 선택합니다.
1. **Lambda 함수** 함수에서 Lambda 권한 부여자 함수를 생성한 AWS 리전을 선택하고 함수 이름을 입력합니다.
1. API Gateway REST API 콘솔이 리소스 기반 정책을 설정하도록 **Lambda 호출 역할**을 비워 둡니다. 이 정책은 API Gateway에 Lambda 권한 부여자 함수를 간접적으로 호출할 권한을 부여합니다. API Gateway가 Lambda 권한 부여자 함수를 간접적으로 호출하도록 허용하는 IAM 역할의 이름을 입력할 수도 있습니다. 예시 역할은 [맡을 수 있는 IAM 역할 생성](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies) 섹션을 참조하세요.
1. **Lambda 이벤트 페이로드**로 **토큰**을 선택합니다.
1. **토큰 소스**에 인증 토큰이 포함된 헤더 이름을 입력합니다. 호출자는 권한 부여 토큰을 Lambda 권한 부여자에게 전송하기 위해 이 이름의 헤더를 포함해야 합니다.
1. (선택 사항) **토큰 검증**에 정규 표현식 문을 입력합니다. API Gateway는 이 표현식에 대해 입력 토큰의 초기 확인을 수행하고 확인이 성공할 경우 권한 부여자를 호출합니다.
1. 권한 부여자에 의해 생성된 권한 부여 정책을 캐싱하려면 **권한 부여 캐싱**을 설정해 둡니다. 정책 캐싱을 비활성화한 경우 **토큰 소스**에 지정된 헤더 이름이 캐시 키가 됩니다. 정책 캐싱을 활성화한 경우 **TTL** 값을 수정할 수 있습니다. **TTL**을 0으로 설정하면 정책 캐싱이 비활성화됩니다.
캐싱을 활성화하는 경우 권한 부여자가 API 전체의 모든 메서드에 적용 가능한 정책을 반환해야 합니다. 메서드별 정책을 적용하려는 경우 **권한 부여자 캐싱**을 끌 수 있습니다.
1. **권한 부여자 생성**을 선택합니다.
------
Lambda 권한 부여자를 생성한 후 테스트할 수 있습니다. 다음 절차는 Lambda 권한 부여자를 테스트하는 방법을 보여줍니다.
------
#### [ REQUEST authorizer ]
**`REQUEST` Lambda 권한 부여자를 테스트하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 권한 부여자의 이름을 선택합니다.
1. **테스트 권한 부여자**에 자격 증명 소스의 값을 입력합니다.
[`REQUEST` 권한 부여자 Lambda 함수 예제](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-request-lambda-function-create)를 사용하는 경우 다음과 같이 합니다.
1. **헤더**를 선택하고 **headerValue1**을 입력한 다음 **파라미터 추가**를 선택합니다.
1. **자격 증명 소스 유형**에서 **쿼리 문자열**을 선택한 다음 **queryValue1**을 입력하고 **파라미터 추가**를 선택합니다.
1. **자격 증명 소스 유형**에서 **스테이지 변수**를 선택하고 **stageValue1**을 입력합니다.
테스트 간접 호출을 위한 컨텍스트 변수는 수정할 수 없지만 Lambda 함수의 **API Gateway 권한 부여자** 테스트 이벤트 템플릿은 수정할 수 있습니다. 그런 다음 수정된 컨텍스트 변수를 사용하여 Lambda 권한 부여자 함수를 테스트할 수 있습니다. 자세한 내용은 AWS Lambda 개발자 안내서의 [콘솔에서 Lambda 함수 테스팅](https://docs.aws.amazon.com/lambda/latest/dg/testing-functions.html)을 참조하세요.**
1. **테스트 권한 부여자**를 선택합니다.
------
#### [ TOKEN authorizer ]
**`TOKEN` Lambda 권한 부여자를 테스트하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 권한 부여자의 이름을 선택합니다.
1. **테스트 권한 부여자**에 토큰 값을 입력합니다.
[`TOKEN` 권한 부여자 Lambda 함수 예제](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create)를 사용하는 경우 다음과 같이 합니다.
1. **authorizationToken**에 **allow**를 입력합니다.
1. **테스트 권한 부여자**를 선택합니다.
Lambda 권한 부여자가 테스트 환경에서 요청을 성공적으로 거부하면 테스트는 `200 OK` HTTP 응답으로 응답합니다. 그러나 테스트 환경 밖에서는 API Gateway가 `403 Forbidden` HTTP 응답을 반환하고 메서드 요청이 실패합니다.
------
## Lambda 권한 부여자 구성(AWS CLI)
다음 [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) 명령은 AWS CLI를 사용하여 Lambda 권한 부여자를 생성하는 방법을 보여줍니다.
------
#### [ REQUEST authorizer ]
다음 [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) 명령은 `REQUEST` 권한 부여자를 생성하고 `Authorizer` 헤더와 `accountId` 컨텍스트 변수를 자격 증명 소스로 사용합니다.
```
aws apigateway create-authorizer \
--rest-api-id 1234123412 \
--name 'First_Request_Custom_Authorizer' \
--type REQUEST \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \
--identity-source 'method.request.header.Authorization,context.accountId' \
--authorizer-result-ttl-in-seconds 300
```
------
#### [ TOKEN authorizer ]
다음 [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) 명령은 `TOKEN` 권한 부여자를 생성하고 `Authorization` 헤더를 자격 증명 소스로 사용합니다.
```
aws apigateway create-authorizer \
--rest-api-id 1234123412 \
--name 'First_Token_Custom_Authorizer' \
--type TOKEN \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \
--identity-source 'method.request.header.Authorization' \
--authorizer-result-ttl-in-seconds 300
```
------
Lambda 권한 부여자를 생성한 후 테스트할 수 있습니다. 다음 [test-invoke-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-authorizer.html) 명령은 Lambda 권한 부여자를 테스트합니다.
```
aws apigateway test-invoke-authorizer --rest-api-id 1234123412 \
--authorizer-id efg1234 \
--headers Authorization='Value'
```
## Lambda 권한 부여자를 사용하도록 메서드 구성(콘솔)
Lambda 권한 부여자를 구성한 후 API에 대한 메서드에 연결해야 합니다. 권한 부여자가 권한 부여 캐싱을 사용하는 경우 정책을 업데이트하여 추가 메서드에 대한 액세스를 제어해야 합니다.
**Lambda 권한 부여자를 사용하도록 API 메서드를 구성하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API를 선택합니다.
1. **리소스**를 선택한 다음 새 메서드를 선택하거나 기존 메서드를 선택합니다.
1. **메서드 요청** 탭의 **메서드 요청 설정**에서 **편집**을 선택합니다.
1. **권한 부여자**의 경우 드롭다운 메뉴에서 방금 생성한 Lambda 권한 부여자를 선택합니다.
1. (선택 사항) 권한 부여 토큰을 백엔드로 전달하려면 **HTTP 요청 헤더**를 선택합니다. **헤더 추가**를 선택한 다음 인증 헤더의 이름을 추가합니다. **이름**에서, API에 대한 Lambda 권한 부여자를 생성할 때 지정한 **토큰 소스** 이름과 일치하는 헤더 이름을 입력합니다. `REQUEST` 권한 부여자에는 이 단계가 적용되지 않습니다.
1. **저장**을 선택합니다.
1. **Deploy API(API 배포)**를 선택하여 단계에 API를 배포합니다. 스테이지 변수를 사용하는 `REQUEST` 권한 부여자의 경우 **스테이지** 페이지가 열려 있는 동안 필요한 스테이지 변수를 지정하고 값을 지정해야 합니다.
## Lambda 권한 부여자를 사용하도록 메서드 구성(AWS CLI)
Lambda 권한 부여자를 구성한 후 API에 대한 메서드에 연결해야 합니다. 새 메서드를 생성하거나 패치 작업을 사용하여 권한 부여자를 기존 메서드에 연결할 수 있습니다. 권한 부여자가 권한 부여 캐싱을 사용하는 경우 정책을 업데이트하여 추가 메서드에 대한 액세스를 제어해야 합니다.
다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령은 Lambda 권한 부여자를 사용하는 새 메서드를 생성합니다.
```
aws apigateway put-method --rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--authorization-type CUSTOM \
--authorizer-id efg1234
```
다음 [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) 명령은 Lambda 권한 부여자를 사용하도록 기존 메서드를 업데이트합니다.
```
aws apigateway update-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--patch-operations op="replace",path="/authorizationType",value="CUSTOM" op="replace",path="/authorizerId",value="efg1234"
```
# API Gateway Lambda 권한 부여자에 대한 입력
다음 섹션에서는 API Gateway에서 Lambda 권한 부여자로 보내는 입력 형식을 설명합니다.
## `TOKEN` 입력 형식
`TOKEN` 유형 Lambda 권한 부여자(이전에는 사용자 지정 권한 부여자라고 함)의 경우 API에 대해 권한 부여자를 구성할 때 사용자 지정 헤더를 **토큰 원본**으로 지정해야 합니다. API 클라이언트는 수신되는 요청에 있는 해당 헤더의 권한 부여 토큰을 전달해야 합니다. 메서드 요청을 수신하면 API Gateway는 사용자 지정 헤더로부터 토큰을 추출합니다. 그런 다음 토큰을 Lambda 함수 내 `authorizationToken` 객체의 `event` 속성으로 전달하고 메서드 ARN을 `methodArn` 속성으로 전달합니다.
```
{
"type":"TOKEN",
"authorizationToken":"{caller-supplied-token}",
"methodArn":"arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
```
이 예제에서 `type` 속성은 권한 부여자 유형(`TOKEN` 권한 부여자)을 지정합니다. `{caller-supplied-token}`의 출처는 클라이언트 요청의 권한 부여 헤더이며 모든 문자열 값이 될 수 있습니다. `methodArn`은 수신 메서드 요청의 ARN이며 API Gateway에서 Lambda 권한 부여자 구성에 따라 채워집니다.
## `REQUEST` 입력 형식
`REQUEST` 유형의 Lambda 권한 부여자의 경우, API Gateway가 요청 파라미터를 `event` 객체의 일부로 Lambda 함수에 전달합니다. 이러한 요청 파라미터에는 헤더, 경로 파라미터, 쿼리 문자열 파라미터, 단계 변수 및 일부 요청 컨텍스트 변수가 포함됩니다. API 호출자는 경로 파라미터, 헤더 및 쿼리 문자열 파라미터를 설정할 수 있습니다. API 개발자는 API를 배포할 때 단계 변수를 설정해야 하며, API Gateway는 런타임 시 요청 컨텍스트를 제공합니다.
**참고**
경로 파라미터는 Lambda 권한 부여자 함수에 요청 파라미터로 전달될 수 있지만, 자격 증명 원본으로 사용될 수는 없습니다.
다음 예제는 프록시 통합을 포함하는 API 메서드(`REQUEST`)에 대한 `GET /request` 권한 부여자에 대한 입력입니다.
```
{
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"HeaderAuth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "..."
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "...",
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "abcdef123"
}
}
```
`requestContext`는 키-값 페어의 맵이며 [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference) 변수에 해당합니다. 결과는 API 종속적입니다.
API Gateway는 새 키를 맵에 추가할 수 있습니다. Lambda 프록시 통합에서의 Lambda 함수에 대한 자세한 내용은 [프록시 통합에 대한 Lambda 함수의 입력 형식](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) 단원을 참조하세요.
# API Gateway Lambda 권한 부여자의 출력
Lambda 권한 부여자 함수의 출력은 사전과 같은 객체이며, 이 객체에는 보안 주체 ID(`principalId`)와 정책 설명 목록이 들어 있는 정책 문서(`policyDocument`)가 포함되어 있어야 합니다. 또한 키-값 페어를 포함하는 `context` 맵을 포함할 수 있습니다. API가 사용량 계획을 사용하는 경우([https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource)가 `AUTHORIZER`로 설정됨), Lambda 권한 부여자 함수는 `usageIdentifierKey` 속성 값으로 사용량 계획의 API 키 중 하나를 반환해야 합니다.
다음은 이 출력의 예입니다.
------
#### [ JSON ]
****
```
{
"principalId": "yyyyyyyy",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"stringKey": "value",
"numberKey": "1",
"booleanKey": "true"
},
"usageIdentifierKey": "{api-key}"
}
```
------
여기서 정책 설명은 API Gateway 실행 서비스에서 지정된 API 메서드(`Effect`)를 호출(`Action`)하도록 허용할지 거부할지(`Resource`) 여부를 지정합니다. 권한 부여자에 따라 여러 리소스에 대한 액세스를 제어해야 할 수 있습니다. 와일드카드(`*`)를 사용하여 리소스 유형(메서드)를 지정할 수 있습니다. API 호출에 대한 유효한 정책을 설정하는 방법은 [API Gateway에서 API 실행을 위한 IAM 정책의 설명 참조](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-calling-api-permissions) 단원을 참조하세요.
권한 부여가 활성화된 메서드 ARN의 경우(예: `arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]`) 최대 길이는 1,600바이트입니다. 경로 파라미터 값은 실행 시간에 값 크기가 결정되기 때문에 ARN 길이가 한도를 초과하게 될 가능성이 있습니다. 이런 일이 발생하면 API 클라이언트는 `414 Request URI too long` 응답을 받습니다.
뿐만 아니라 권한 부여자의 정책 설명 출력 내용과 마찬가지로 리소스 ARN은 현재 512자로 제한되어 있습니다. 이런 이유 때문에 요청 URI에서는 길이가 상당히 긴 JWT 토큰이 있는 URI를 사용해서는 안 됩니다. 그 대신에 요청 헤더에서 JWT 토큰을 안전하게 전달할 수도 있습니다.
`principalId` 변수를 사용하여 매핑 템플릿에서 `$context.authorizer.principalId` 값에 액세스할 수 있습니다. 이 기능은 값을 백엔드에 전달하려는 경우에 유용합니다. 자세한 내용은 [데이터 변환용 컨텍스트 변수](api-gateway-mapping-template-reference.md#context-variable-reference) 단원을 참조하세요.
각각 `stringKey`, `numberKey` 또는 `booleanKey`를 호출하여 매핑 템플릿에서 `"value"` 맵의 `"1"`, `"true"` 또는 `context` 값(예: `$context.authorizer.stringKey`, `$context.authorizer.numberKey` 또는 `$context.authorizer.booleanKey`)에 액세스할 수 있습니다. 반환되는 값은 모두 문자열화됩니다. JSON 객체 또는 어레이를 `context` 맵의 유효한 키 값으로 설정할 수 없습니다.
`context` 맵을 사용하면 통합 요청 매핑 템플릿을 사용해 캐시된 자격 증명을 권한 부여자에서 백엔드로 반환할 수 있습니다. 그러면 캐시된 자격 증명을 사용해 모든 요청에 대해 보안 키에 액세스하고 권한 부여 토큰을 열 필요를 줄일 수 있으므로 백엔드가 개선된 사용자 경험을 제공할 수 있습니다.
Lambda 프록시 통합의 경우 API Gateway가 `context` 객체를 입력 `event`의 일부로 Lambda 권한 부여자에서 백엔드 Lambda 함수로 직접 전달합니다. `context`를 호출하여 Lambda 함수에서 `$event.requestContext.authorizer.key` 키-값 페어를 검색할 수 있습니다.
`{api-key}`는 API 단계의 사용량 계획에서 API 키를 뜻합니다. 자세한 내용은 [API Gateway의 REST API 사용량 계획 및 API 키](api-gateway-api-usage-plans.md) 단원을 참조하세요.
다음 예제는 Lambda 권한 부여자의 출력을 보여줍니다. 예제 출력에는 AWS 계정(`123456789012`)의 API(`ymy8tbxw7b`) `dev` 스테이지에 대해 `GET` 메서드에 대한 호출을 차단(`Deny`)하는 정책 설명이 포함되어 있습니다.
------
#### [ JSON ]
****
```
{
"principalId": "user",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
}
]
}
}
```
------
# API Gateway Lambda 권한 부여자를 사용한 API 직접 호출
Lambda 권한 부여자(이전에는 사용자 지정 권한 부여자라고 함)를 구성하고 API를 배포했으면 Lambda 권한 부여자가 활성화된 상태에서 API를 테스트해야 합니다. 이를 위해서는 REST 클라이언트(예: cURL 또는 [Postman](https://www.postman.com/))가 필요합니다. 다음 예제에서는 Postman을 사용합니다.
**참고**
권한 부여자 사용 메서드를 호출할 때 지정된 **토큰 확인 표현식**에 필요한 `TOKEN` 권한 부여자가 설정되어 있지 않거나 null이거나 무효화된 경우 API Gateway에서는 CloudWatch에 대한 호출을 기록하지 않습니다. 마찬가지로 API Gateway는 `REQUEST` 권한 부여자에 필요한 자격 증명 원본이 하나라도 설정되지 않았거나, null이거나, 비어 있을 경우 CloudWatch에 대한 호출을 기록하지 않습니다.
다음에서는 Postman을 사용하여 Lambda `TOKEN` 권한 부여자로 API를 호출하거나 테스트하는 방법을 보여줍니다. 이 방법은 필요한 경로, 헤더 또는 쿼리 문자열 파라미터를 명시적으로 지정할 경우 Lambda `REQUEST` 권한 부여자를 사용해 API를 호출하는 데 적용할 수 있습니다.
**사용자 지정 `TOKEN` 권한 부여자를 사용해 API를 호출하려면**
1. **Postman**을 열고 **GET** 메서드를 선택한 후 API의 **Invoke URL(URL 호출)**을 인접한 URL 필드에 붙여 넣습니다.
Lambda 권한 부여 토큰 헤더를 추가하고 값을 `allow`로 설정합니다. **Send(전송)**를 선택합니다.
![\[Lambda 권한 부여 허용 토큰을 사용하여 API 호출\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/custom-auth-call-api-with-allow-token.png)
응답을 보면, API Gateway Lambda 권한 부여자가 **200 OK** 응답을 반환하고, 메서드와 통합된 HTTP 엔드포인트(http://httpbin.org/get)에 액세스할 수 있는 호출 권한을 부여함을 알 수 있습니다.
1. Postman에 머물면서 Lambda 권한 부여 토큰 헤더 값을 `deny`로 변경합니다. **Send(전송)**를 선택합니다.
![\[Lambda 권한 부여 거부 토큰을 사용하여 API 호출\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/custom-auth-call-api-with-deny-token.png)
응답을 보면, API Gateway Lambda 권한 부여자가 **403 Forbidden** 응답을 반환하고, HTTP 엔드포인트에 액세스할 수 있는 호출 권한을 부여하지 않음을 알 수 있습니다.
1. Postman에서 Lambda 권한 부여 토큰 헤더 값을 `unauthorized`로 변경하고 **전송**을 선택합니다.
![\[Lambda 권한 부여 권한 없음 토큰을 사용하여 API 호출\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/custom-auth-call-api-with-unauthorized-token.png)
응답을 보면, API Gateway가 **401 Unauthorized** 응답을 반환하고, HTTP 엔드포인트에 액세스할 수 있는 호출 권한을 부여하지 않음을 알 수 있습니다.
1. 이제 Lambda 권한 부여 토큰 헤더 값을 `fail`로 변경합니다. **Send(전송)**를 선택합니다.
![\[Lambda 권한 부여 실패 토큰을 사용하여 API 호출\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/custom-auth-call-api-with-fail-token.png)
응답을 보면, API Gateway가 **500 Internal Server Error** 응답을 반환하고, HTTP 엔드포인트에 액세스할 수 있는 호출 권한을 부여하지 않음을 알 수 있습니다.
# 교차 계정 API Gateway Lambda 권한 부여자 구성
이제는 다른 AWS Lambda 계정의 AWS 함수도 API 권한 부여자 함수로 사용할 수 있습니다. 각 계정은 Amazon API Gateway를 사용할 수 있는 모든 리전에 존재할 수 있습니다. Lambda 권한 부여자 함수는 OAuth 또는 SAML 같은 보유자 토큰 인증 전략을 사용할 수 있습니다. 따라서 여러 API Gateway API에 대해 Lambda 권한 부여자 함수를 중앙에서 손쉽게 관리 및 공유할 수 있습니다.
이 단원에서는 Amazon API Gateway 콘솔을 사용하여 교차 계정 Lambda 권한 부여자 함수를 구성하는 방법을 보여줍니다.
이 지침에서는 한 AWS 계정에서 API Gateway API를, 다른 계정에서는 Lambda 권한 부여자 함수를 이미 생성했다고 가정합니다.
## API Gateway 콘솔을 사용하여 교차 계정 Lambda 권한 부여자 구성
API를 포함하고 있는 계정에서 Amazon API Gateway 콘솔에 로그인하고 다음을 수행합니다.
1. API를 선택하고 기본 탐색 창에서 **권한 부여자**를 선택합니다.
1. **권한 부여자 생성**을 선택합니다.
1. **권한 부여자 이름**에 권한 부여자의 이름을 입력합니다.
1. **권한 부여자 유형**으로 **Lambda**를 선택합니다.
1. **Lambda 함수**에서 두 번째 계정에서 생성한 Lambda 권한 부여자 함수의 정식 ARN을 입력합니다.
**참고**
Lambda 콘솔 창의 오른쪽 위 모서리에서 함수의 ARN을 찾을 수 있습니다.
1. `aws lambda add-permission` 명령 문자열과 함께 경고가 표시됩니다. 이 정책은 권한 부여자 Lambda 함수를 호출할 API Gateway 권한을 부여합니다. 나중에 사용하기 위해 명령을 복사하여 저장합니다. 권한 부여자를 생성한 후 명령을 실행합니다.
1. **Lambda 이벤트 페이로드**에서 `TOKEN` 권한 부여자는 **토큰**을, `REQUEST` 권한 부여자는 **요청**을 선택합니다.
1. 이전 단계에서의 선택에 따라 다음 중 하나를 수행합니다.
1. **토큰** 옵션의 경우 다음을 수행합니다.
+ **토큰 소스**에 인증 토큰이 포함된 헤더 이름을 입력합니다. API 클라이언트는 권한 부여 토큰을 Lambda 권한 부여자에게 전송하려면 이 이름의 헤더를 포함해야 합니다.
+ 선택적으로 **토큰 검증**에 정규 표현식 문을 입력합니다. API Gateway는 이 표현식에 대해 입력 토큰의 초기 확인을 수행하고 확인이 성공할 경우 권한 부여자를 호출합니다. 이렇게 하면 API 호출을 줄일 수 있습니다.
+ 권한 부여자에 의해 생성된 권한 부여 정책을 캐싱하려면 **권한 부여 캐싱**을 설정해 둡니다. 정책 캐싱을 활성화한 경우 **TTL** 값을 수정할 수 있습니다. **TTL**을 0으로 설정하면 정책 캐싱이 비활성화됩니다. 정책 캐싱을 비활성화한 경우 **토큰 소스**에 지정된 헤더 이름이 캐시 키가 됩니다. 요청에서 이 헤더에 여러 값이 전달되면 모든 값이 순서가 유지된 상태로 캐시 키가 됩니다.
**참고**
기본 **TTL** 값은 300초입니다. 최대 TTL 값은 3600초이며, 이 제한은 늘릴 수 없습니다.
1. **요청** 옵션의 경우 다음을 수행합니다.
+ **자격 증명 소스 유형**에서 파리미터 유형을 선택합니다. 지원되는 파라미터 유형은 `Header`, `Query string`, `Stage variable` 및 `Context`입니다. 자격 증명 소스를 더 추가하려면 **파라미터 추가**를 선택합니다.
+ 권한 부여자에 의해 생성된 권한 부여 정책을 캐싱하려면 **권한 부여 캐싱**을 설정해 둡니다. 정책 캐싱을 활성화한 경우 **TTL** 값을 수정할 수 있습니다. **TTL**을 0으로 설정하면 정책 캐싱이 비활성화됩니다.
API Gateway는 지정된 자격 증명 원본을 요청 권한 부여자 캐싱 키로 사용합니다. 캐싱을 활성화한 경우 API Gateway가 런타임 시 모든 지정된 자격 증명 원본이 존재하는 것을 성공적으로 확인한 경우에만 권한 부여자의 Lambda 함수를 호출합니다. 지정된 자격 증명 원본이 없거나, Null이거나, 비어 있을 경우 API Gateway가 권한 부여자 Lambda 함수를 직접적으로 호출하지 않고 `401 Unauthorized` 응답을 반환합니다.
여러 개의 자격 증명 소스가 정의된 경우, 이들은 모두 권한 부여자의 캐시 키를 도출하는 데 사용됩니다. 캐시 키 부분을 변경하면 권한 부여자가 캐시된 정책 문서를 폐기하고 새로 생성합니다. 요청에서 여러 값이 있는 헤더가 전달되면 모든 값이 순서가 유지된 상태로 캐시 키의 일부가 됩니다.
+ 캐싱을 비활성화한 경우 자격 증명 소스를 지정할 필요가 없습니다.
**참고**
캐싱을 활성화하려면 권한 부여자가 API 전체의 모든 메서드에 적용 가능한 정책을 반환해야 합니다. 메서드별 정책을 적용하려는 경우 **권한 부여자 캐싱**을 해제할 수 있습니다.
1. **권한 부여자 생성**을 선택합니다.
1. 이전 단계에서 복사한 `aws lambda add-permission` 명령 문자열을 두 번째 계정에 대해 구성된 AWS CLI 창에 붙여 넣습니다. `AUTHORIZER_ID`를 권한 부여자의 ID로 바꿉니다. 이렇게 하면 첫 번째 계정이 두 번째 계정의 Lambda 권한 부여자 함수에 액세스할 수 있는 권한이 부여됩니다.
# Verified Permissions를 사용하여 자격 증명의 속성을 기반으로 액세스 제어
Amazon Verified Permissions를 사용하여 API Gateway API에 대한 액세스를 제어합니다. Verified Permissions와 함께 API Gateway를 사용하는 경우 Verified Permissions가 세분화된 권한 부여 결정을 사용하여 API에 대한 액세스를 제어하는 Lambda 권한 부여자를 생성합니다. Verified Permissions는 Cedar 정책 언어를 사용해 애플리케이션 사용자에 대한 세분화된 권한을 정의하여 정책 스토어 스키마 및 정책을 기반으로 호출자에게 권한을 부여합니다. 자세한 내용은 *Amazon Verified Permissions 사용 설명서*의 [연결된 API 및 ID 공급자를 사용하여 정책 저장소 생성](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/getting-started-api-policy-store.html)을 참조합니다.
Verified Permissions는 자격 증명 소스로서 Amazon Cognto 사용자 풀 또는 OpenID Connect(OIDC) ID 제공업체를 지원합니다. Verified Permissions는 보안 주체가 이전에 식별되고 인증된 것으로 가정합니다. Verified Permissions는 리전 및 엣지 최적화 REST API에만 지원됩니다.
## Verified Permissions를 사용하여 Lambda 권한 부여자 생성
Verified Permissions는 Lambda 권한 부여자를 생성하여 보안 주체가 API에서 작업을 수행할 수 있는지 여부를 결정합니다. Verified Permissions가 권한 부여 작업을 수행하는 데 사용할 Cedar 정책을 생성합니다.
다음은 API의 `GET /users` 리소스에 있는 `developer` 그룹에 대해 Amazon Cognito 사용자 풀 `us-east-1_ABC1234`를 기반으로 API를 간접적으로 호출할 수 있도록 액세스를 허용하는 Cedar 정책의 예시입니다. Verified Permissions는 발신자 ID에 대한 보유자 토큰을 구문 분석하여 그룹 멤버십을 결정합니다.
```
permit(
principal in MyAPI::UserGroup::"us-east-1_ABC1234|developer",
action in [ MyAPI::Action::"get /users" ],
resource
);
```
선택적으로 Verified Permissions에서 API의 메서드에 권한 부여자를 연결할 수 있습니다. API의 프로덕션 스테이지에서는 Verified Permissions의 권한 부여자 연결을 허용하지 않는 것이 좋습니다.
다음 목록은 Lambda 권한 부여자를 API 메서드의 메서드 요청에 연결하거나 연결하지 않도록 Verified Permissions를 구성하는 방법을 보여줍니다.
**권한 부여자 연결(AWS Management Console)**
Verified Permissions 콘솔에서 **정책 스토어 생성**을 선택할 때 **앱 통합 배포** 페이지에서 **지금**을 선택합니다.
**권한 부여자 연결 안 함(AWS Management Console)**
Verified Permissions 콘솔에서 **정책 스토어 생성**을 선택할 때 **앱 통합 배포** 페이지에서 **나중에**를 선택합니다.
Verified Permissions는 여전히 Lambda 권한 부여자를 생성합니다. Lambda 권한 부여자는 `AVPAuthorizerLambda-`로 시작합니다. 메서드에 권한 부여자를 연결하는 방법에 대한 자세한 지침은 [Lambda 권한 부여자를 사용하도록 메서드 구성(콘솔)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-console) 섹션을 참조하세요.
**권한 부여자 연결(CloudFormation)**
Verified Permissions에서 생성된 CloudFormation 템플릿의 `Conditions` 섹션에서 `"Ref": "shouldAttachAuthorizer"`를 `true`로 설정합니다.
**권한 부여자 연결 안 함(CloudFormation)**
Verified Permissions에서 생성된 CloudFormation 템플릿의 `Conditions` 섹션에서 `"Ref": "shouldAttachAuthorizer"`를 `false`로 설정합니다.
Verified Permissions는 여전히 Lambda 권한 부여자를 생성합니다. Lambda 권한 부여자는 `AVPAuthorizerLambda-`로 시작합니다. 메서드에 권한 부여자를 연결하는 방법에 대한 자세한 지침은 [Lambda 권한 부여자를 사용하도록 메서드 구성(AWS CLI)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-cli) 섹션을 참조하세요.
## Verified Permissions를 사용하여 Lambda 권한 부여자 직접 호출
`Authorization` 헤더에 자격 증명 또는 액세스 토큰을 제공하여 Lambda 권한 부여자를 직접적으로 호출할 수 있습니다. 자세한 내용은 [API Gateway Lambda 권한 부여자를 사용한 API 직접 호출](call-api-with-api-gateway-lambda-authorization.md) 섹션을 참조하세요.
API Gateway는 Lambda 권한 부여자가 반환하는 정책을 120초 동안 캐싱합니다. API Gateway 콘솔에서 또는 AWS CLI를 사용하여 TTL을 수정할 수 있습니다.
# Amazon Cognito 사용자 풀을 권한 부여자로 사용하여 REST API에 대한 액세스 제어
[IAM 역할 및 정책](permissions.md) 또는 [Lambda 권한 부여자](apigateway-use-lambda-authorizer.md)(이전에는 사용자 지정 권한 부여자라고 함)를 사용하는 것 말고도 [Amazon Cognito 사용자 풀](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)을 사용하여 Amazon API Gateway에서 API에 액세스할 수 있는 사람을 제어할 수도 있습니다.
API에 Amazon Cognito 사용자 풀을 사용하려면 먼저 `COGNITO_USER_POOLS` 유형의 권한 부여자를 생성한 다음 해당 권한 부여자를 사용하도록 API 메서드를 구성해야 합니다. API가 배포된 후 클라이언트는 먼저 사용자 풀에 사용자를 로그인하고, 해당 사용자의 [자격 증명 또는 액세스 토큰](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)을 획득한 다음 일반적으로 요청의 `Authorization` 헤더로 설정되는 토큰 1개를 사용하여 API 메서드를 호출해야 합니다. API 호출은 필요한 토큰이 제공되고 제공된 토큰이 유효한 경우에만 성공하며, 그렇지 않으면 권한이 부여될 수 있는 자격 증명이 클라이언트에게 없기 때문에 호출할 권한이 클라이언트에게 부여되지 않습니다.
자격 증명 토큰은 로그인한 사용자의 자격 증명 클레임을 기반으로 API 호출 권한을 부여하는 데 사용됩니다. 액세스 토큰은 지정된 액세스 보호 리소스의 사용자 지정 범위를 기반으로 API 호출 권한을 부여하는 데 사용됩니다. 자세한 내용은 [사용자 풀에 토큰 사용](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)과 [리소스 서버 및 사용자 지정 범위](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html)를 참조하세요.
API를 위한 Amazon Cognito 사용자 풀을 생성하고 구성하려면 다음 작업을 수행하세요.
+ Amazon Cognito 콘솔, CLI/SDK 또는 API를 사용하여 사용자 풀을 생성하거나 다른 AWS 계정이 소유한 사용자 풀을 사용합니다.
+ API Gateway 콘솔, CLI/SDK 또는 API를 사용하여 선택한 사용자 풀이 포함된 API Gateway 권한 부여자를 생성합니다.
+ 선택한 API 메서드에서 API Gateway 콘솔, CLI/SDK 또는 API를 사용하여 권한 부여자를 활성화합니다.
사용자 풀이 활성화된 상태에서 API 메서드를 호출하기 위해 API 클라이언트는 다음 작업을 수행합니다.
+ Amazon Cognito CLI/SDK 또는 API를 사용하여 선택한 사용자 풀에 사용자를 로그인하고 자격 증명 토큰 또는 액세스 토큰을 획득합니다. SDK 사용에 대한 자세히 내용은 [AWS SDK를 사용한 Amazon Cognito 코드 예시](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html)를 참조하세요.
+ 클라이언트별 프레임워크를 사용하여 배포된 API Gateway API를 호출하고 `Authorization` 헤더에서 적절한 토큰을 제공합니다.
API 개발자는 클라이언트 개발자에게 사용자 풀 ID와 클라이언트 ID 및 가능한 경우, 사용자 풀의 일부로 정의되는 연결된 클라이언트 비밀번호를 제공해야 합니다.
**참고**
사용자가 Amazon Cognito 자격 증명을 사용하여 로그인하고 IAM 역할 권한과 함께 사용할 임시 자격 증명도 획득하게 하려면 [Amazon Cognito 연동 ID](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)를 사용합니다. 각 API 리소스 엔드포인트 HTTP 메서드에 대해 권한 부여 유형을 설정하고 `Method Execution` 범주를 `AWS_IAM`으로 설정합니다.
이 단원에서는 사용자 풀을 생성하고, API Gateway API를 사용자 풀과 통합하고, 사용자 풀에 통합된 API를 호출하는 방법을 설명합니다.
**Topics**
+ [REST API에 대한 Amazon Cognito 사용자 풀 생성](apigateway-create-cognito-user-pool.md)
+ [REST API와 Amazon Cognito 사용자 풀 통합](apigateway-enable-cognito-user-pool.md)
+ [Amazon Cognito 사용자 풀과 통합된 REST API 호출](apigateway-invoke-api-integrated-with-cognito-user-pool.md)
+ [API Gateway 콘솔을 사용하여 REST API를 위한 교차 계정 Amazon Cognito 권한 부여자 구성](apigateway-cross-account-cognito-authorizer.md)
+ [CloudFormation을 사용하여 REST API를 위한 Amazon Cognito 권한 부여자 생성](apigateway-cognito-authorizer-cfn.md)
# REST API에 대한 Amazon Cognito 사용자 풀 생성
API를 사용자 풀과 통합하기 전에 Amazon Cognito에서 사용자 풀을 생성해야 합니다. 사용자 풀 구성은 [Amazon Cognito의 모든 리소스 할당량](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html)을 준수해야 합니다. 그룹, 사용자 및 역할과 같은 모든 사용자 정의 Amazon Cognito 변수가 영숫자 문자만 사용해야 합니다. 사용자 풀을 생성하는 방법에 대한 지침은 *Amazon Cognito 개발자 가이드*에서 [자습서: 사용자 풀 생성](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html)을 참조하세요.
사용자 풀 ID, 클라이언트 ID 및 모든 클라이언트 비밀번호를 적어 둡니다. 사용자가 사용자 풀에 등록하고, 사용자 풀에 로그인하고, 사용자 풀에 구성된 API 메서드를 호출하기 위해 요청에 포함할 자격 증명 또는 액세스 토큰을 획득하려면 클라이언트가 Amazon Cognito에 이러한 ID 및 클라이언트 비밀번호를 제공해야 합니다. 또한 다음에 설명한 대로 사용자 풀을 API Gateway에서 권한 부여자로 구성할 경우 사용자 풀 이름을 지정해야 합니다.
액세스 토큰을 사용하여 API 메서드 호출 권한을 부여하는 경우, 사용자 풀과의 앱 통합을 구성하여 지정된 리소스 서버에서 원하는 사용자 지정 범위를 설정해야 합니다. Amazon Cognito 사용자 풀을 통해 토큰 사용에 대한 자세한 내용은 [사용자 풀을 통해 토큰 사용](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)을 참조하세요. 리소스 서버에 대한 자세한 내용은 [사용자 풀의 리소스 서버 정의](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html)를 참조하세요.
구성된 리소스 서버 식별자와 사용자 지정 범위 이름을 적어 둡니다. 이 정보는 `COGNITO_USER_POOLS` 권한 부여자가 사용하는 **OAuth Scopes(OAuth 범위)**의 액세스 범위 전체 이름을 생성하는 데 필요합니다.
![\[Amazon Cognito 사용자 풀 리소스 서버 및 범위\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png)
# REST API와 Amazon Cognito 사용자 풀 통합
API Gateway에서 Amazon Cognito 사용자 풀을 생성한 다음 이 사용자 풀을 사용하는 `COGNITO_USER_POOLS` 권한 부여자를 생성해야 합니다. 다음 절차에서는 API Gateway 콘솔에서 이 작업을 수행하는 방법을 보여줍니다.
**참고**
[https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) 작업을 통해 여러 사용자 풀을 사용하는 `COGNITO_USER_POOLS` 권한 부여자를 생성할 수 있습니다. `COGNITO_USER_POOLS` 권한 부여자 한 명에 최대 1,000개의 사용자 풀을 사용할 수 있습니다. 이 한도는 늘릴 수 없습니다.
**중요**
아래 절차를 수행한 후 변경 사항을 전파하기 위해 API를 배포 또는 재배포할 필요가 있습니다. API 배포에 대한 자세한 내용은 [API Gateway에서 REST API 배포](how-to-deploy-api.md) 단원을 참조하세요.
**API Gateway 콘솔을 사용하여 `COGNITO_USER_POOLS` 권한 부여자를 생성하려면**
1. API Gateway에서 새 API를 생성하거나 기존 API를 선택합니다.
1. 기본 탐색 창에서 **권한 부여자**를 선택합니다.
1. **권한 부여자 생성**을 선택합니다.
1. 사용자 풀을 사용하도록 새 권한 부여자를 구성하려면 다음을 수행합니다.
1. **권한 부여자 이름**에 이름을 입력합니다.
1. **권한 부여자 유형**으로 **Cognito**를 선택합니다.
1. **Cognito 사용자 풀**의 경우 Amazon Cognito를 생성한 AWS 리전을 선택하고 사용 가능한 사용자 풀을 선택합니다.
스테이지 변수를 사용하여 사용자 풀을 정의할 수 있습니다. 사용자 풀에는 다음 형식을 사용합니다. `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`
1. **토큰 소스**에 헤더 이름으로 **Authorization**을 입력하여 사용자가 성공적으로 로그인할 때 Amazon Cognito에서 반환하는 자격 증명 또는 액세스 토큰을 전달합니다.
1. (선택 사항) **토큰 검증** 필드에 정규식을 입력하여 Amazon Cognito를 통해 요청에 대한 권한이 부여되기 전에 자격 증명 토큰의 `aud`(대상) 필드를 검증합니다. 액세스 토큰을 사용할 경우, 액세스 토큰에 `aud` 필드가 포함되지 않으므로 이 유효성 검사는 요청을 거부합니다.
1. **권한 부여자 생성**을 선택합니다.
1. `COGNITO_USER_POOLS` 권한 부여자를 만든 후 사용자 풀에서 프로비저닝한 ID 토큰을 제공하여 간접 호출을 테스트할 수 있습니다. 액세스 토큰을 사용하여 권한 부여자 간접 호출을 테스트할 수 없습니다.
[Amazon Cognito 자격 증명 SDK](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html)를 호출하여 사용자 로그인을 수행함으로써 이 자격 증명 토큰을 얻을 수 있습니다. [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) 작업을 사용해도 됩니다. **권한 부여 범위**를 구성하지 않으면 API Gateway는 제공된 토큰을 자격 증명 토큰으로 취급합니다.
이전 절차에서는 새로 생성된 Amazon Cognito 사용자 풀을 사용하는 `COGNITO_USER_POOLS` 권한 부여자를 생성합니다. API 메서드에서 권한 부여자를 활성화하는 방법에 따라 통합된 사용자 풀에서 프로비저닝되는 자격 증명 토큰 또는 액세스 토큰을 사용할 수 있습니다.
**메서드에서 `COGNITO_USER_POOLS` 권한 부여자를 구성하려면**
1. **리소스**를 선택합니다. 새 메서드를 선택하거나 기존 메서드를 선택합니다. 필요하다면 리소스를 생성합니다.
1. **메서드 요청** 탭의 **메서드 요청 설정**에서 **편집**을 선택합니다.
1. **권한 부여자**의 경우 드롭다운 메뉴에서 방금 생성한 **Amazon Cognito 사용자 풀 권한 부여자**를 선택합니다.
1. 자격 증명 토큰을 사용하려면 다음 작업을 수행하세요.
1. **권한 부여 범위**를 비워둡니다.
1. 필요에 따라 **통합 요청**에서 본문 매핑 템플릿에 `$context.authorizer.claims['property-name']` 또는 `$context.authorizer.claims.property-name` 표현식을 추가하여, 사용자 풀에서 백엔드로 지정된 자격 증명 클레임 속성을 전달합니다. `sub` 또는 `custom-sub`처럼 단순한 속성 이름의 경우, 두 표기법이 동일합니다. `custom:role`처럼 복잡한 속성 이름의 경우, 점 표기법을 사용할 수 없습니다. 예를 들어 다음 매핑 표현식은 클레임의 [표준 필드](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)인 `sub` 및 `email`를 백엔드로 전달합니다.
```
{
"context" : {
"sub" : "$context.authorizer.claims.sub",
"email" : "$context.authorizer.claims.email"
}
}
```
사용자 풀을 구성할 때 사용자 지정 클레임 필드를 선언했다면 동일한 패턴에 따라 사용자 지정 필드에 액세스할 수 있습니다. 다음 예에서는 클레임의 사용자 지정 `role` 필드를 가져옵니다.
```
{
"context" : {
"role" : "$context.authorizer.claims.role"
}
}
```
사용자 지정 클레임 필드가 `custom:role`로 선언되면 다음 예를 사용하여 클레임의 속성을 가져옵니다.
```
{
"context" : {
"role" : "$context.authorizer.claims['custom:role']"
}
}
```
1. 액세스 토큰을 사용하려면 다음 작업을 수행하세요.
1. **권한 부여 범위**에 Amazon Cognito 사용자 풀이 생성되었을 때 구성된 범위의 전체 이름을 하나 이상 입력합니다. 예를 들어 [REST API에 대한 Amazon Cognito 사용자 풀 생성](apigateway-create-cognito-user-pool.md)에서 제시된 예를 따르면, 스코프 중 하나는 `https://my-petstore-api.example.com/cats.read`입니다.
런타임 시 이 단계의 메서드에서 지정되는 범위가 수신되는 토큰에서 클레임되는 범위와 일치하면 메서드 호출이 성공합니다. 그렇지 않으면 호출은 `401 Unauthorized` 응답과 함께 실패합니다.
1. **저장**을 선택합니다.
1. 선택한 다른 메서드에 대해 이러한 단계를 반복합니다.
`COGNITO_USER_POOLS` 권한 부여자의 경우, **OAuth Scopes** 옵션이 지정되지 않으면 API Gateway는 제공된 토큰을 자격 증명 토큰으로 취급하고 클레임된 자격 증명을 사용자 풀의 자격 증명과 대조하여 확인합니다. 그렇지 않으면 API Gateway는 제공된 토큰을 액세스 토큰으로 취급하고 토큰에서 클레임된 액세스 범위를 메서드에서 선언된 권한 부여 범위와 대조하여 확인합니다.
API Gateway 콘솔을 사용하는 대신 OpenAPI 정의 파일을 지정하고 API 정의를 API Gateway로 가져와 메서드에서 Amazon Cognito 사용자 풀을 활성화할 수도 있습니다.
**OpenAPI 정의 파일을 사용하여 COGNITO\$1USER\$1POOLS 권한 부여자를 가져오려면**
1. API에 OpenAPI 정의 파일을 생성(또는 내보내기)합니다.
1. `COGNITO_USER_POOLS` 권한 부여자(`MyUserPool`) JSON 정의를 다음과 같이 OpenAPI 3.0의 `securitySchemes` 섹션 또는 Open API 2.0의 `securityDefinitions` 섹션의 일부로 지정합니다.
------
#### [ OpenAPI 3.0 ]
```
"securitySchemes": {
"MyUserPool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}"
]
}
}
```
------
#### [ OpenAPI 2.0 ]
```
"securityDefinitions": {
"MyUserPool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}"
]
}
}
```
------
1. 메서드 권한 부여에 자격 증명 토큰을 사용하려면 루트 리소스에서 다음 GET 메서드에 나온 것처럼 `{ "MyUserPool": [] }`을 메서드의 `security` 정의에 추가합니다.
```
"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"text/html"
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"security": [
{
"MyUserPool": []
}
],
"x-amazon-apigateway-integration": {
"type": "mock",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "'text/html'"
},
}
},
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match"
}
},
...
}
```
1. 메서드 권한 부여에 액세스 토큰을 사용하려면 위의 보안 정의를 `{ "MyUserPool": [resource-server/scope, ...] }`로 변경합니다.
```
"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"text/html"
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"security": [
{
"MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"]
}
],
"x-amazon-apigateway-integration": {
"type": "mock",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "'text/html'"
},
}
},
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match"
}
},
...
}
```
1. 필요에 따라 적절한 OpenAPI 정의 또는 확장자를 사용해 다른 API 구성을 설정할 수 있습니다. 자세한 내용은 [API Gateway용 OpenAPI 확장 프로그램](api-gateway-swagger-extensions.md) 단원을 참조하세요.
# Amazon Cognito 사용자 풀과 통합된 REST API 호출
사용자 풀 권한 부여자를 구성한 상태로 메서드를 호출하려면 클라이언트에서 다음을 수행해야 합니다.
+ 사용자가 사용자 풀을 사용하여 로그인하도록 설정합니다.
+ 사용자가 사용자 풀에 로그인하도록 설정합니다.
+ 사용자 풀에서 로그인한 사용자의 [자격 증명 또는 액세스 토큰](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)을 가져옵니다.
+ `Authorization` 헤더(또는 권한 부여자를 생성할 때 지정한 다른 헤더)에 토큰을 포함합니다.
[AWS Amplify]()를 사용하여 이러한 작업을 수행할 수 있습니다. 자세한 내용은 [Amazon Cognito와 웹 및 모바일 앱 통합](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html)을 참조하세요.
+ Android의 경우 [Android용 Amplify 시작하기](https://docs.amplify.aws/android/build-a-backend/auth/)를 참조하세요.
+ iOS를 사용하려면 [iOS용 Amplify 시작하기](https://docs.amplify.aws/swift/build-a-backend/auth/)를 참조하세요.
+ JavaScript를 사용하려면 [Javascript용 Amplify 시작하기](https://docs.amplify.aws/javascript/build-a-backend/auth/)를 참조하세요.
# API Gateway 콘솔을 사용하여 REST API를 위한 교차 계정 Amazon Cognito 권한 부여자 구성
이제 다른 AWS 계정의 Amazon Cognito 사용자 풀도 API 권한 부여자로 사용할 수 있습니다. Amazon Cognito 사용자 풀은 OAuth 또는 SAML 같은 보유자 토큰 인증 전략을 사용할 수 있습니다. 따라서 여러 API Gateway API에 대해 Amazon Cognito 사용자 풀 권한 부여자를 중앙에서 손쉽게 관리 및 공유할 수 있습니다.
이 단원에서는 Amazon API Gateway 콘솔을 사용하여 교차 계정 Amazon Cognito 사용자 풀을 구성하는 방법을 보여줍니다.
이 지침에서는 한 AWS 계정에서 API Gateway API를, 다른 계정에서는 Amazon Cognito 사용자 풀을 이미 생성했다고 가정합니다.
## REST API를 위한 교차 계정 Amazon Cognito 권한 부여자 생성
API를 포함하고 있는 계정에서 Amazon API Gateway 콘솔에 로그인하고 다음을 수행합니다.
1. API Gateway에서 새 API를 생성하거나 기존 API를 선택합니다.
1. 기본 탐색 창에서 **권한 부여자**를 선택합니다.
1. **권한 부여자 생성**을 선택합니다.
1. 사용자 풀을 사용하도록 새 권한 부여자를 구성하려면 다음을 수행합니다.
1. **권한 부여자 이름**에 이름을 입력합니다.
1. **권한 부여자 유형**으로 **Cognito**를 선택합니다.
1. **Cognito 사용자 풀**에서는 두 번째 계정에 있는 사용자 풀의 전체 ARN을 입력합니다.
**참고**
Amazon Cognito 콘솔에서 **일반 설정** 창의 **풀 ARN** 필드에서 사용자 풀의 ARN을 찾을 수 있습니다.
1. **토큰 소스**에 헤더 이름으로 **Authorization**을 입력하여 사용자가 성공적으로 로그인할 때 Amazon Cognito에서 반환하는 자격 증명 또는 액세스 토큰을 전달합니다.
1. (선택 사항) **토큰 검증** 필드에 정규식을 입력하여 Amazon Cognito를 통해 요청에 대한 권한이 부여되기 전에 자격 증명 토큰의 `aud`(대상) 필드를 검증합니다. 액세스 토큰을 사용할 경우, 액세스 토큰에 `aud` 필드가 포함되지 않으므로 이 유효성 검사는 요청을 거부합니다.
1. **권한 부여자 생성**을 선택합니다.
# CloudFormation을 사용하여 REST API를 위한 Amazon Cognito 권한 부여자 생성
CloudFormation을 사용하여 Amazon Cognito 사용자 풀 및 Amazon Cognito 권한 부여자를 생성합니다. 예제 CloudFormation 템플릿은 다음을 수행합니다.
+ Amazon Cognito 사용자 풀을 생성합니다. 클라이언트는 먼저 사용자를 사용자 풀에 로그인시키고 [자격 증명 또는 액세스 토큰](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)을 얻어야 합니다. 액세스 토큰을 사용하여 API 메서드 호출 권한을 부여하는 경우, 사용자 풀과의 앱 통합을 구성하여 지정된 리소스 서버에서 원하는 사용자 지정 범위를 설정해야 합니다.
+ `GET` 메서드를 사용하여 API Gateway API를 생성합니다.
+ `Authorization` 헤더를 토큰 소스로 사용하는 Amazon Cognito 권한 부여자를 생성합니다.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
UserPool:
Type: AWS::Cognito::UserPool
Properties:
AccountRecoverySetting:
RecoveryMechanisms:
- Name: verified_phone_number
Priority: 1
- Name: verified_email
Priority: 2
AdminCreateUserConfig:
AllowAdminCreateUserOnly: true
EmailVerificationMessage: The verification code to your new account is {####}
EmailVerificationSubject: Verify your new account
SmsVerificationMessage: The verification code to your new account is {####}
VerificationMessageTemplate:
DefaultEmailOption: CONFIRM_WITH_CODE
EmailMessage: The verification code to your new account is {####}
EmailSubject: Verify your new account
SmsMessage: The verification code to your new account is {####}
UpdateReplacePolicy: Retain
DeletionPolicy: Retain
CogAuthorizer:
Type: AWS::ApiGateway::Authorizer
Properties:
Name: CognitoAuthorizer
RestApiId:
Ref: Api
Type: COGNITO_USER_POOLS
IdentitySource: method.request.header.Authorization
ProviderARNs:
- Fn::GetAtt:
- UserPool
- Arn
Api:
Type: AWS::ApiGateway::RestApi
Properties:
Name: MyCogAuthApi
ApiDeployment:
Type: AWS::ApiGateway::Deployment
Properties:
RestApiId:
Ref: Api
DependsOn:
- CogAuthorizer
- ApiGET
ApiDeploymentStageprod:
Type: AWS::ApiGateway::Stage
Properties:
RestApiId:
Ref: Api
DeploymentId:
Ref: ApiDeployment
StageName: prod
ApiGET:
Type: AWS::ApiGateway::Method
Properties:
HttpMethod: GET
ResourceId:
Fn::GetAtt:
- Api
- RootResourceId
RestApiId:
Ref: Api
AuthorizationType: COGNITO_USER_POOLS
AuthorizerId:
Ref: CogAuthorizer
Integration:
IntegrationHttpMethod: GET
Type: HTTP_PROXY
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Outputs:
ApiEndpoint:
Value:
Fn::Join:
- ""
- - https://
- Ref: Api
- .execute-api.
- Ref: AWS::Region
- "."
- Ref: AWS::URLSuffix
- /
- Ref: ApiDeploymentStageprod
- /
```
# API Gateway에서 REST API 통합
API 메서드를 설정한 후 이를 백엔드의 엔드포인트와 통합해야 합니다. 백엔드 엔드포인트는 통합 엔드포인트로도 참조되며, Lambda 함수, HTTP 웹 페이지 또는 AWS 서비스 작업일 수 있습니다.
API 메서드와 마찬가지로 API 통합에는 통합 요청 및 통합 응답이 있습니다. 통합 요청은 백엔드가 수신하는 HTTP 요청을 캡슐화합니다. 클라이언트가 제출하는 메서드 요청과는 다를 수도 있고, 다르지 않을 수도 있습니다. 통합 응답은 백엔드에서 반환되는 출력을 캡슐화하는 HTTP 응답입니다.
통합 요청 설정에 수반되는 작업: 클라이언트가 제출한 메서드 요청을 백엔드로 전달하는 방식을 구성, 필요한 경우 요청 데이터를 통합 요청 데이터로 변환하는 방식을 구성, 호출할 Lambda 함수 지정, 수신 요청을 전송할 HTTP 서버 지정, 또는 호출할 AWS 서비스 작업 지정.
통합 응답을 설정하려면(비 프록시 통합에만 적용) 백엔드에서 반환된 결과를 특정 상태 코드의 메서드 응답에 전달하는 방식을 구성하고, 지정된 통합 응답 파라미터를 사전 구성된 메서드 응답 파라미터로 변환하는 방식을 구성하고, 지정된 본문 매핑 템플릿에 따라 통합 응답 본문을 메서드 응답 본문으로 매핑하는 방식을 구성해야 합니다.
프로그램에 따라 통합 요청은 [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스에 의해 캡슐화되고 통합 응답은 API Gateway의 [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스에 의해 캡슐화됩니다.
통합 요청을 설정하려면 [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스를 생성한 후 이를 사용해 통합 엔드포인트 URL을 구성합니다. 그 다음에 백엔드에 액세스할 수 있는 IAM 권한을 설정하고 매핑을 지정하여 수신 요청 데이터를 백엔드로 전달하기 전에 변환합니다. 비프록시 통합에 대해 통합 응답을 설정하려면 [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스를 생성한 후 이를 사용하여 대상 메서드 응답을 설정합니다. 그 다음에 백엔드 출력을 메서드 응답으로 매핑하는 방식을 구성합니다.
**Topics**
+ [API Gateway에서 통합 요청을 설정](api-gateway-integration-settings-integration-request.md)
+ [API Gateway에서 통합 응답 설정](api-gateway-integration-settings-integration-response.md)
+ [API Gateway의 REST API에 대한 Lambda 통합](set-up-lambda-integrations.md)
+ [API Gateway의 REST API에 대한 HTTP 통합](setup-http-integrations.md)
+ [API Gateway에서 프록시 통합에 대한 통합 응답 스트리밍](response-transfer-mode.md)
+ [API Gateway의 REST API에 대한 프라이빗 통합](private-integration.md)
+ [API Gateway의 REST API 모의 통합](how-to-mock-integration.md)
# API Gateway에서 통합 요청을 설정
통합 요청을 설정하려면 다음과 같은 필수 및 선택 작업을 수행합니다.
1. 메서드 요청 데이터가 백엔드로 전달되는 방식을 결정하는 통합 유형을 선택합니다.
1. 모의가 아닌 통합의 경우, `MOCK` 통합을 제외한 HTTP 메서드와 대상 통합 엔드포인트의 URI를 지정합니다.
1. Lambda 함수 및 기타 AWS 서비스 작업을 통한 통합의 경우, API Gateway에 대한 필수 권한이 있는 IAM 역할을 설정하여 사용자를 대신해 백엔드를 호출합니다.
1. 비 프록시 통합의 경우에는 필수 파라미터 매핑을 설정하여 사전 정의 메서드 요청 파라미터를 적절한 통합 요청 파라미터로 매핑합니다.
1. 비 프록시 통합의 경우, 필요한 본문 매핑을 설정하여 지정된 매핑 템플릿에 따라 특정 콘텐츠 유형의 수신 메서드 요청 본문을 매핑합니다.
1. 비 프록시 통합의 경우, 조건을 지정하여 그 조건에 따라 수신 메서드 요청 데이터가 백엔드로 있는 그대로 패스스루되도록 합니다.
1. 선택 사항으로 바이너리 페이로드에 대해 형식 변환을 처리하는 방식을 지정합니다.
1. 선택 사항으로 캐시 네임스페이스 이름과 캐시 키 파라미터를 선언하여 API 캐싱을 활성화합니다.
이 작업에는 API Gateway의 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스를 생성하고 적절한 속성 값을 설정하는 과정이 수반됩니다. API Gateway 콘솔, AWS CLI 명령, AWS SDK 또는 API Gateway REST API를 사용하면 됩니다.
**Topics**
+ [API 통합 요청의 기본 작업](integration-request-basic-setup.md)
+ [API Gateway API 통합 유형 선택](api-gateway-api-integration-types.md)
+ [프록시 리소스를 사용하여 프록시 통합 설정](api-gateway-set-up-simple-proxy.md)
+ [API Gateway 콘솔을 사용하여 API 통합 요청 설정](how-to-method-settings-console.md)
# API 통합 요청의 기본 작업
통합 요청은 API Gateway가 백엔드에 제출하는 HTTP 요청으로서 클라이언트가 제출한 요청 데이터를 전달하고 필요한 경우 이 데이터를 변환합니다. 통합 요청의 HTTP 메서드(또는 동사) 및 URI는 백엔드(즉 통합 엔드포인트)의 지시를 받습니다. 이들은 각각 메서드 요청의 HTTP 메서드 및 URI와 같거나 다를 수 있습니다.
예를 들어 Lambda 함수가 Amazon S3에서 가져온 파일을 반환하면 이 작업을 직관적으로 `GET` 메서드 요청으로 클라이언트에게 공개할 수 있습니다. 이는 그에 상응하는 통합 요청이 `POST` 요청을 사용해 Lambda 함수를 호출할 것을 요구하더라도 가능합니다. HTTP 엔드포인트의 경우, 메서드 요청과 그에 상응하는 통합 요청이 모두 동일한 HTTP 동사를 사용할 확률이 높습니다. 하지만 이것이 필수적인 것은 아닙니다. 다음 메서드 요청을 통합할 수 있습니다.
```
GET /{var}?query=value
Host: api.domain.net
```
다음 통합 요청을 사용:
```
POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...
{
path: "{var}'s value",
type: "value"
}
```
API 개발자라면 메서드 요청을 위한 HTTP 동사 및 URI는 해당 요구 사항에 적합한 것은 무엇이든지 사용할 수 있습니다. 그러나 통합 엔드포인트의 요구 사항을 따라야 합니다. 메서드 요청 데이터가 통합 요청 데이터와 다르다면 메서드 요청 데이터에서 통합 요청 데이터로 매핑을 제공하여 그 차이를 해소할 수 있습니다.
이전 예제에서 매핑은 `{var}` 메서드 요청의 경로 변수(`query`)와 쿼리 파라미터(`GET`) 값을 `path` 및 `type`의 통합 요청 페이로드 속성 값으로 변환합니다. 매핑 가능한 다른 요청 데이터는 요청 헤더와 본문을 포함합니다. 이에 대해서는 [API Gateway의 REST API 대한 파라미터 매핑](rest-api-parameter-mapping.md)에 설명되어 있습니다.
HTTP 또는 HTTP 프록시 통합 요청을 설정할 때 백엔드 HTTP 엔드포인트 URL을 통합 요청 URI 값으로 할당합니다. 예를 들어 PetStore API에서 반려 동물 페이지를 얻어오라는 메서드 요청에는 다음과 같은 통합 요청 URI가 있습니다.
```
http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
Lambda 또는 Lambda 프록시 통합을 설정할 때 Lambda 함수 호출을 위한 Amazon 리소스 이름(ARN)을 통합 요청 URI 값으로 할당합니다. 이 ARN의 형식은 다음과 같습니다.
```
arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations
```
`arn:aws:apigateway:api-region:lambda:path/` 이후 부분, 즉 `/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations`는 Lambda [호출](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) 작업의 REST API URI 경로입니다. API Gateway 콘솔을 사용하여 Lambda 통합을 설정하면 API Gateway는 사용자에게 리전에서 `lambda-function-name`을 선택하라는 메시지를 표시한 후 ARN을 생성하여 이를 통합 URI에 할당합니다.
다른 AWS 서비스 작업으로 통합 요청을 설정할 때 통합 요청 URI는 Lambda `Invoke` 작업이 있는 통합과 유사한 ARN이기도 합니다. 예를 들어 Amazon S3의 [GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) 작업과 통합하는 경우, 통합 요청 URI는 다음 형식으로 된 ARN입니다.
```
arn:aws:apigateway:api-region:s3:path/{bucket}
```
통합 요청 URI는 그 작업을 지정할 경로 규칙에 관한 것입니다. 여기에서 `{bucket}`은 버킷 이름의 자리 표시자입니다. 또는 AWS 서비스 작업을 그 이름으로 참조할 수 있습니다. 작업 이름을 사용하면 Amazon S3의 `GetBucket` 작업에 대한 통합 요청 URI는 다음과 같아집니다.
```
arn:aws:apigateway:api-region:s3:action/GetBucket
```
작업 기반 통합 요청 URI를 사용하는 경우 `{bucket}` 작업의 입력 형식에 따라 버킷 이름(`{ Bucket: "{bucket}" }`)을 통합 요청 본문(`GetBucket`)에 지정해야 합니다.
AWS 통합의 경우에는 API Gateway가 통합 작업을 호출할 수 있게 허용하도록 [자격 증명](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#credentials)을 구성해야 합니다. IAM 역할을 새로 만들거나 기존 것에서 선택하여 API Gateway가 작업을 호출한 후 그 ARN을 사용해 그 역할을 지정하도록 할 수 있습니다. 다음은 이 ARN의 예를 보여줍니다.
```
arn:aws:iam::account-id:role/iam-role-name
```
이 IAM 역할에는 그 작업이 실행되도록 허용하는 정책이 포함되어야 합니다. 또한 그 역할을 맡을 수 있도록 (그 역할의 신뢰 관계에) 신뢰할 수 있는 엔터티로 선언된 API Gateway가 있어야 합니다. 그러한 권한은 그 작업 자체에 대해 부여할 수 있습니다. 이 권한을 리소스 기반 권한이라고 합니다. Lambda 통합의 경우, Lambda의 [addPermission](https://docs.aws.amazon.com/lambda/latest/dg/API_AddPermission.html) 작업을 호출하여 리소스 기반 권한을 설정한 후 API Gateway 통합 요청에서 `credentials`를 null로 설정합니다.
지금까지 기본적인 통합 설정을 다루었습니다. 고급 설정에는 메서드 요청 데이터를 통합 요청 데이터로 매핑하는 작업이 수반됩니다. 자세한 내용은 [API Gateway에서 REST API의 데이터 변환](rest-api-data-transformations.md) 섹션을 참조하세요.
# API Gateway API 통합 유형 선택
작업 중인 통합 엔드포인트의 유형과 데이터가 통합 엔드포인트로(부터) 전달되는 방식에 따라 API 통합 유형을 선택합니다. Lambda 함수의 경우 Lambda 프록시 통합 또는 Lambda 사용자 지정 통합이 있을 수 있습니다. HTTP 엔드포인트의 경우에는 HTTP 프록시 통합 또는 HTTP 사용자 지정 통합이 있을 수 있습니다. AWS 서비스 작업의 경우에는 비프록시 유형의 AWS 통합만 있습니다. API Gateway도 모의 통합을 지원하는데, 이 경우 API Gateway는 메서드 요청에 응답하기 위한 통합 엔드포인트의 역할을 합니다.
Lambda 사용자 지정 통합은 AWS 통합의 특수 사례로서, 이 경우 통합 엔드포인트는 Lambda 서비스의 [function-invoking 작업](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html)에 해당합니다.
프로그래밍 방식으로 [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스의 [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type) 속성을 설정하여 통합 유형을 선택합니다. Lambda 프록시 통합의 경우, 그 값은 `AWS_PROXY`입니다. Lambda 사용자 지정 통합 및 기타 모든 AWS 통합의 경우에는 `AWS`입니다. HTTP 프록시 통합 및 HTTP 통합의 경우에는 그 값이 각각 `HTTP_PROXY` 및 `HTTP`입니다. 모의 통합의 경우 `type` 값은 `MOCK`입니다.
Lambda 프록시 통합은 단일 Lambda 함수를 사용하여 간소화된 통합 설정을 지원합니다. 이 설정은 간단하며 기존 설정을 손상하지 않고 백엔드와 함께 진화할 수 있습니다. 이러한 이유로 Lambda 함수와의 통합을 적극 권장합니다.
이와 대조적으로 Lambda 사용자 지정 통합을 사용하면 입력 및 출력 데이터 형식의 유사한 요구 사항이 있는 다양한 통합 엔드포인트에 대해 구성된 매핑 템플릿을 재사용할 수 있습니다. 이 설정은 더 복잡하며 더 고급 애플리케이션 시나리오에 권장됩니다.
이와 마찬가지로 HTTP 프록시 통합에는 간소화된 통합 설정이 있으며 기존 설정을 손상하지 않고 백엔드와 함께 진화할 수 있습니다. HTTP 사용자 지정 통합은 설정하기가 더 복잡하지만 다른 통합 엔드포인트에 대해 구성된 매핑 템플릿을 재사용할 수 있습니다.
다음 목록은 지원되는 통합 유형을 요약한 것입니다.
+ `AWS`: 이 통합 유형을 사용하면 API에서 AWS 서비스 작업을 공개할 수 있습니다. `AWS` 통합의 경우, 통합 요청과 통합 응답을 모두 구성하고 메서드 요청에서 통합 요청으로, 통합 응답에서 메서드 응답으로 필수적인 데이터 매핑을 설정해야 합니다.
+ `AWS_PROXY`: 이러한 유형의 통합을 사용해 유연하고 다목적이며 간소화된 통합 설정으로 API 메서드가 Lambda 함수 호출 작업에 통합되도록 할 수 있습니다. 이러한 통합은 통합된 Lambda 기능과 클라이언트 간의 직접적인 상호 작용에 의존합니다.
Lambda 프록시 통합으로도 알려진 이러한 유형의 통합에서는 통합 요청 또는 통합 응답을 설정하지 않습니다. API Gateway는 클라이언트로부터 입력으로 수신되는 요청을 백엔드 Lambda 함수로 전달합니다. 통합된 Lambda 함수는 [이 형식의 입력](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format)을 받아들여 그 입력을 요청 헤더, URL 경로 변수, 쿼리 문자열 파라미터 및 적용 가능한 본문 등 사용 가능한 모든 소스로부터 구문 분석합니다. 이 함수는 이 [출력 형식](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format)에 따라 결과를 반환합니다.
이것은 API Gateway를 통해 Lambda 함수를 호출할 때 선호되는 통합 유형이며 함수 호출 작업 외의 Lambda 작업을 포함한 기타 모든 AWS 서비스 작업에는 적용할 수 없습니다.
+ `HTTP`: 이 통합 유형을 사용하면 API에서 백엔드의 HTTP 엔드포인트를 공개할 수 있습니다. HTTP 사용자 지정 통합으로도 알려진 `HTTP` 통합에서는 통합 요청과 통합 응답을 둘 다 설정해야 합니다. 메서드 요청에서 통합 요청으로, 그리고 통합 응답에서 메서드 응답으로 필수적인 데이터 매핑을 설정해야 합니다.
+ `HTTP_PROXY`: HTTP 프록시 통합을 사용하여 클라이언트는 단일 API 메서드에서 간소화된 통합 설정을 통해 백엔드 HTTP 엔드포인트에 액세스할 수 있습니다. 통합 요청 또는 통합 응답은 설정하지 않습니다. API Gateway는 클라이언트로부터 수신되는 요청을 HTTP 엔드포인트로 전달하고 HTTP 엔드포인트에서 발신되는 응답을 클라이언트로 전달합니다.
+ `MOCK`: 이 통합 유형을 사용하면 API Gateway에서 요청을 백엔드로 전송하지 않고 응답을 반환할 수 있습니다. 이것은 백엔드 사용에 대한 요금을 발생시키지 않으면서 통합 설정을 테스트하고 협력을 통한 API의 발전을 활성화하는 데 사용할 수 있으므로 API 테스트에 유용합니다.
협력을 통한 발전을 통해 팀은 `MOCK` 통합을 사용해 다른 팀이 소유한 API 구성 요소의 시뮬레이션을 설정함으로써 자신의 개발 노력을 격리시킬 수 있습니다. 또한 API 메서드가 CORS 액세스를 허용하는지 확인하기 위해 CORS 관련 헤더를 반환하는 데도 유용합니다. 사실 API Gateway 콘솔은 `OPTIONS` 메서드를 통합하여 모의 통합으로 CORS를 지원합니다. [게이트웨이 응답](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)은 모의 통합의 다른 예입니다.
# 프록시 리소스를 사용하여 프록시 통합 설정
[프록시 리소스](api-gateway-method-settings-method-request.md#api-gateway-proxy-resource)를 사용하여 API Gateway API에서 프록시 통합을 설정하려면 다음 작업을 수행합니다.
+ `{proxy+}`의 복잡한 경로 변수를 사용하여 프록시 리소스를 생성합니다.
+ 프록시 리소스에서 `ANY` 메서드를 설정합니다.
+ HTTP 또는 Lambda 통합 유형을 사용하여 리소스 및 메서드를 백엔드와 통합합니다.
**참고**
복잡한 경로 변수, `ANY` 메서드 및 프록시 통합 유형은 일반적으로 함께 사용되지만 독립적인 기능입니다. 복잡한 리소스에 대해 특정 HTTP 메서드를 구성하거나 비 프록시 통합 유형을 프록시 리소스에 적용할 수 있습니다.
API Gateway는 Lambda 프록시 통합 또는 HTTP 프록시 통합으로 메서드를 처리할 때 특정 제한 및 제약을 적용합니다. 자세한 내용은 [Amazon API Gateway 중요 정보](api-gateway-known-issues.md) 단원을 참조하세요.
**참고**
패스스루를 포함하는 프록시 통합을 사용할 경우 API Gateway에서는 페이로드의 콘텐츠 유형이 지정되지 않은 경우 기본 `Content-Type:application/json` 헤더를 반환합니다.
프록시 리소스는 HTTP 프록시 통합이나 Lambda 프록시 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)을 사용하여 백엔드와 통합될 때 가장 강력합니다.
## 프록시 리소스를 사용한 HTTP 프록시 통합
API Gateway REST API에서 `HTTP_PROXY`로 지정되는 HTTP 프록시 통합은 메서드 요청을 백엔드 HTTP 엔드포인트와 통합하기 위한 것입니다. API Gateway에서는 이 통합 유형을 사용하여 프런트엔드와 백엔드 사이에 전체 요청 및 응답을 전달할 뿐이며 특정 [제약 및 제한](api-gateway-known-issues.md)의 적용을 받습니다.
**참고**
HTTP 프록시 통합은 다중 값 헤더와 쿼리 문자열을 지원합니다.
HTTP 프록시 통합을 프록시 리소스에 적용할 경우 단일 통합 설정으로 HTTP 백엔드의 일부 또는 전체 엔드포인트 계층을 공개하도록 API를 설정할 수 있습니다. 예를 들어 웹사이트의 백엔드가 루트 노드(`/site`)에서 `/site/a0/a1/.../aN`, `/site/b0/b1/.../bM`과 같은 여러 트리 노드 분기로 구성된다고 가정합니다. `ANY`의 프록시 리소스에 대한 `/api/{proxy+}` 메서드를 URL 경로가 `/site/{proxy}`인 백엔드 엔드포인트와 통합할 경우, 단일 통합 요청으로 `[a0, a1, ..., aN, b0, b1, ...bM, ...]`에 대해 모든 HTTP 작업(GET, POST 등)을 지원할 수 있습니다. 그 대신에 프록시 통합을 특정 HTTP 메서드(예: `GET`)에 적용할 경우 그 결과로 얻는 통합 요청은 그러한 백엔드 노드 중 하나에서 지정된(예: `GET`) 작업으로 작동합니다.
## 프록시 리소스를 사용한 Lambda 프록시 통합
API Gateway REST API에서 `AWS_PROXY`로 지정되는 Lambda 프록시 통합은 백엔드에서 메서드 요청을 Lambda 함수와 통합하기 위한 것입니다. 이 통합 유형을 통해 API Gateway에서는 기본 매핑 템플릿을 적용하여 전체 요청을 Lambda 함수로 보내고 Lambda 함수의 출력을 HTTP 응답으로 변환합니다.
마찬가지로 Lambda 프록시 통합을 `/api/{proxy+}`의 프록시 리소스에 적용하여 백엔드 Lambda 함수가 `/api` 아래의 API 리소스 변경에 개별적으로 대응하도록 단일 통합을 설정할 수 있습니다.
# API Gateway 콘솔을 사용하여 API 통합 요청 설정
API 메서드 설정은 메서드를 정의하고 그 동작을 설명합니다. 메서드를 설정하려면 해당 메서드를 노출시킬 루트('/') 등의 리소스, HTTP 메서드(`GET`, `POST` 등) 및 대상 백엔드와의 통합 방식을 지정해야 합니다. 메서드 요청 및 응답은 호출하는 앱과의 관계를 규정하며, 이를 통해 API는 어떤 파라미터를 받게 되고 응답은 어떤 유형인지 지정합니다.
다음 절차에서는 API Gateway 콘솔을 사용하여 통합 요청을 생성하는 방법을 설명합니다.
**Topics**
+ [Lambda 통합 설정](#how-to-method-settings-console-lambda)
+ [HTTP 통합 설정](#how-to-method-settings-console-http)
+ [AWS 서비스 통합 설정](#how-to-method-settings-console-aws)
+ [모의 통합 설정](#how-to-method-settings-console-mock)
## Lambda 통합 설정
Lambda 함수 통합을 사용하여 API를 Lambda 함수에 통합할 수 있습니다. API 수준에서 비프록시 통합을 생성하는 경우 `AWS` 통합 유형이고, 프록시 통합을 생성하는 경우 `AWS_PROXY` 통합 유형입니다.
**Lambda 통합을 설정하려면**
1. **리소스** 창에서 **메서드 생성**을 선택합니다.
1. **메서드 유형**에서 HTTP 메서드를 선택합니다.
1. **통합 유형**에서 **Lambda 함수(Lambda Function)**를 선택합니다.
1. Lambda 프록시 통합을 사용하려면 **Lambda 프록시 통합**을 활성화합니다. Lambda 프록시 통합에 대한 자세한 내용은 [API Gateway Lambda 프록시 통합 이해](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy) 섹션을 참조하세요.
1. **Lambda 함수**에서 Lambda 함수의 이름을 입력합니다.
API와 다른 리전에서 Lambda 함수를 사용하는 경우, 드롭다운 메뉴에서 리전을 선택하고 Lambda 함수의 이름을 입력합니다. 교차 계정 Lambda 함수를 사용하는 경우 함수 ARN을 입력합니다.
1. 기본 제한 시간 값인 29초를 사용하려면 **기본 제한 시간**을 활성화된 상태로 유지합니다. 사용자 지정 제한 시간을 설정하려면 **기본 제한 시간**을 선택하고 `50` \$1 `29000`밀리초 사이의 제한 시간 값을 입력합니다.
1. (옵션) 다음 드롭다운 메뉴를 사용하여 메서드 요청 설정을 구성할 수 있습니다. **메서드 요청 설정을** 선택하고 메서드 요청을 구성합니다. 자세한 내용은 [API Gateway 콘솔에서 API Gateway 메서드 요청 편집](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)의 3단계를 참조하세요.
메서드를 생성한 후 메서드 요청 설정을 구성할 수도 있습니다.
1. **메서드 생성**을 선택합니다.
## HTTP 통합 설정
HTTP 통합을 사용하여 API를 HTTP 엔드포인트와 통합할 수 있습니다. API 수준에서 이는 `HTTP` 통합 유형입니다.
**HTTP 통합을 설정하려는 경우**
1. **리소스** 창에서 **메서드 생성**을 선택합니다.
1. **메서드 유형**에서 HTTP 메서드를 선택합니다.
1. **통합 유형**에서 **HTTP**를 선택합니다.
1. HTTP 프록시 통합을 사용하려면 **HTTP 프록시 통합**을 활성화합니다. HTTP 프록시 통합에 대한 자세한 내용은 [API Gateway에서 HTTP 프록시 통합 설정](setup-http-integrations.md#api-gateway-set-up-http-proxy-integration-on-proxy-resource) 섹션을 참조하세요.
1. **HTTP 메서드(HTTP method)**에서 HTTP 백엔드의 메서드와 가장 가까운 HTTP 메서드 유형을 선택합니다.
1. **엔드포인트 URL**에서 이 메서드를 사용하고자 하는 HTTP 백엔드의 URL을 입력합니다.
1. **콘텐츠 처리**에서 콘텐츠 처리 동작을 선택합니다.
1. 기본 제한 시간 값인 29초를 사용하려면 **기본 제한 시간**을 활성화된 상태로 유지합니다. 사용자 지정 제한 시간을 설정하려면 **기본 제한 시간**을 선택하고 `50` \$1 `29000`밀리초 사이의 제한 시간 값을 입력합니다.
1. (옵션) 다음 드롭다운 메뉴를 사용하여 메서드 요청 설정을 구성할 수 있습니다. **메서드 요청 설정을** 선택하고 메서드 요청을 구성합니다. 자세한 내용은 [API Gateway 콘솔에서 API Gateway 메서드 요청 편집](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)의 3단계를 참조하세요.
메서드를 생성한 후 메서드 요청 설정을 구성할 수도 있습니다.
1. **메서드 생성**을 선택합니다.
## AWS 서비스 통합 설정
AWS 서비스 통합을 사용하여 API를 AWS 서비스에 직접 통합할 수 있습니다. API 수준에서 이는 `AWS` 통합 유형입니다.
API Gateway API를 설정하여 다음 중 하나를 수행하려면:
+ 새 Lambda 함수를 생성합니다.
+ Lambda 함수에 리소스 권한을 설정합니다.
+ 기타 Lambda 서비스 작업을 수행합니다.
**AWS 서비스**를 선택해야 합니다.
**AWS 서비스 통합을 설정하려면**
1. **리소스** 창에서 **메서드 생성**을 선택합니다.
1. **메서드 유형**에서 HTTP 메서드를 선택합니다.
1. **통합 유형**에서 **AWS 서비스**를 선택합니다.
1. **AWS 리전**에서 이 메서드를 사용하여 작업을 호출하고자 하는 AWS 리전을 선택합니다.
1. **AWS 서비스**에서 이 메서드로 호출하려는 AWS 서비스를 선택합니다.
1. **AWS 하위 도메인**에 AWS 서비스가 사용하는 하위 도메인을 입력합니다. 일반적으로 이 필드는 비워 둡니다. 일부 AWS 서비스는 호스트의 일부로 하위 도메인을 지원할 수 있습니다. 사용 가능 여부, 그리고 사용 가능할 경우 세부 정보는 서비스 설명서를 참조하세요.
1. **HTTP 메서드(HTTP method)**에서 작업에 해당하는 HTTP 메서드 유형을 선택합니다. HTTP 메서드 유형에 대해서는 **AWS 서비스**에서 선택한 AWS 서비스에 관한 API 참조 문서를 참조하세요.
1. **작업 유형**에서 API 작업을 사용하려면 **작업 이름 사용**을 선택하고 사용자 지정 리소스 경로를 사용하려면 **경로 재정의 사용**을 선택합니다. 사용 가능한 작업 및 사용자 지정 리소스 경로에 대해서는 **AWS 서비스**에서 선택한 AWS 서비스에 관한 API 참조 문서를 참조하세요.
1. **작업 이름** 또는 **경로 재정의**를 입력합니다.
1. **실행 역할**에 메서드가 작업을 호출할 때 사용할 IAM 역할의 ARN을 입력합니다.
IAM 역할을 생성하려는 경우 [1단계: AWS 서비스 프록시 실행 역할 생성](getting-started-aws-proxy.md#getting-started-aws-proxy-add-roles)의 지침을 조정할 수 있습니다. 원하는 작업 개수 및 리소스 설명으로 액세스 정책을 지정합니다. 자세한 내용은 [Amazon API Gateway에서 IAM을 사용하는 방식](security_iam_service-with-iam.md) 섹션을 참조하세요.
작업 및 리소스 설명문 구문은 **AWS 서비스**에서 선택한 AWS서비스에 관한 문서를 참조하세요.
IAM 역할의 신뢰 관계에 대해 다음과 같이 지정합니다. 이렇게 하면 API Gateway가 AWS 계정을 대신해 작업을 수행할 수 있습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. 기본 제한 시간 값인 29초를 사용하려면 **기본 제한 시간**을 활성화된 상태로 유지합니다. 사용자 지정 제한 시간을 설정하려면 **기본 제한 시간**을 선택하고 `50` \$1 `29000`밀리초 사이의 제한 시간 값을 입력합니다.
1. (옵션) 다음 드롭다운 메뉴를 사용하여 메서드 요청 설정을 구성할 수 있습니다. **메서드 요청 설정을** 선택하고 메서드 요청을 구성합니다. 자세한 내용은 [API Gateway 콘솔에서 API Gateway 메서드 요청 편집](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)의 3단계를 참조하세요.
메서드를 생성한 후 메서드 요청 설정을 구성할 수도 있습니다.
1. **메서드 생성**을 선택합니다.
## 모의 통합 설정
API Gateway가 정적 응답을 반환하는 백엔드로 작동하기를 원할 경우 모의 통합을 사용합니다. API 수준에서 이는 `MOCK` 통합 유형입니다. 일반적으로 API가 최종적인 것은 아니지만 API 응답을 생성하여 테스트를 위해 종속 팀을 차단하고자 하는 경우 `MOCK` 통합을 사용할 수 있습니다. `OPTION` 메서드의 경우 API Gateway가 `MOCK` 통합을 기본값으로 설정하여 적용된 API 리소스에 대한 CORS 사용 헤더를 반환합니다.
**모의 통합을 설정하려면**
1. **리소스** 창에서 **메서드 생성**을 선택합니다.
1. **메서드 유형**에서 HTTP 메서드를 선택합니다.
1. **통합 유형**에서 **모의**를 선택합니다.
1. (옵션) 다음 드롭다운 메뉴를 사용하여 메서드 요청 설정을 구성할 수 있습니다. **메서드 요청 설정을** 선택하고 메서드 요청을 구성합니다. 자세한 내용은 [API Gateway 콘솔에서 API Gateway 메서드 요청 편집](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)의 3단계를 참조하세요.
메서드를 생성한 후 메서드 요청 설정을 구성할 수도 있습니다.
1. **메서드 생성**을 선택합니다.
# API Gateway에서 통합 응답 설정
비 프록시 통합의 경우에는 통합 응답을 하나 이상 설정하고 이를 기본 응답으로 만들어 백엔드에서 클라이언트로 반환되는 결과를 전달해야 합니다. 그 결과를 있는 그대로 패스스루하거나 통합 응답 데이터를 메서드 응답 데이터로 변환(둘이 서로 다른 형식인 경우)할 수 있습니다.
프록시 통합의 경우, API Gateway는 백엔드 출력을 클라이언트에게 HTTP 응답으로 자동 전달합니다. 통합 응답이나 메서드 응답은 설정하지 않습니다.
통합 응답을 설정하려면 다음과 같은 필수 및 선택 작업을 수행합니다.
1. 통합 응답 데이터가 매핑된 메서드 응답의 HTTP 상태 코드를 지정합니다. 이 항목은 필수입니다.
1. 이 통합 응답이 표시할 백엔드 출력을 선택하기 위해 표현식을 정의합니다. 이를 비워둘 경우, 응답은 아직 구성되지 않은 응답을 파악하는 데 사용되는 기본 응답입니다.
1. 필요한 경우 키-값 페어로 구성된 매핑을 선언하여 지정된 통합 응답 파라미터를 특정 메서드 응답 파라미터로 매핑합니다.
1. 필요한 경우 본문 매핑 템플릿을 추가하여 특정 통합 응답 페이로드를 지정된 메서드 응답 페이로드로 변환합니다.
1. 필요한 경우 바이너리 페이로드에 대해 형식 변환을 처리하는 방식을 지정합니다.
통합 응답은 백엔드 응답을 캡슐화하는 HTTP 응답입니다. HTTP 엔드포인트의 경우, 백엔드 응답은 HTTP 응답입니다. 통합 응답 상태 코드는 백엔드에서 반환하는 상태 코드를 받아들일 수 있고, 통합 응답 본문은 백엔드에서 반환하는 페이로드입니다. Lambda 엔드포인트의 경우, 백엔드 응답은 Lambda 함수에서 반환되는 출력입니다. Lambda 통합의 경우, Lambda 함수 출력은 `200 OK` 응답으로 반환됩니다. 페이로드에는 JSON 문자열이나 JSON 객체, 또는 JSON 객체인 오류 메시지 등 JSON 데이터가 결과로 포함될 수 있습니다. 정규식을 [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) 속성에 할당하여 오류 응답을 적절한 HTTP 오류 응답으로 매핑할 수 있습니다. Lambda 함수 오류 응답에 대한 자세한 내용은 [API Gateway에서 Lambda 오류 처리](handle-errors-in-lambda-integration.md)를 참조하세요. Lambda 프록시 통합의 경우, Lambda 함수는 다음 형식의 출력을 반환해야 합니다.
```
{
statusCode: "...", // a valid HTTP status code
headers: {
custom-header: "..." // any API-specific custom header
},
body: "...", // a JSON string.
isBase64Encoded: true|false // for binary support
}
```
Lambda 함수 응답을 적당한 HTTP 응답으로 매핑할 필요가 없습니다.
클라이언트에게 결과를 반환하려면 통합 응답을 설정하여 엔드포인트 응답을 있는 그대로 그에 상응하는 메서드 응답으로 패스스루합니다. 또는 엔드포인트 응답 데이터를 메서드 응답 데이터에 매핑할 수 있습니다. 매핑할 수 있는 응답 데이터에는 응답 상태 코드, 응답 헤더 파라미터 및 응답 본문이 포함됩니다. 반환된 상태 코드에 대해 메서드 응답이 정의되지 않은 경우, API Gateway는 500 오류를 반환합니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 섹션을 참조하세요.
# API Gateway의 REST API에 대한 Lambda 통합
Lambda 프록시 통합 또는 Lambda 비프록시(사용자 지정) 통합을 사용하여 API 메서드를 Lambda 함수와 통합할 수 있습니다.
Lambda 프록시 통합에서는 필요한 설정이 간단합니다. 통합의 HTTP 메서드를 POST로, 통합 엔드포인트 URI를 특정 Lambda 함수의 Lambda 함수 호출 작업의 ARN으로 설정하고, 사용자를 대신해 Lambda 함수를 호출할 수 있는 API Gateway 권한을 부여합니다.
Lambda 비 프록시 통합에서는, 프록시 통합 설정 단계 외에도 수신 요청 데이터가 통합 요청에 매핑되는 방식과 그 결과로 얻는 통합 응답 데이터가 메서드 응답에 매핑되는 방식도 지정합니다.
**Topics**
+ [API Gateway의 Lambda 프록시 통합](set-up-lambda-proxy-integrations.md)
+ [API Gateway에서 Lambda 사용자 지정 통합 설정](set-up-lambda-custom-integrations.md)
+ [백엔드 Lambda 함수의 비동기 호출 설정](set-up-lambda-integration-async.md)
+ [API Gateway에서 Lambda 오류 처리](handle-errors-in-lambda-integration.md)
# API Gateway의 Lambda 프록시 통합
다음 섹션에서는 Lambda 프록시 통합을 사용하는 방법을 보여줍니다.
**Topics**
+ [API Gateway Lambda 프록시 통합 이해](#api-gateway-create-api-as-simple-proxy)
+ [다중 값 헤더 및 쿼리 문자열 파라미터에 대한 지원](#apigateway-multivalue-headers-and-parameters)
+ [프록시 통합에 대한 Lambda 함수의 입력 형식](#api-gateway-simple-proxy-for-lambda-input-format)
+ [프록시 통합에 대한 Lambda 함수의 출력 형식](#api-gateway-simple-proxy-for-lambda-output-format)
+ [AWS CLI를 사용하여 API Gateway용 Lambda 프록시 통합 설정](set-up-lambda-proxy-integration-using-cli.md)
+ [OpenAPI 정의와 Lambda 프록시 통합을 사용하여 프록시 리소스 설정](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md)
## API Gateway Lambda 프록시 통합 이해
Amazon API Gateway의 Lambda 프록시 통합은 단일 API 메서드의 설정을 통해 API를 구축하기 위한 간단하고 강력하며 민첩한 메커니즘입니다. Lambda 프록시 통합을 사용하면 클라이언트가 백엔드에서 단일 Lambda 함수를 호출할 수 있습니다. 이 함수는 다른 Lambda 함수를 호출하는 등 다른 AWS 서비스의 많은 리소스 또는 기능에 액세스합니다.
Lambda 프록시 통합에서 클라이언트가 API 요청을 제출하면 API Gateway는 통합된 Lambda 함수로 [이벤트 객체](#api-gateway-simple-proxy-for-lambda-input-format)를 전달합니다. 단, 요청 파라미터의 순서는 유지되지 않습니다. [요청 데이터](#api-gateway-simple-proxy-for-lambda-input-format)에는 요청 헤더, 쿼리 문자열 파라미터, URL 경로 변수, 페이로드 및 API 구성 데이터가 포함되어 있습니다. 구성 데이터에는 현재 배포 단계 이름, 단계 변수, 사용자 ID 또는 권한 부여 컨텍스트(있는 경우)가 포함될 수 있습니다. 백엔드 Lambda 함수는 수신되는 요청 데이터를 구문 분석하여 반환하는 응답을 결정합니다. API Gateway에서 Lambda 출력을 클라이언트에 대한 API 응답으로 전달하려면 Lambda 함수에서 [이 형식](#api-gateway-simple-proxy-for-lambda-output-format)으로 결과를 반환해야 합니다.
API Gateway는 Lambda 프록시 통합을 위해 클라이언트와 백엔드 Lambda 함수 사이에 개입하지 않기 때문에 클라이언트와 통합된 Lambda 함수는 API의 기존 통합 설정을 깨지 않고 서로의 변화에 맞게 조정할 수 있습니다. 이렇게 하려면 클라이언트가 백엔드 Lambda 함수에 의해 제정된 애플리케이션 프로토콜을 따라야 합니다.
모든 API 메서드에 대해 Lambda 프록시 통합을 설정할 수 있습니다. 그러나 Lambda 프록시 통합은 일반 프록시 리소스가 포함된 API 메서드에 대해 구성될 때 더 강력합니다. 일반 프록시 리소스는 `{proxy+}`의 특수 템플릿 경로 변수, catch-all `ANY` 메서드 자리 표시자 또는 둘 다로 표시될 수 있습니다. 클라이언트는 수신되는 요청의 백엔드 Lambda 함수에 대한 입력을 요청 파라미터 또는 해당 페이로드로 전달할 수 있습니다. 요청 파라미터에는 헤더, URL 경로 변수, 쿼리 문자열 파라미터 및 해당 페이로드가 포함되어 있습니다. 통합된 Lambda 함수는 필요한 입력이 누락된 경우 요청을 처리하고 의미 있는 오류 메시지로 클라이언트에 응답하기 전에 모든 입력 소스를 확인합니다.
일반 HTTP 메서드 `ANY` 및 일반 리소스 `{proxy+}`와 통합된 API 메서드를 호출할 때 클라이언트는 `ANY` 대신 특정 HTTP 메서드를 사용하여 요청을 제출합니다. 또한 클라이언트는 `{proxy+}` 대신 특정 URL 경로를 지정하고 필수 헤더, 쿼리 문자열 파라미터 또는 해당 페이로드를 포함합니다.
다음 목록에는 Lambda 프록시 통합을 통해 다양한 API 메서드의 런타임 동작이 요약되어 있습니다.
+ `ANY /{proxy+}`: 클라이언트는 특정 HTTP 메서드를 선택하고 특정 리소스 경로 계층을 설정해야 하며 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 설정하여 데이터를 통합된 Lambda 함수에 대한 입력으로 전달할 수 있습니다.
+ `ANY /res`: 클라이언트는 특정 HTTP 메서드를 선택해야 하고 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 설정하여 데이터를 통합된 Lambda 함수에 대한 입력으로 전달할 수 있습니다.
+ `GET|POST|PUT|... /{proxy+}`: 클라이언트는 특정 리소스 경로 계층, 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 설정하여 데이터를 통합된 Lambda 함수에 대한 입력으로 전달할 수 있습니다.
+ `GET|POST|PUT|... /res/{path}/...`: 클라이언트는 특정 경로 세그먼트(`{path}` 변수의 경우)를 선택해야 하고 요청 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 설정하여 입력 데이터를 통합된 Lambda 함수에 전달할 수 있습니다.
+ `GET|POST|PUT|... /res`: 클라이언트는 요청 헤더, 쿼리 문자열 파라미터 및 해당 페이로드를 선택하여 입력 데이터를 통합된 Lambda 함수에 전달할 수 있습니다.
프록시 리소스 `{proxy+}` 및 사용자 지정 리소스 `{custom}` 모두 템플릿 경로 변수로 표현됩니다. 그러나 `{proxy+}`는 경로 계층을 따라 모든 리소스를 참조할 수 있지만 `{custom}`은 특정 경로 세그먼트만 참조합니다. 예를 들어 식품 매장은 부서 이름, 생산 카테고리 및 제품 유형별로 온라인 제품 재고를 구성할 수 있습니다. 식품 매장의 웹 사이트는 사용자 지정 리소스의 템플릿 경로 변수인 `/{department}/{produce-category}/{product-type}`을 사용하여 사용 가능한 제품을 나타낼 수 있습니다. 예를 들어 사과는 `/produce/fruit/apple`로, 당근은 `/produce/vegetables/carrot`으로 표현됩니다. 또한 `/{proxy+}`를 사용하여 온라인 매장에서 쇼핑하는 동안 고객이 검색할 수 있는 부서, 생산 카테고리 또는 제품 유형을 나타낼 수 있습니다. 예를 들어 `/{proxy+}`는 다음 항목 중 하나를 참조할 수 있습니다.
+ `/produce`
+ `/produce/fruit`
+ `/produce/vegetables/carrot`
고객이 사용 가능한 제품, 제품 카테고리 및 관련 매장 부서를 검색할 수 있게 하려면 읽기 전용 권한으로 `GET /{proxy+}`의 단일 메서드를 공개할 수 있습니다. 마찬가지로 감독자가 `produce` 부서의 재고를 업데이트할 수 있게 하려면 읽기/쓰기 권한으로 `PUT /produce/{proxy+}`의 또 다른 단일 메서드를 설정할 수 있습니다. 점원이 야채의 총 누계를 업데이트할 수 있게 하려면 읽기/쓰기 권한으로 `POST /produce/vegetables/{proxy+}` 메서드를 설정할 수 있습니다. 매장 관리자가 사용 가능한 제품에 대해 가능한 조치를 수행할 수 있게 하려면 온라인 매장 개발자는 읽기/쓰기 권한으로 `ANY /{proxy+}` 메서드를 공개할 수 있습니다. 어떤 경우에도 런타임 시 고객 또는 직원은 선택한 부서에서 지정된 유형의 특정 제품, 선택한 부서의 특정 생산 카테고리 또는 특정 부서를 선택해야 합니다.
API Gateway 프록시 통합 설정에 대한 자세한 내용은 [프록시 리소스를 사용하여 프록시 통합 설정](api-gateway-set-up-simple-proxy.md)를 참조하세요.
프록시 통합을 위해서는 클라이언트가 백엔드 요구 사항에 대해 보다 자세한 지식을 갖추고 있어야 합니다. 따라서 최적의 앱 성능과 사용자 경험을 보장하려면 백엔드 개발자는 클라이언트 개발자에게 백엔드 요구 사항을 명확하게 전달하고 요구 사항이 충족되지 않으면 강력한 오류 피드백 메커니즘을 제공해야 합니다.
## 다중 값 헤더 및 쿼리 문자열 파라미터에 대한 지원
API Gateway는 이제 동일한 이름을 지닌 복수의 헤더 및 쿼리 문자열 파라미터를 지원합니다. 다중 값 헤더와 단일 값 헤더 및 파라미터는 동일한 요청 및 응답에서 결합될 수 있습니다. 자세한 내용은 [프록시 통합에 대한 Lambda 함수의 입력 형식](#api-gateway-simple-proxy-for-lambda-input-format) 및 [프록시 통합에 대한 Lambda 함수의 출력 형식](#api-gateway-simple-proxy-for-lambda-output-format)(을)를 참조하세요.
## 프록시 통합에 대한 Lambda 함수의 입력 형식
Lambda 프록시 통합을 사용할 경우 API Gateway에서 전체 클라이언트 요청을 백엔드 Lambda 함수의 입력 `event` 파라미터에 매핑합니다. 다음 예제에서는 API Gateway가 Lambda 프록시 통합으로 보내는 이벤트의 구조를 보여줍니다.
이 예제에서는 API Gateway에 대한 간접 호출이 다음과 같다고 가정합니다.
```
curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2'
```
출력은 다음과 같습니다.
```
{
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2",
"header3": "value1,value2"
},
"multiValueHeaders": {
"header1": ["value1"],
"header2": ["value1","value2"],
"header3": ["value1,value2"]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value2",
"parameter3": "value1,value2"
},
"multiValueQueryStringParameters": {
"parameter1": ["value1"],
"parameter2": ["value1","value2"],
"parameter3": ["value1,value2"]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "IP",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
**참고**
입력에서:
`headers` 키에는 단일 값 헤더만 있습니다.
`multiValueHeaders` 키에는 다중 값 헤더와 단일 값 헤더가 있을 수 있습니다.
`headers` 및 `multiValueHeaders` 모두에 대해 값을 지정한 경우, API Gateway는 이들 헤더를 단일 목록으로 병합합니다. 동일한 키-값 페어가 양쪽 모두에 지정된 경우, `multiValueHeaders`의 값만이 병합된 목록에 표시됩니다.
백엔드 Lambda 함수에 대한 입력에서 `requestContext` 객체는 키-값 페어의 맵입니다. 각 페어에서 키는 [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference) 변수 속성의 이름이고, 값은 그 속성의 값입니다. API Gateway는 새 키를 맵에 추가할 수 있습니다.
활성화된 기능에 따라 `requestContext` 맵은 API마다 다를 수 있습니다. 예를 들어 앞의 예제에서는 권한 부여 유형이 지정되지 않았으므로 `$context.authorizer.*` 또는 `$context.identity.*` 속성이 없습니다. 권한 부여 유형이 지정된 경우에는 다음과 같이 API Gateway가 `requestContext.identity` 객체의 통합 엔드포인트에 권한이 부여된 사용자 정보를 전달합니다.
+ 권한 부여 유형이 `AWS_IAM`인 경우, 권한 부여된 사용자 정보에 `$context.identity.*` 속성이 포함됩니다.
+ 권한 부여 유형이 `COGNITO_USER_POOLS`(Amazon Cognito 권한 부여자)인 경우, 권한 부여된 사용자 정보에 `$context.identity.cognito*` 및 `$context.authorizer.claims.*` 속성이 포함됩니다.
+ 권한 부여 유형이 `CUSTOM`(Lambda 권한 부여자)인 경우, 권한 부여된 사용자 정보에 `$context.authorizer.principalId` 및 기타 적용되는 `$context.authorizer.*` 속성이 포함됩니다.
## 프록시 통합에 대한 Lambda 함수의 출력 형식
Lambda 프록시 통합을 사용할 경우 API Gateway에서는 백엔드 Lambda 함수에 다음 JSON 형식에 따라 출력을 반환하도록 요구합니다.
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}
```
출력에서:
+ 출력에서 추가 응답 헤더가 반환되지 않을 경우 `headers` 및 `multiValueHeaders` 키가 비지정 상태일 수 있습니다.
+ `headers` 키에는 단일 값 헤더만 있습니다.
+ `multiValueHeaders` 키에는 다중 값 헤더와 단일 값 헤더가 있을 수 있습니다. `multiValueHeaders` 키를 사용하여 모든 단일 값 헤더를 포함하는 모든 추가 헤더를 지정할 수 있습니다.
+ `headers` 및 `multiValueHeaders` 모두에 대해 값을 지정한 경우, API Gateway는 이들 헤더를 단일 목록으로 병합합니다. 동일한 키-값 페어가 양쪽 모두에 지정된 경우, `multiValueHeaders`의 값만이 병합된 목록에 표시됩니다.
Lambda 프록시 통합에 대해 CORS를 활성화하려면 출력 `Access-Control-Allow-Origin:domain-name`에 `headers`을 추가해야 합니다. `domain-name`은 모든 도메인 이름에 대해 `*`일 수 있습니다. 출력 `body`는 프런트엔드에 메서드 응답 페이로드로 마샬링됩니다. `body`가 이진 BLOB인 경우 `isBase64Encoded`를 `true`으로 설정하고, **이진 미디어 유형**을 `*/*`로 구성하여 Base64로 인코딩된 문자열로 인코딩할 수 있습니다. 그렇지 않은 경우 `false`로 설정하거나 지정되지 않은 상태로 둘 수 있습니다.
**참고**
이진 지원 활성화에 대한 자세한 내용은 [API Gateway 콘솔을 사용하여 이진 지원 활성화](api-gateway-payload-encodings-configure-with-console.md) 단원을 참조하세요. Lambda 함수의 예는 [API Gateway의 Lambda 프록시 통합에서 이진 미디어 반환](lambda-proxy-binary-media.md) 단원을 참조하세요.
함수 출력의 형식이 다른 경우 API Gateway에서는 `502 Bad Gateway` 오류 응답을 반환합니다.
Node.js에서 Lambda 함수의 응답을 반환하려면 다음과 같은 명령어를 사용할 수 있습니다.
+ 성공 결과를 반환하려면 `callback(null, {"statusCode": 200, "body": "results"})`을 호출합니다.
+ 예외를 발생하려면 `callback(new Error('internal server error'))`를 호출합니다.
+ 클라이언트 측 오류의 경우(예: 필요한 파라미터가 없는 경우) `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})`를 호출하여 예외를 발생하지 않고 오류를 반환할 수 있습니다.
Node.js의 Lambda `async` 함수에서 이와 동일한 구문은 다음과 같습니다.
+ 성공 결과를 반환하려면 `return {"statusCode": 200, "body": "results"}`을 호출합니다.
+ 예외를 발생하려면 `throw new Error("internal server error")`를 호출합니다.
+ 클라이언트 측 오류의 경우(예: 필요한 파라미터가 없는 경우) `return {"statusCode": 400, "body": "Missing parameters of ..."}`를 호출하여 예외를 발생하지 않고 오류를 반환할 수 있습니다.
# AWS CLI를 사용하여 API Gateway용 Lambda 프록시 통합 설정
이 섹션에서는 AWS CLI를 사용하여 Lambda 프록시 통합으로 API를 설정하는 방법을 보여줍니다. API Gateway 콘솔을 사용하여 Lambda 프록시 통합을 통해 프록시 리소스를 구성하는 방법에 대한 자세한 내용은 [자습서: Lambda 프록시 통합을 통해 REST API 생성](api-gateway-create-api-as-simple-proxy-for-lambda.md) 단원을 참조하세요.
예를 들면 다음과 같은 샘플 Lambda 함수를 API의 백엔드로 사용합니다.
```
export const handler = async(event, context) => {
console.log('Received event:', JSON.stringify(event, null, 2));
var res ={
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
};
var greeter = 'World';
if (event.greeter && event.greeter!=="") {
greeter = event.greeter;
} else if (event.body && event.body !== "") {
var body = JSON.parse(event.body);
if (body.greeter && body.greeter !== "") {
greeter = body.greeter;
}
} else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") {
greeter = event.queryStringParameters.greeter;
} else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") {
greeter = event.multiValueHeaders.greeter.join(" and ");
} else if (event.headers && event.headers.greeter && event.headers.greeter != "") {
greeter = event.headers.greeter;
}
res.body = "Hello, " + greeter + "!";
return res
};
```
이를 [API Gateway에서 Lambda 사용자 지정 통합 설정](set-up-lambda-custom-integrations.md)의 Lambda 사용자 지정 통합 설정과 비교하여 이 Lambda 함수에 대한 입력을 요청 파라미터 및 본문으로 표현할 수 있습니다. 클라이언트가 동일한 입력 데이터를 전달하도록 허용하는 더 많은 위도가 있습니다. 여기에서 클라이언트는 greeter의 이름을 쿼리 문자열 파라미터, 헤더 또는 본문 속성으로 전달할 수 있습니다. 함수는 Lambda 사용자 지정 통합도 지원합니다. API 설정은 더 간단합니다. 메서드 응답 또는 통합 응답은 전혀 구성하지 않습니다.
**AWS CLI를 사용하여 Lambda 프록시 통합 설정**
1. 다음 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 명령을 사용하면 API를 생성할 수 있습니다.
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
출력은 다음과 같습니다.
```
{
"name": "HelloWorldProxy (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
이 예제에서는 API `id`(`te6si5ach7`)와 `rootResourceId`(`krznpq9xpg`)를 사용합니다.
1. 다음 [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) 명령을 사용하면 `/greeting`의 API Gateway [리소스](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)를 생성할 수 있습니다.
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part {proxy+}
```
출력은 다음과 같습니다.
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
다음 단계에서는 `{proxy+}` 리소스의 `id` 값(`2jf6xt`)을 사용하여 `/{proxy+}` 리소스에 대한 메서드를 생성합니다.
1. 다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)를 사용하면 `ANY /{proxy+}`의 `ANY` 메서드 요청을 생성할 수 있습니다.
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--authorization-type "NONE"
```
출력은 다음과 같습니다.
```
{
"apiKeyRequired": false,
"httpMethod": "ANY",
"authorizationType": "NONE"
}
```
이 API 메서드를 통해 클라이언트는 백엔드에서 Lambda 함수의 인사를 수신 또는 발신할 수 있습니다.
1. 다음 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 명령을 사용하면 `HelloWorld`라는 Lambda 함수와 `ANY /{proxy+}` 메서드의 통합을 설정할 수 있습니다. 이 함수는 `"Hello, {name}!"` 파라미터가 제공되면 `greeter`이라는 메시지로, 쿼리 문자열 파라미터가 설정되어 있지 않으면 `"Hello, World!"`라는 메시지로 요청에 응답합니다.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--type AWS_PROXY \
--integration-http-method POST \
--uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
**중요**
Lambda 통합의 경우에는 [함수 호출을 위한 Lambda 서비스 작업의 사양](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html)에 따라 통합 요청에 대해 `POST`의 HTTP 메서드를 사용해야 합니다. `apigAwsProxyRole`의 IAM 역할에는 `apigateway` 서비스가 Lambda 함수를 호출하도록 허용하는 정책이 있어야 합니다. IAM 권한에 대한 자세한 내용은 [API 호출을 위한 API Gateway 권한 모델](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api) 단원을 참조하세요.
출력은 다음과 같습니다.
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:1234567890:function:HelloWorld/invocations",
"httpMethod": "POST",
"cacheNamespace": "vvom7n",
"credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole",
"type": "AWS_PROXY"
}
```
`credentials`에 IAM 역할을 제공하는 대신 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 명령을 사용하여 리소스 기반 권한을 추가할 수 있습니다. 이 작업은 API Gateway 콘솔이 수행합니다.
1. 다음 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 명령을 사용하면 API를 `test` 스테이지에 배포할 수 있습니다.
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. 터미널에서 다음 cURL 명령을 사용하여 API를 테스트합니다.
`?greeter=jane`이라는 쿼리 문자열 파라미터와 함께 API를 호출:
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane'
```
`greeter:jane`이라는 헤더 파라미터와 함께 API를 호출:
```
curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-H 'greeter: jane'
```
`{"greeter":"jane"}`이라는 본문과 함께 API를 호출:
```
curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-d '{ "greeter": "jane" }'
```
이 모든 경우에 출력되는 것은 다음과 같은 응답 본문이 있는 200 응답입니다.
```
Hello, jane!
```
# OpenAPI 정의와 Lambda 프록시 통합을 사용하여 프록시 리소스 설정
Lambda 프록시 통합 유형을 사용하여 프록시 리소스를 설정하려면 복잡한 경로 파라미터(예: `/parent/{proxy+}`)를 사용하여 API 리소스를 생성한 후 이 리소스를 `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource` 메서드의 Lambda 함수 백엔드(예: `ANY`)와 통합합니다. 복잡한 경로 파라미터는 API 리소스 경로의 끝에 와야 합니다. 비 프록시 리소스를 사용할 때와 마찬가지로 API Gateway 콘솔을 사용하거나 OpenAPI 정의 파일을 가져오거나 API Gateway REST API를 직접 호출하여 프록시 리소스를 설정할 수 있습니다.
다음 OpenAPI API 정의 파일은 `SimpleLambda4ProxyResource`라는 Lambda 함수에 통합된 프록시 리소스를 포함하는 API의 예를 보여줍니다.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
},
"servers": [
{
"url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/testStage"
}
}
}
]
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"host": "gy415nuibc.execute-api.us-east-1.amazonaws.com",
"basePath": "/testStage",
"schemes": [
"https"
],
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
}
}
```
------
Lambda 프록시 통합을 사용하여 API Gateway에서는 런타임에 수신 요청을 Lambda 함수의 입력 `event` 파라미터에 매핑합니다. 입력에는 요청 메서드, 경로, 헤더, 쿼리 문자열 파라미터, 페이로드, 연결된 컨텍스트, 정의된 단계 변수 등이 포함됩니다. 입력 형식에 대한 설명은 [프록시 통합에 대한 Lambda 함수의 입력 형식](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) 단원을 참조하세요. API Gateway에서 Lambda 출력을 HTTP 응답에 성공적으로 매핑하도록 하려면 Lambda 함수에서 [프록시 통합에 대한 Lambda 함수의 출력 형식](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format)에 설명된 형식으로 결과를 출력해야 합니다.
`ANY` 메서드를 통한 프록시 리소스의 Lambda 프록시 통합에서는 단일 백엔드 Lambda 함수가 프록시 리소스를 통해 모든 요청에 대한 이벤트 핸들러 역할을 합니다. 예를 들어 트래픽 패턴을 기록하려면 프록시 리소스에 대한 URL 경로에 `/state/city/street/house`를 포함하는 요청을 제출하여 모바일 디바이스에서 시/도, 시, 거리, 빌딩 등 위치 정보를 전송하도록 할 수 있습니다. 그러면 백엔드 Lambda 함수에서 URL 경로를 구문 분석한 다음 위치 튜플을 DynamoDB 테이블에 삽입할 수 있습니다.
# API Gateway에서 Lambda 사용자 지정 통합 설정
Lambda 사용자 지정, 비프록시, 통합을 설정하는 방법을 보여주기 위해 API Gateway API를 만들어 Lambda 함수를 호출할 `GET /greeting?greeter={name}` 메서드를 공개합니다. 다음 예시 Lambda 함수 중 하나를 API에 사용하십시오.
다음 예시 Lambda 함수 중 하나를 사용하십시오.
------
#### [ Node.js ]
```
'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
var times = ['morning', 'afternoon', 'evening', 'night', 'day'];
export const handler = async(event) => {
console.log(event);
// Parse the input for the name, city, time and day property values
let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name;
let city = event.city === undefined ? 'World' : event.city;
let time = times.indexOf(event.time)<0 ? 'day' : event.time;
let day = days.indexOf(event.day)<0 ? null : event.day;
// Generate a greeting
let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. ';
if (day) greeting += 'Happy ' + day + '!';
// Log the greeting to CloudWatch
console.log('Hello: ', greeting);
// Return a greeting to the caller
return greeting;
};
```
------
#### [ Python ]
```
import json
def lambda_handler(event, context):
print(event)
res = {
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
}
if event['greeter'] == "":
res['body'] = "Hello, World"
elif (event['greeter']):
res['body'] = "Hello, " + event['greeter'] + "!"
else:
raise Exception('Missing the required greeter parameter.')
return res
```
------
이 함수는 `"Hello, {name}!"` 파라미터 값이 비어 있지 않은 문자열인 경우 `greeter`이라는 메시지로 응답합니다. `"Hello, World!"` 값이 빈 문자열이면 `greeter`라는 메시지를 반환합니다. 수신 요청에 greeter 파라미터가 설정되지 않은 경우 함수는 `"Missing the required greeter parameter."`라는 오류 메시지를 반환합니다. 이 함수의 이름을 `HelloWorld`로 지정합니다.
Lambda 콘솔에서 또는 AWS CLI를 사용하여 이를 생성할 수 있습니다. 이 단원에서는 다음 ARN을 사용하여 이 함수를 참조합니다.
```
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld
```
백엔드에 설정된 Lambda 함수를 사용하여 API를 설정하는 단계로 이동합니다.
**AWS CLI를 사용하여 Lambda 사용자 지정 통합 설정**
1. 다음 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 명령을 사용하면 API를 생성할 수 있습니다.
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
출력은 다음과 같습니다.
```
{
"name": "HelloWorld (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
이 예제에서는 API `id`(`te6si5ach7`)와 `rootResourceId`(`krznpq9xpg`)를 사용합니다.
1. 다음 [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) 명령을 사용하면 `/greeting`의 API Gateway [리소스](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)를 생성할 수 있습니다.
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part greeting
```
출력은 다음과 같습니다.
```
{
"path": "/greeting",
"pathPart": "greeting",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
다음 단계에서는 `greeting` 리소스의 `id` 값(`2jf6xt`)을 사용하여 `/greeting` 리소스에 대한 메서드를 생성합니다.
1. 다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령을 사용하면 `GET /greeting?greeter={name}`의 API 메서드 요청을 생성할 수 있습니다.
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.greeter=false
```
출력은 다음과 같습니다.
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.querystring.greeter": false
}
}
```
이 API 메서드를 통해 클라이언트는 백엔드에서 Lambda 함수의 인사를 수신할 수 있습니다. `greeter` 파라미터는 선택 사항인데, 그 이유는 백엔드가 익명 호출자 또는 자기 동일 호출자를 처리해야 하기 때문입니다.
1. 다음 [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) 명령을 사용하면 `GET /greeting?greeter={name}`의 메서드 요청에 대한 `200 OK` 응답을 설정할 수 있습니다.
```
aws apigateway put-method-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200
```
1. 다음 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 명령을 사용하면 `HelloWorld`라는 Lambda 함수와 `GET /greeting?greeter={name}` 메서드의 통합을 설정할 수 있습니다. 이 함수는 `"Hello, {name}!"` 파라미터가 제공되면 `greeter`이라는 메시지로, 쿼리 문자열 파라미터가 설정되어 있지 않으면 `"Hello, World!"`라는 메시지로 요청에 응답합니다.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--type AWS \
--integration-http-method POST \
--uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \
--request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
여기에 제공된 매핑 템플릿은 `greeter` 쿼리 문자열 파라미터를 JSON 페이로드의 `greeter` 속성으로 변환합니다. 이것이 필요한 이유는 Lambda 함수에 대한 입력은 본문에 표시되어야 하기 때문입니다.
**중요**
Lambda 통합의 경우에는 [함수 호출을 위한 Lambda 서비스 작업의 사양](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html)에 따라 통합 요청에 대해 `POST`의 HTTP 메서드를 사용해야 합니다. `uri` 파라미터는 함수 호출 작업의 ARN입니다.
출력은 다음과 같습니다.
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\"greeter\":\"$input.params('greeter')\"}"
},
"cacheNamespace": "krznpq9xpg",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"type": "AWS"
}
```
`apigAwsProxyRole`의 IAM 역할에는 `apigateway` 서비스가 Lambda 함수를 호출하도록 허용하는 정책이 있어야 합니다. `credentials`에 IAM 역할을 제공하는 대신 [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) 명령을 호출하여 리소스 기반 권한을 추가할 수 있습니다. API Gateway 콘솔은 이 방식으로 권한을 추가합니다.
1. 다음 [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html) 명령을 사용하면 Lambda 함수 출력을 `200 OK` 메서드 응답으로 클라이언트에 전달하도록 통합 응답을 설정할 수 있습니다.
```
aws apigateway put-integration-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
빈 문자열에 선택 패턴을 설정하면 `200 OK` 응답이 기본값입니다.
출력은 다음과 같습니다.
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
1. 다음 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 명령을 사용하면 API를 `test` 스테이지에 배포할 수 있습니다.
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. 터미널에서 다음 cURL 명령을 사용하여 API를 테스트합니다.
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \
-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751'
```
# 백엔드 Lambda 함수의 비동기 호출 설정
Lambda 비프록시(사용자 지정)에서, 백엔드 Lambda 함수는 기본적으로 동기적으로 호출됩니다. 이 동작은 대부분의 REST API 작업에 적합합니다. 그러나 일부 애플리케이션은 일반적으로 별도의 백엔드 구성 요소에 의해 (배치 작업 또는 장기 지연 작업으로) 비동기적으로 작업을 수행해야 합니다. 이 경우 백엔드 Lambda 함수는 비동기적으로 호출되며 프런트엔드 REST API 메서드가 결과를 반환하지 않습니다.
[Lambda 호출 유형](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html)을 `'Event'`로 지정하여 Lambda 함수를 Lambda 비프록시 통합이 비동기적으로 호출되도록 구성할 수 있습니다. 구성 방법은 다음과 같습니다.
## API Gateway 콘솔에서 Lambda 비동기 호출 구성
모든 호출이 비동기식 인 경우:
+ **통합 요청**에서 정적 값이 `'Event'`인 `X-Amz-Invocation-Type` 헤더를 추가합니다.
호출이 비동기식인지 동기식인지 여부를 클라이언트가 결정하려면 다음을 수행하세요.
1. **메서드 요청**에서 `InvocationType` 헤더를 추가합니다.
1. **통합 요청**에서 매핑 표현식이 `method.request.header.InvocationType`인 `X-Amz-Invocation-Type` 헤더를 추가합니다.
1. 클라이언트는 API 요청에 비동기식 호출의 경우 `InvocationType: Event` 헤더를, 동기식 호출의 경우 `InvocationType: RequestResponse` 헤더를 포함할 수 있습니다.
## OpenAway를 사용하여 Lambda 비동기 호출 구성
모든 호출이 비동기식 인 경우:
+ **x-amazon-apigateway-integration** 섹션에 `X-Amz-Invocation-Type` 헤더를 추가합니다.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "'Event'"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
호출이 비동기식인지 동기식인지 여부를 클라이언트가 결정하려면 다음을 수행하세요.
1. 모든 [OpenAPI Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)(OpenAPI 경로 항목 객체)에 다음 헤더를 추가합니다.
```
"parameters" : [ {
"name" : "InvocationType",
"in" : "header",
"schema" : {
"type" : "string"
}
} ]
```
1. **x-amazon-apigateway-integration** 섹션에 `X-Amz-Invocation-Type` 헤더를 추가합니다.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
1. 클라이언트는 API 요청에 비동기식 호출의 경우 `InvocationType: Event` 헤더를, 동기식 호출의 경우 `InvocationType: RequestResponse` 헤더를 포함할 수 있습니다.
## CloudFormation을 사용하여 Lambda 비동기 간접 호출을 구성합니다.
다음 CloudFormation 템플릿은 비동기 호출을 위해 `AWS::ApiGateway::Method`를 구성하는 방법을 보여줍니다.
모든 호출이 비동기식 인 경우:
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: "'Event'"
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
호출이 비동기식인지 동기식인지 여부를 클라이언트가 결정하려면 다음을 수행하세요.
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
RequestParameters:
method.request.header.InvocationType: false
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
클라이언트는 API 요청에 비동기식 호출의 경우 `InvocationType: Event` 헤더를, 동기식 호출의 경우 `InvocationType: RequestResponse` 헤더를 포함할 수 있습니다.
# API Gateway에서 Lambda 오류 처리
Lambda 사용자 지정 통합의 경우에는 Lambda가 통합 응답에서 반환한 오류를 클라이언트에 대한 표준 HTTP 오류 응답으로 매핑해야 합니다. 그렇게 하지 않으면 Lambda 오류는 기본적으로 API 사용자가 직관적으로 이해하기 어려운 `200 OK` 응답으로 반환됩니다.
Lambda가 반환할 수 있는 오류 유형은 표준 오류와 사용자 지정 오류, 두 가지입니다. API에서 이 두 가지 오류를 다르게 처리해야 합니다.
Lambda 프록시 통합의 경우, Lambda는 다음 형식의 출력을 반환해야 합니다.
```
{
"isBase64Encoded" : "boolean",
"statusCode": "number",
"headers": { ... },
"body": "JSON string"
}
```
이 출력에서 `statusCode`는 일반적으로 클라이언트 오류의 경우 `4XX`, 서버 오류의 경우 `5XX`입니다. API Gateway는 지정된 `statusCode`에 따라 Lambda 오류를 HTTP 오류 응답에 매핑함으로써 이러한 오류를 처리합니다. API Gateway에서 클라이언트에 대한 응답의 일부로 오류 유형(예: `InvalidParameterException`)을 전달하려면 Lambda 함수가 `"X-Amzn-ErrorType":"InvalidParameterException"` 속성에 헤더(예: `headers`)를 포함해야 합니다.
**Topics**
+ [API Gateway에서 표준 Lambda 오류 처리](#handle-standard-errors-in-lambda-integration)
+ [API Gateway에서 사용자 지정 Lambda 오류 처리](#handle-custom-errors-in-lambda-integration)
## API Gateway에서 표준 Lambda 오류 처리
표준 AWS Lambda의 오류 형식은 다음과 같습니다.
```
{
"errorMessage": "string",
"errorType": "string",
"stackTrace": [
"string",
...
]
}
```
여기서 `errorMessage`는 오류의 문자열 표현식입니다. `errorType`은 언어 종속적 오류 또는 예외 유형입니다. `stackTrace`는 문자열 표현식 목록으로, 오류를 유발하는 스택 추적을 보여 줍니다.
예를 들어 다음과 같은 JavaScript(Node.js) Lambda 함수를 생각해 보세요.
```
export const handler = function(event, context, callback) {
callback(new Error("Malformed input ..."));
};
```
이 함수는 오류 메시지 `Malformed input ...`이 포함된 다음과 같은 표준 Lambda 오류를 반환합니다.
```
{
"errorMessage": "Malformed input ...",
"errorType": "Error",
"stackTrace": [
"export const handler (/var/task/index.js:3:14)"
]
}
```
마찬가지로 다음과 같은 Python Lambda 함수를 생각해 보세요. 동일한 `Exception` 오류 메시지와 함께 `Malformed input ...`을 야기하는 함수입니다.
```
def lambda_handler(event, context):
raise Exception('Malformed input ...')
```
이 함수는 다음과 같은 표준 Lambda 오류를 반환합니다.
```
{
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"lambda_handler",
"raise Exception('Malformed input ...')"
]
],
"errorType": "Exception",
"errorMessage": "Malformed input ..."
}
```
`errorType` 및 `stackTrace` 속성 값은 언어 종속적입니다. 또한 이 표준 오류는 `Error` 객체의 확장이거나 `Exception` 클래스의 하위 클래스인 모든 오류 객체에 적용됩니다.
표준 Lambda 오류를 메서드 응답에 매핑하려면, 먼저 주어진 Lambda 오류의 HTTP 상태 코드를 결정해야 합니다. 그런 다음 주어진 HTTP 상태 코드와 연결된 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)의 `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` 속성에서 정규 표현식 패턴을 설정합니다. API Gateway 콘솔에서 이 `selectionPattern`은 각 통합 응답 아래의 **통합 응답** 섹션에 **Lambda 오류 Regex**로 표시됩니다.
**참고**
API Gateway는 응답 매핑을 위해서 Java 패턴 스타일 정규식을 사용합니다. 자세한 내용은 Oracle 설명서의 [패턴 ](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) 단원을 참조하세요
예를 들어, 다음 [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)를 사용하여 새 `selectionPattern` 표현식을 설정합니다.
```
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2
```
[메서드 응답](api-gateway-method-settings-method-response.md#setup-method-response-status-code)에 해당하는 오류 코드(`400`)도 설정해야 합니다. 그렇지 않으면 API Gateway는 실행 시간에 잘못된 구성 오류 응답을 내보냅니다.
**참고**
실행 시간에 API Gateway는 Lambda 오류의 `errorMessage`를 메시지를 `selectionPattern` 속성의 정규식 패턴과 비교합니다. 양쪽이 일치하면 API Gateway는 Lambda 오류를 해당 HTTP 상태 코드의 HTTP 응답으로 반환합니다. 일치하지 않으면 API Gateway는 오류를 기본 응답으로 반환하고, 만일 기본 응답이 구성되어 있지 않으면 잘못된 구성 예외로 내보냅니다.
지정된 응답에 대해 `selectionPattern` 값을 `.*`로 설정하면 이 응답이 기본 응답으로 다시 설정됩니다. 이는 해당 선택 패턴이 null(즉. 지정되지 않은 오류 메시지)을 포함하는 모든 오류 메시지와 일치하기 때문입니다. 그 결과로 나타나는 매핑은 기본 매핑을 무시합니다. `.+`를 선택 패턴으로 사용하여 응답을 필터링하는 경우 응답이 일치하지 않을 수 있음을 인지하는 것이 좋습니다. 줄바꿈('`\n`) 문자를 포함하는 응답과 일치하지 않을 수 있습니다.
`selectionPattern`를 사용하여 기존의 AWS CLI 값을 업데이트하려면 [integrationresponse:update](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) 작업을 호출하여 `/selectionPattern` 경로 값을 `Malformed*` 패턴의 지정된 regex 표현식으로 바꿉니다.
API Gateway 콘솔을 사용하여 `selectionPattern` 표현식을 설정하려면, 지정된 HTTP 상태 코드의 통합 응답을 설정하거나 업데이트할 때 **Lambda 오류 Regex** 텍스트 상자에 원하는 표현식을 입력합니다.
## API Gateway에서 사용자 지정 Lambda 오류 처리
AWS Lambda에서는 사용자 지정 오류 객체를 앞 단원에서 다룬 표준 오류 대신 JSON 문자열로 반환할 수 있습니다. 유효한 모든 JSON 객체를 오류로 사용할 수 있습니다. 예를 들어 다음 JavaScript(Node.js) Lambda 함수는 사용자 지정 오류를 반환합니다.
```
export const handler = (event, context, callback) => {
...
// Error caught here:
var myErrorObj = {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
callback(JSON.stringify(myErrorObj));
};
```
`myErrorObj`을 호출하여 함수를 종료하려면 먼저 `callback` 객체를 JSON 문자열로 변환해야 합니다. 그렇지 않으면 `myErrorObj`가 `"[object Object]"`의 문자열로 반환됩니다. API 메서드가 앞의 Lambda 함수와 통합되면 API Gateway는 다음과 같은 페이로드의 통합 응답을 받습니다.
```
{
"errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}
```
통합 응답과 마찬가지로 이 오류 응답을 그대로 메서드 응답으로 전달할 수 있습니다. 아니면 매핑 템플릿을 사용하여 페이로드를 다른 형식으로 변환할 수도 있습니다. 예를 들어, `500` 상태 코드의 메서드 응답이라면 다음과 같은 본문 매핑 템플릿을 고려해 보세요.
```
{
errorMessage: $input.path('$.errorMessage');
}
```
이 템플릿은 사용자 지정 오류 JSON 문자열이 포함된 통합 응답 본문을 다음과 같은 메서드 응답 본문으로 변환합니다. 이 메서드 응답 본문에는 사용자 지정 오류 JSON 객체가 들어 있습니다.
```
{
"errorMessage" : {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
};
```
API 요구 사항에 따라 사용자 지정 오류 속성 중 일부 또는 전부를 메서드 응답 헤더 파라미터로 전달해야 할 수 있습니다. 그러려면 통합 응답 본문의 사용자 지정 오류 매핑을 메서드 응답 헤더에 적용하면 됩니다.
예를 들어, 다음 OpenAPI 확장은 각각 `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` 및 `errorMessage.trace` 속성에서 `error_type`, `error_status`, `error_trace_function` 및 `error_trace` 헤더로 매핑을 정의합니다.
```
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function",
"method.response.header.error_status": "integration.response.body.errorMessage.httpStatus",
"method.response.header.error_type": "integration.response.body.errorMessage.errorType",
"method.response.header.error_trace": "integration.response.body.errorMessage.trace"
},
...
}
}
}
```
API Gateway는 실행 시간에 헤더 매핑을 수행할 때 `integration.response.body` 파라미터를 역직렬화합니다. 그러나 이런 역직렬화는 Lambda 사용자 지정 오류 응답의 본문-헤더 매핑에만 적용되며, `$input.body`를 사용하는 본문-본문 매핑에는 적용되지 않습니다. 이러한 사용자 지정 오류의 본문-헤더 매핑을 사용할 경우, 클라이언트가 받는 메서드 응답에 다음 헤더가 포함되어 있습니다. 단, 메서드 요청에 `error_status`, `error_trace`, `error_trace_function`, `error_type` 헤더가 선언되어 있어야 합니다.
```
"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"
```
통합 응답 본문의 `errorMessage.trace` 속성은 복잡한 속성입니다. `error_trace` 헤더에 JSON 문자열로 매핑됩니다.
# API Gateway의 REST API에 대한 HTTP 통합
HTTP 프록시 통합 또는 HTTP 사용자 지정 통합을 사용하여 API 메서드를 HTTP 엔드포인트와 통합할 수 있습니다.
API Gateway는 80, 443, 1024-65535 엔드포인트 포트를 지원합니다.
프록시 통합을 사용하면 설정이 간단합니다. 콘텐츠 인코딩 또는 캐싱에 관심이 없다면 백엔드 요구 사항에 따라 HTTP 메서드 및 HTTP 엔드포인트 URI를 설정하기만 하면 됩니다.
사용자 지정 통합은 설정이 이보다 복잡합니다. 프록시 통합 설정 단계 외에도 수신 요청 데이터가 통합 요청에 매핑되는 방식과 그 결과로 얻는 통합 응답 데이터가 메서드 응답에 매핑되는 방식을 지정해야 합니다.
**Topics**
+ [API Gateway에서 HTTP 프록시 통합 설정](#api-gateway-set-up-http-proxy-integration-on-proxy-resource)
+ [API Gateway에서 HTTP 사용자 지정 통합 설정](#set-up-http-custom-integrations)
## API Gateway에서 HTTP 프록시 통합 설정
HTTP 프록시 통합 유형을 사용하여 프록시 리소스를 설정하려면 복잡한 경로 파라미터(예: `/parent/{proxy+}`)를 사용하여 API 리소스를 생성한 후 이 리소스를 `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}` 메서드의 HTTP 백엔드 엔드포인트(예: `ANY`)와 통합합니다. 복잡한 경로 파라미터는 리소스 경로의 끝에 와야 합니다.
비 프록시 리소스를 사용할 때와 마찬가지로 API Gateway 콘솔을 사용하거나, OpenAPI 정의 파일을 가져오거나, API Gateway REST API를 직접 호출하여 HTTP 프록시 통합을 통해 프록시 리소스를 설정할 수 있습니다. API Gateway 콘솔을 사용하여 HTTP 프록시 통합을 통해 프록시 리소스를 구성하는 방법에 대한 자세한 내용은 [자습서: HTTP 프록시 통합을 통해 REST API 생성](api-gateway-create-api-as-simple-proxy-for-http.md) 단원을 참조하세요.
다음 OpenAPI 정의 파일은 [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) 웹사이트에 통합된 프록시 리소스를 포함하는 API의 예를 보여줍니다.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T23:19:28Z",
"title": "PetStoreWithProxyResource"
},
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.proxy": "method.request.path.proxy"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"cacheNamespace": "rbftud",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "http_proxy"
}
}
}
},
"servers": [
{
"url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
]
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-12T23:19:28Z",
"title": "PetStoreWithProxyResource"
},
"host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.proxy": "method.request.path.proxy"
},
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"cacheNamespace": "rbftud",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "http_proxy"
}
}
}
}
}
```
------
이 예에서 캐시 키는 프록시 리소스의 `method.request.path.proxy` 경로 파라미터에 선언됩니다. 이는 API Gateway 콘솔을 사용하여 API를 생성할 때의 기본 설정입니다. API의 기본 경로(`/test`, 단계에 해당함)는 웹사이트의 PetStore 페이지(`/petstore`)에 매핑됩니다. 단일 통합 요청으로 API의 복잡한 경로 변수와 완전 포착(catch-all) `ANY` 메서드를 사용하여 전체 PetStore 웹사이트를 미러링합니다. 다음 예에서는 이 미러링을 보여줍니다.
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `pets`로 설정**
프런트엔드에서 시작되는 메서드 요청:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
```
백엔드로 전송되는 통합 요청:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
```
`ANY` 메서드와 프록시 리소스의 런타임 인스턴스가 모두 유효합니다. 이 호출은 백엔드에서 반환되는 반려 동물의 첫 번째 배치를 포함하는 페이로드와 함께 `200 OK` 응답을 반환합니다.
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `pets?type=dog`로 설정**
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
```
백엔드로 전송되는 통합 요청:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
```
`ANY` 메서드와 프록시 리소스의 런타임 인스턴스가 모두 유효합니다. 이 호출은 백엔드에서 반환되는 지정된 개의 첫 번째 배치를 포함하는 페이로드와 함께 `200 OK` 응답을 반환합니다.
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `pets/{petId}`로 설정**
프런트엔드에서 시작되는 메서드 요청:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
```
백엔드로 전송되는 통합 요청:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
```
`ANY` 메서드와 프록시 리소스의 런타임 인스턴스가 모두 유효합니다. 이 호출은 백엔드에서 반환되는 지정된 반려 동물을 포함하는 페이로드와 함께 `200 OK` 응답을 반환합니다.
+ **`ANY`를 `POST`으로 설정하고 `{proxy+}`를 `pets`로 설정**
프런트엔드에서 시작되는 메서드 요청:
```
POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...
{
"type" : "dog",
"price" : 1001.00
}
```
백엔드로 전송되는 통합 요청:
```
POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
Content-Type: application/json
Content-Length: ...
{
"type" : "dog",
"price" : 1001.00
}
```
`ANY` 메서드와 프록시 리소스의 런타임 인스턴스가 모두 유효합니다. 이 호출은 백엔드에서 반환되는 새로 생성된 반려 동물을 포함하는 페이로드와 함께 `200 OK` 응답을 반환합니다.
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `pets/cat`로 설정**
프런트엔드에서 시작되는 메서드 요청:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
```
백엔드로 전송되는 통합 요청:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
```
프록시 리소스 경로의 런타임 인스턴스가 백엔드 엔드포인트와 일치하지 않고 결과 요청이 잘못되었습니다. 따라서 `400 Bad Request` 응답이 다음 오류 메시지와 함께 반환됩니다.
```
{
"errors": [
{
"key": "Pet2.type",
"message": "Missing required field"
},
{
"key": "Pet2.price",
"message": "Missing required field"
}
]
}
```
+ **`ANY`를 `GET`으로 설정하고 `{proxy+}`를 `null`로 설정**
프런트엔드에서 시작되는 메서드 요청:
```
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
```
백엔드로 전송되는 통합 요청:
```
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
타겟 리소스는 프록시 리소스의 상위이지만, `ANY` 메서드의 런타임 인스턴스가 해당 리소스의 API에 정의되어 있지 않습니다. 따라서 이 `GET` 요청은 API Gateway에서 반환되는 `403 Forbidden` 오류 메시지와 함께 `Missing Authentication Token` 응답을 반환합니다. API가 상위 리소스(`ANY`)에 `GET` 또는 `/` 메서드를 공개할 경우 이 호출은 백엔드에서 반환되는 `404 Not Found` 메시지와 함께 `Cannot GET /petstore` 응답을 반환합니다.
클라이언트 요청에 대해 타겟 엔드포인트 URL이 잘못되거나 HTTP 동사가 유효하지만 지원되지 않는 경우 백엔드에서 `404 Not Found` 응답을 반환합니다. 지원되지 않는 HTTP 메서드의 경우 `403 Forbidden` 응답이 반환됩니다.
## API Gateway에서 HTTP 사용자 지정 통합 설정
HTTP 사용자 지정 통합(다른 명칭: 비프록시 통합)에서는 API 메서드와 API 통합 간에 전달할 데이터와 그 데이터를 전달하는 방식을 제어할 수 있는 권한이 더 많습니다. 이러한 제어는 데이터 매핑을 통해 할 수 있습니다.
메서드 요청 설정의 일부로 [메서드](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 리소스에 대한 [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#requestParameters)속성을 설정입니다. 이를 통해 클라이언트로부터 프로비저닝되는 메서드 요청 파라미터 중 어떤 것이 백엔드로 디스패치되기 전에 통합 요청 파라미터 또는 적용 가능한 본문 속성에 매핑되도록 할지 선언합니다. 그런 다음 통합 요청 설정의 일부로 해당 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스의 [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestParameters) 속성을 설정하여 파라미터 대 파라미터 매핑을 지정합니다. 또한 [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestTemplates) 속성을 설정하여 지원되는 각 콘텐츠 유형에 매핑 템플릿을 지정합니다. 매핑 템플릿은 메서드 요청 파라미터 또는 본문을 통합 요청 본문으로 매핑합니다.
마찬가지로 메서드 응답 설정의 일부로 [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) 리소스에 대한 [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) 속성을 설정합니다. 이를 통해 클라이언트로 디스패치될 메서드 응답 파라미터 중 어떤 것이 백엔드로부터 반환된 통합 응답 파라미터 또는 적용 가능한 특정 본문 속성으로부터 매핑되도록 할지 선언합니다. 그런 다음 백엔드의 응답을 기반으로 통합 응답을 선택하도록 [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)을 설정합니다. 비프록시 HTTP 통합의 경우 이는 정규식입니다. 예를 들어 모든 2xx HTTP 응답 상태 코드를 HTTP 엔드포인트에서 이 출력 매핑으로 매핑하려면 `2\d{2}`를 사용합니다.
**참고**
API Gateway는 응답 매핑을 위해서 Java 패턴 스타일 정규식을 사용합니다. 자세한 내용은 Oracle 설명서의 [패턴 ](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) 단원을 참조하세요
그런 다음 통합 응답 설정의 일부로 해당 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스에 대한 [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseParameters) 속성을 설정하여 파라미터 대 파라미터 매핑을 지정합니다. 또한 [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseTemplates) 맵을 설정하여 지원되는 각 콘텐츠 유형에 매핑 템플릿을 지정합니다. 매핑 템플릿은 통합 응답 파라미터 또는 통합 응답 본문 속성을 메서드 응답 본문으로 매핑합니다.
매핑 템플릿 설정에 대한 자세한 내용은 [API Gateway에서 REST API의 데이터 변환](rest-api-data-transformations.md) 단원을 참조하세요.
# API Gateway에서 프록시 통합에 대한 통합 응답 스트리밍
API Gateway가 통합 응답을 반환하는 방법을 제어하도록 프록시 통합을 구성할 수 있습니다. 기본적으로 API Gateway는 전송을 시작하기 전에 전체 응답을 수신할 때까지 기다립니다. 그러나 통합의 응답 전송 모드를 `STREAM`으로 설정하면 API Gateway는 클라이언트로 전송하기 전에 응답이 완전히 계산될 때까지 기다리지 않습니다. 응답 스트리밍은 모든 REST API 엔드포인트 유형에서 작동합니다.
다음 사용 사례에 응답 스트리밍을 사용합니다.
+ 챗봇과 같은 생성형 AI 애플리케이션의 time-to-first-byte(TTFB)를 줄입니다.
+ S3 미리 서명된 URL을 사용하지 않고 대용량 이미지, 비디오 또는 음악 파일을 스트리밍합니다.
+ 서버 전송 이벤트(SSE)와 같은 증분 진행 상황을 보고하면서 장기 실행 작업을 수행합니다.
+ API Gateway의 10MB 응답 페이로드 제한을 초과했습니다.
+ 통합 제한 시간 증가를 요청하지 않고 API Gateway의 29초 제한 시간을 초과했습니다.
+ 바이너리 미디어 유형을 구성하지 않고 바이너리 페이로드를 수신합니다.
## 응답 페이로드 스트리밍 고려 사항
다음 고려 사항은 응답 페이로드 스트리밍 사용에 영향을 미칠 수 있습니다.
+ `HTTP_PROXY` 또는 `AWS_PROXY` 통합 유형에만 응답 페이로드 스트리밍을 사용할 수 있습니다. 여기에는 Lambda 프록시 통합과 통합을 사용하는 프라이빗 `HTTP_PROXY` 통합이 포함됩니다.
+ 기본 전송 모드 설정은 `BUFFERED`입니다. 응답 스트리밍을 사용하려면 응답 전송 모드를 `STREAM`으로 변경해야 합니다.
+ 응답 스트리밍은 REST API에만 지원됩니다.
+ 요청 스트리밍은 지원되지 않습니다.
+ 최대 15분 동안 응답을 스트리밍할 수 있습니다.
+ 스트림에는 유휴 제한 시간이 적용됩니다. 리전 또는 프라이빗 엔드포인트의 경우 제한 시간은 5분입니다. 엣지 최적화 엔드포인트의 경우 제한 시간은 30초입니다.
+ 자체 CloudFront 배포와 함께 리전 REST API에 응답 스트리밍을 사용하는 경우 CloudFront 배포의 응답 제한 시간을 늘려 30초 이상 유휴 제한 시간을 달성할 수 있습니다. 자세한 내용은 [응답 시간 초과](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesOrigin.html#DownloadDistValuesOriginResponseTimeout)를 참조하세요.
+ 응답 전송 모드를 `STREAM`로 설정하면 API Gateway는 전체 통합 응답의 버퍼링을 요구하는 기능을 지원할 수 없습니다. 따라서 응답 스트리밍에서는 다음 기능이 지원되지 않습니다.
+ 엔드포인트 캐싱
+ 콘텐츠 인코딩입니다. 통합 응답을 압축하려면 통합에서 이 작업을 수행합니다.
+ VTL을 사용한 응답 변환
+ 각 스트리밍 응답 내에서 응답 페이로드의 처음 10MB에는 대역폭 제한이 적용되지 않습니다. 10MB를 초과하는 응답 페이로드 데이터는 2MB/s로 제한됩니다.
+ 제한 시간으로 인해 클라이언트와 API Gateway 간 또는 API Gateway와 Lambda 간의 연결이 종료되면 Lambda 함수가 계속 실행될 수 있습니다. 자세한 내용은 [Lambda 함수 제한 시간 구성](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)을 참조하세요.
+ 응답 스트리밍에는 비용이 발생합니다. 자세한 내용은 [API Gateway 요금](https://aws.amazon.com/api-gateway/pricing/)을 참조하세요.
# API Gateway에서 페이로드 응답 스트리밍과 HTTP 프록시 통합 설정
응답 페이로드 스트리밍을 설정할 때 메서드의 통합 요청에서 응답 전송 모드를 지정합니다. 통합 요청에서 이러한 설정을 구성하여 통합 응답 전후에 API Gateway가 작동하는 방식을 제어합니다. 응답 스트리밍을 사용하는 경우 통합 제한 시간을 최대 15분으로 구성할 수 있습니다.
`HTTP_PROXY` 통합과 함께 페이로드 응답 스트리밍을 사용하는 경우 API Gateway는 모든 헤더를 완전히 수신할 때까지 HTTP 응답 상태 코드 또는 HTTP 응답 헤더를 전송하지 않습니다.
## 페이로드 응답 스트리밍과 HTTP 프록시 통합 생성
다음 절차에서는 `STREAM`이 `responseTransferMode`로 설정된 새 API를 가져오는 방법을 보여 줍니다. 기존 통합 API가 있으며 `responseTransferMode`를 수정하려면 [HTTP 프록시 통합에 대한 응답 전송 모드 업데이트](#response-streaming-http-update) 섹션을 참조하세요.
------
#### [ AWS Management Console ]
**페이로드 응답 스트리밍과 HTTP 프록시 통합 생성**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. **리소스 생성**을 선택합니다.
1. **리소스 이름**에 **streaming**을 입력합니다.
1. **리소스 생성**을 선택합니다.
1. **/streaming** 리소스를 선택한 상태에서 **메서드 생성**을 선택합니다.
1. **메서드 유형**에서 **모두**를 선택합니다.
1. **통합 유형**에서 **HTTP**를 선택합니다.
1. **HTTP 프록시 통합**을 선택합니다.
1. **응답 전송 모드**에서 **스트림**을 선택합니다.
1. **HTTP 메서드**에서 메서드를 선택합니다.
1. **엔드포인트 URL**에 통합 엔드포인트를 입력합니다. 다시 스트리밍할 대용량 페이로드를 생성하는 엔드포인트를 선택해야 합니다.
1. **메서드 생성**을 선택합니다.
메서드를 생성한 후 API를 배포합니다.
**API를 배포하려면**
1. **Deploy API(API 배포)**를 선택합니다.
1. **스테이지**에서 **새 스테이지**를 선택합니다.
1. **단계 이름**에 **prod**를 입력합니다.
1. (선택 사항) **설명**에 설명을 입력합니다.
1. **배포(Deploy)**를 선택합니다.
------
#### [ AWS CLI ]
**페이로드 응답 스트리밍을 사용하여 새 API 생성**
1. 다음 Open API 파일을 복사하고 `ResponseStreamDemoSwagger.yaml`로 저장합니다. 이 파일에서 `responseTransferMode`는 `STREAM`으로 설정됩니다. 통합 엔드포인트는 `https://example.com`으로 설정되지만 대규모 페이로드를 생성하는 엔드포인트로 수정하여 다시 스트리밍하는 것이 좋습니다.
```
openapi: "3.0.1"
info:
title: "ResponseStreamingDemo"
version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
variables:
basePath:
default: "prod"
paths:
/streaming:
get:
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "https://example.com"
type: "http_proxy"
timeoutInMillis: 900000
responseTransferMode: "STREAM"
```
1. 다음 `import-rest-api` 명령을 사용하여 OpenAPI 정의를 가져옵니다.
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. 다음 `create-deployment` 명령을 사용하여 새 API를 스테이지에 배포합니다.
```
aws apigateway create-deployment \
--rest-api-id a1b2c3 \
--stage-name prod \
--region us-west-1
```
------
## HTTP 프록시 통합에 대한 응답 전송 모드 업데이트
다음 절차에서는 HTTP 프록시 통합에 대한 응답 전송 모드를 업데이트하는 방법을 보여 줍니다.
------
#### [ AWS Management Console ]
**HTTP 프록시 통합에 대한 응답 전송 모드 업데이트**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 방법을 선택합니다.
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **응답 전송 모드**에서 **스트림**을 선택합니다.
1. **저장**을 선택합니다.
메서드를 업데이트한 후 API를 배포합니다.
**API를 배포하려면**
1. **Deploy API(API 배포)**를 선택합니다.
1. **스테이지**에서 **새 스테이지**를 선택합니다.
1. **단계 이름**에 **prod**를 입력합니다.
1. (선택 사항) **설명**에 설명을 입력합니다.
1. **배포(Deploy)**를 선택합니다.
------
#### [ AWS CLI ]
다음 `update-integration` 명령은 통합의 전송 모드를 `BUFFERED`에서 `STREAM`으로 업데이트합니다. 기존 API 경우 모든 통합에 대한 응답 전송 모드는 `BUFFERED`로 설정됩니다.
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method GET \
--patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \
--region us-west-1
```
변경을 적용하려면 API를 재배포해야 합니다. 통합 제한 시간을 사용자 지정한 경우 API Gateway가 최대 5분 동안 응답을 스트리밍하므로 이 제한 시간 값이 제거됩니다.
다음 `update-integration` 명령은 통합의 전송 모드를 `STREAM`에서 `BUFFERED`로 업데이트합니다.
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method GET \
--patch-operations "op='replace',path='/responseTransferMode',value=BUFFERED" \
--region us-west-1
```
변경을 적용하려면 API를 재배포해야 합니다.
------
# API Gateway에서 페이로드 응답 스트리밍과 Lambda 프록시 통합 설정
Lambda 함수의 응답을 스트리밍하여 첫 번째 바이트까지의 시간(TTFB) 성능을 개선하고 부분 응답을 사용할 수 있게 되면 클라이언트로 다시 보낼 수 있습니다. API Gateway를 사용하려면 [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) Lambda API를 사용하여 Lambda 함수를 간접적으로 호출해야 합니다. API Gateway는 이벤트 객체를 Lambda 함수에 전달합니다. 백엔드 Lambda 함수는 수신되는 요청 데이터를 구문 분석하여 반환하는 응답을 결정합니다. API Gateway가 Lambda 출력을 스트리밍하려면 Lambda 함수가 API Gateway에 필요한 [형식](#response-transfer-mode-lambda-format)을 출력해야 합니다.
## 스트림과 버퍼링된 응답 전송 모드 간의 Lambda 프록시 통합 차이
다음 목록은 응답 스트리밍을 위한 Lambda 프록시 통합과 Lambda 프록시 통합의 차이점을 설명합니다.
+ API Gateway는 [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API를 사용하여 응답 스트리밍을 위한 Lambda 프록시 통합을 간접적으로 호출합니다. 이렇게 하면 다음과 같은 다른 URI가 생성됩니다.
```
arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations
```
이 ARN은 API 버전에 대해 다른 날짜를 사용하고 Lambda 프록시 통합과는 다른 서비스 작업을 사용합니다.
응답 스트리밍에 API Gateway 콘솔을 사용하는 경우 콘솔은 올바른 URI를 사용합니다.
+ Lambda 프록시 통합에서 API Gateway는 Lambda로부터 전체 응답을 수신한 후에만 클라이언트에 응답을 전송합니다. 응답 스트리밍을 위한 Lambda 프록시 통합에서 API Gateway는 Lambda에서 유효한 메타데이터 및 구분 기호를 수신한 후 페이로드 스트림을 시작합니다.
+ 응답 스트리밍을 위한 Lambda 프록시 통합은 프록시 통합과 동일한 입력 형식을 사용하지만 다른 출력 형식이 필요합니다.
## 응답 스트리밍을 위한 Lambda 프록시 통합 형식
API Gateway가 응답 스트리밍으로 Lambda 함수를 간접적으로 호출하는 경우 입력 형식은 프록시 통합을 위한 Lambda 함수의 입력 형식과 동일합니다. 자세한 내용은 [프록시 통합에 대한 Lambda 함수의 입력 형식](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) 섹션을 참조하세요.
Lambda가 API Gateway에 응답을 스트리밍할 때 응답은 다음 형식을 준수해야 합니다. 이 형식은 구분 기호를 사용하여 메타데이터 JSON과 원시 페이로드를 구분합니다. 이 경우 페이로드 데이터는 스트리밍 Lambda 함수에 의해 전송될 때 스트리밍됩니다.
```
{
"headers": {"headerName": "headerValue", ...},
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"cookies" : ["cookie1", "cookie2"],
"statusCode": httpStatusCode
}PAYLOAD1 | PAYLOAD2 | PAYLOAD3
```
출력에서:
+ 출력에서 추가 응답 헤더가 반환되지 않을 경우 `headers`, `multiValueHeaders`, `cookies` 및 `statusCode` 키가 비지정 상태일 수 있습니다.
+ `headers` 키에는 단일 값 헤더만 있습니다.
+ 출력에는 헤더에 `Transfer-Encoding: chunked` 또는 `Content-length: number`이 포함될 것으로 예상됩니다. 함수가 이러한 헤더 중 하나를 반환하지 않으면 API Gateway는 응답 헤더에 `Transfer-Encoding: chunked`를 추가합니다.
+ `multiValueHeaders` 키에는 다중 값 헤더와 단일 값 헤더가 있을 수 있습니다. `multiValueHeaders` 키를 사용하여 모든 단일 값 헤더를 포함하는 모든 추가 헤더를 지정할 수 있습니다.
+ `headers` 및 `multiValueHeaders` 모두에 대해 값을 지정한 경우, API Gateway는 이들 헤더를 단일 목록으로 병합합니다. 동일한 키-값 페어가 양쪽 모두에 지정된 경우, `multiValueHeaders`의 값만이 병합된 목록에 표시됩니다.
+ 메타데이터는 유효한 JSON이어야 합니다. `headers`, `multiValueHeaders`, `statusCode` 및 `cookies` 키만 지원됩니다.
+ 메타데이터 JSON 뒤에 구분 기호를 제공해야 합니다. 구분 기호는 8 Null 바이트여야 하며 스트림 데이터의 처음 16KB 내에 나타나야 합니다.
+ API Gateway에는 메서드 응답 페이로드에 대한 특정 형식이 필요하지 않습니다.
함수 URL을 사용하여 Lambda 함수를 스트리밍하는 경우 이러한 요구 사항을 충족하도록 Lambda 함수의 입력 및 출력을 수정해야 합니다.
Lambda 함수 출력이 이 형식의 요구 사항을 준수하지 않는 경우에도 API Gateway는 여전히 Lambda 함수를 간접적으로 호출할 수 있습니다. 다음 표에는 API Gateway에서 지원하는 API 통합 요청 설정과 Lambda 함수 코드의 조합이 나와 있습니다. 여기에는 버퍼링된의 응답 전송 모드에 대해 지원되는 조합이 포함됩니다.
| 응답 전송 모드 | 함수 코드가 필수 형식을 준수합니다. | Lambda API 간접 호출 | API Gateway에서 지원됨 |
| --- | --- | --- | --- |
| Stream | 예 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 예. API Gateway는 응답을 스트리밍합니다. |
| Stream | 아니요 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 아니요. API Gateway는 Lambda 함수를 간접적으로 호출하고 500 오류 응답을 반환합니다. |
| Stream | 예 | [간접 호출](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 아니요. API Gateway는이 통합 구성을 지원하지 않습니다. |
| Stream | 아니요 | [간접 호출](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 아니요. API Gateway는이 통합 구성을 지원하지 않습니다. |
| 버퍼링됨 | 예 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 아니요. API Gateway는이 통합 구성을 지원하지 않습니다. |
| 버퍼링됨 | 아니요 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 아니요. API Gateway는이 통합 구성을 지원하지 않습니다. |
| 버퍼링됨 | 예 | [간접 호출](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway는 HTTP 헤더와 상태 코드를 반환하지만 응답 본문은 반환하지 않습니다. |
| 버퍼링됨 | 아니요 | [간접 호출](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 예. 이는 Lambda 프록시 통합입니다. 자세한 내용은 [Lambda 프록시 통합](set-up-lambda-proxy-integrations.md)을 참조하세요. |
# API Gateway에서 페이로드 응답 스트리밍과 Lambda 프록시 통합 구성
응답 페이로드 스트리밍을 설정할 때 리소스의 통합 요청에서 전송 모드를 지정합니다. 통합 요청에서 이러한 설정을 구성하여 통합 응답 전후에 API Gateway가 작동하는 방식을 제어합니다.
## 응답 스트리밍을 위한 Lambda 함수 예제
Lambda 함수는 [응답 스트리밍을 위한 Lambda 프록시 통합 형식](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format)을 준수해야 합니다. 응답 스트리밍을 테스트하려면 세 가지 예제 Lambda 함수 중 하나를 사용하는 것이 좋습니다. Lambda 함수를 생성할 때 다음을 수행해야 합니다.
+ 함수에 적절한 제한 시간을 제공합니다. 응답 스트리밍에 대해 알아보려면 최소 1분의 제한 시간을 구성하는 것이 좋습니다. 프로덕션 리소스를 생성할 때 Lambda 함수 제한 시간이 전체 요청 주기를 포함하는지 확인합니다. 자세한 내용은 [Lambda 함수 제한 시간 구성](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)을 참조하세요.
+ 최신 Node.js 런타임을 사용합니다.
+ Lambda 응답 스트리밍을 사용할 수 있는 리전을 사용합니다.
------
#### [ Using HttpResponseStream.from ]
다음 코드 예제에서는 파이프라인 `awslambda.HttpResponseStream()` 메서드를 사용하지 않고 메서드를 사용하여 JSON 메타데이터 객체와 페이로드를 클라이언트로 다시 스트리밍합니다. 구분 기호를 생성할 필요가 없습니다. 자세한 내용은 [응답 스트리밍이 활성화된 Lambda 함수 작성](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html)을 참조하세요.
```
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
"statusCode": 200,
"headers": {
"x-foo": "bar"
},
"multiValueHeaders": {
"x-mv1": ["hello", "world"],
"Set-Cookie": ["c1=blue", "c2=red"]
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("First payload ");
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("Final payload");
responseStream.end();
});
```
------
#### [ Using the pipeline method ]
Lambda는 응답 스트리밍 지원 함수를 작성할 때 네이티브 Node.js 런타임이 제공하는 `awslambda.streamifyResponse()` 데코레이터와 `pipeline()` 메서드를 사용할 것을 권장합니다. 파이프라인 메서드를 사용하는 경우 구분 기호를 생성할 필요가 없습니다. Lambda가이 작업을 수행합니다. 자세한 내용은 [응답 스트리밍이 활성화된 Lambda 함수 작성](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html)을 참조하세요.
다음 코드 예제에서는 JSON 메타데이터 객체와 세 개의 페이로드를 클라이언트로 다시 스트리밍합니다.
```
import { pipeline } from 'node:stream/promises';
import { Readable } from 'node:stream';
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
statusCode: 200,
headers: {
"Content-Type": "text/plain",
"X-Custom-Header": "Example-Custom-Header"
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
const dataStream = Readable.from(async function* () {
yield "FIRST payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "SECOND payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "THIRD payload\n";
await new Promise(r => setTimeout(r, 1000));
}());
await pipeline(dataStream, responseStream);
}
);
```
------
#### [ Without using the pipeline method ]
다음 코드 예제에서는 `awslambda.HttpResponseStream()` 메서드를 사용하지 않고 JSON 메타데이터 객체와 세 개의 페이로드를 클라이언트로 다시 스트리밍합니다. `awslambda.HttpResponseStream()` 메서드가 없으면 메타데이터와 페이로드 사이에 8 Null 바이트의 구분 기호를 포함해야 합니다.
```
export const handler = awslambda.streamifyResponse(async (event, response, ctx) => {
response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}');
response.write("\x00".repeat(8)); // DELIMITER
await new Promise(r => setTimeout(r, 1000));
response.write("FIRST payload");
await new Promise(r => setTimeout(r, 1000));
response.write("SECOND payload");
await new Promise(r => setTimeout(r, 1000));
response.write("FINAL payload");
response.end();
});
```
------
## 페이로드 응답 스트리밍과 Lambda 프록시 통합 생성
다음 절차에서는 페이로드 응답 스트리밍과 Lambda 프록시 통합을 생성하는 방법을 보여 줍니다. 예제 Lambda 함수를 사용하거나 직접 생성합니다.
------
#### [ AWS Management Console ]
**페이로드 응답 스트리밍과 Lambda 프록시 통합을 생성하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. **리소스 생성**을 선택합니다.
1. **리소스 이름**에 **streaming**을 입력합니다.
1. **리소스 생성**을 선택합니다.
1. **/streaming** 리소스를 선택한 상태에서 **메서드 생성**을 선택합니다.
1. **메서드 유형**에서 **모두**를 선택합니다.
1. **통합 유형**에서 **Lambda**를 선택합니다.
1. **Lambda 프록시 통합**을 선택합니다.
1. **응답 전송 모드**에서 **스트림**을 선택합니다.
1. **Lambda 함수**에서 Lambda 함수의 이름을 선택합니다.
API Gateway 콘솔은 [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API를 사용하여 Lambda 함수를 간접적으로 호출합니다. 응답 스트리밍이 활성화된 Lambda 함수를 작성하는 것은 사용자의 책임입니다. 문제 해결 예는 [응답 스트리밍을 위한 Lambda 함수 예제](#response-streaming-lambda-example)을(를) 참조하세요.
1. **메서드 생성**을 선택합니다.
메서드를 생성한 후 API를 배포합니다.
**API를 배포하려면**
1. **Deploy API(API 배포)**를 선택합니다.
1. **스테이지**에서 **새 스테이지**를 선택합니다.
1. **단계 이름**에 **prod**를 입력합니다.
1. (선택 사항) **설명**에 설명을 입력합니다.
1. **배포(Deploy)**를 선택합니다.
------
#### [ AWS CLI ]
다음 절차에서는 `responseTransferMode`가 `STREAM`으로 설정된 새 API를 가져오는 방법을 보여 줍니다. 기존 통합 API가 있으며 `responseTransferMode`를 수정하려면 [Lambda 프록시 통합에 대한 응답 전송 모드 업데이트](#response-streaming-lambda-update) 섹션을 참조하세요.
**페이로드 응답 스트리밍을 사용하여 새 API 생성**
1. 다음 Open API 파일을 복사하고 `ResponseStreamDemoSwagger.yaml`로 저장합니다. 이 파일에서 `responseTransferMode`는 `STREAM`으로 설정되고 통합 URI는 `arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations`로 설정됩니다.
`my-function`의 함수 이름을 스트리밍 지원 함수로 바꾸고 자격 증명을 `apigateway` 서비스가 Lambda 함수를 간접적으로 호출하도록 허용하는 정책이 있는 IAM 역할로 바꿉니다.
```
openapi: "3.0.1"
info:
title: "ResponseStreamingDemo"
version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
variables:
basePath:
default: "prod"
paths:
/lambda:
get:
x-amazon-apigateway-integration:
httpMethod: "POST"
uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations"
type: "aws_proxy"
timeoutInMillis: 90000
responseTransferMode: "STREAM"
credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role"
```
자격 증명에 대한 IAM 역할을 제공하는 대신 Lambda에 대한 `add-permission` 명령을 사용하여 리소스 기반 권한을 추가할 수 있습니다.
1. 다음 `import-rest-api` 명령을 사용하여 OpenAPI 정의를 가져옵니다.
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. 다음 `create-deployment` 명령을 사용하여 새 API를 스테이지에 배포합니다.
```
aws apigateway create-deployment \
--rest-api-id a1b2c2 \
--stage-name prod \
--region us-west-1
```
------
### Lambda 프록시 통합에 대한 응답 전송 모드 업데이트
다음 절차에서는 Lambda 프록시 통합에 대한 응답 전송 모드를 업데이트하는 방법을 보여 줍니다. 응답 전송 모드를 스트리밍으로 변경할 때 응답 스트리밍 요구 사항을 준수하도록 Lambda 함수를 업데이트합니다. 예제 Lambda 함수를 사용하거나 직접 생성합니다.
------
#### [ AWS Management Console ]
**Lambda 프록시 통합에 대한 응답 전송 모드 업데이트**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 방법을 선택합니다.
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **응답 전송 모드**에서 **스트림**을 선택합니다.
1. **Lambda 함수**에서 Lambda 함수의 이름을 선택합니다.
1. **저장**을 선택합니다.
메서드를 업데이트한 후 API를 배포합니다.
**API를 배포하려면**
1. **Deploy API(API 배포)**를 선택합니다.
1. **스테이지**에서 **새 스테이지**를 선택합니다.
1. **단계 이름**에 **prod**를 입력합니다.
1. (선택 사항) **설명**에 설명을 입력합니다.
1. **배포(Deploy)**를 선택합니다.
------
#### [ AWS CLI ]
1. 스트리밍을 활성화하도록 Lambda 함수를 업데이트합니다.
1. 다음 AWS CLI 명령을 사용하여 통합의 통합 URI 및 응답 전송 모드를 업데이트합니다.
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method ANY \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \
--region us-west-1
```
1. 변경 사항을 적용하려면 API를 재배포합니다.
------
# API Gateway에서 응답 스트리밍 관련 문제 해결
다음 문제 해결 지침은 응답 스트리밍을 사용하는 API 문제를 해결하는 데 도움이 될 수 있습니다.
## 일반 문제 해결
[TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html) 또는 콘솔의 테스트 탭을 사용하여 스트림 응답을 테스트할 수 있습니다. 다음 고려 사항은 응답 스트리밍을 위한 테스트 간접 호출 사용에 영향을 미칠 수 있습니다.
+ 메서드를 테스트하면 API Gateway가 스트리밍된 응답 페이로드를 버퍼링합니다. 다음 조건 중 하나라도 충족되면 API Gateway는 버퍼링된 페이로드를 포함하는 일회성 응답을 반환합니다.
+ 요청이 완료됨
+ 35초 경과
+ 1MB 이상의 응답 페이로드가 버퍼링되었습니다.
+ 메서드가 HTTP 응답 상태와 모든 헤더를 반환하기 전에 35초 이상이 경과하면 TestInvokeMethod에서 반환된 응답 상태는 0입니다.
+ API Gateway는 실행 로그를 생성하지 않습니다.
API를 배포한 후 curl 명령을 사용하여 스트림 응답을 테스트할 수 있습니다. `-i` 옵션을 사용하여 출력에 프로토콜 응답 헤더를 포함하는 것이 좋습니다. 응답 데이터가 도착하면 보려면 curl 옵션 `--no-buffer`를 사용합니다.
## cURL 오류 해결
통합을 테스트 중이고 `curl: (18) transfer closed with outstanding read data remaining` 오류가 발생하는 경우 통합 제한 시간이 충분히 긴지 확인합니다. Lambda 함수를 사용하는 경우 Lambda 함수의 응답 제한 시간을 업데이트해야 합니다. 자세한 내용은 [Lambda 함수 제한 시간 구성](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)을 참조하세요.
## 액세스 로깅 사용 문제 해결
REST API 스테이지에 대한 액세스 로그를 사용하여 응답 스트림을 로깅하고 문제를 해결할 수 있습니다. 기존 변수 외에도 다음 액세스 로그 변수를 사용할 수 있습니다.
`$context.integration.responseTransferMode`
통합의 응답 전송 모드입니다. 이는 `BUFFERED` 또는 `STREAMED`일 수 있습니다.
`$context.integration.timeToAllHeaders`
API Gateway가 통합 연결을 설정하는 시점부터 클라이언트로부터 모든 통합 응답 헤더를 수신하는 시점까지의 시간입니다.
`$context.integration.timeToFirstContent`
API Gateway가 통합 연결을 설정하는 시점부터 첫 번째 콘텐츠 바이트를 수신하는 시점까지의 시간입니다.
`$context.integration.latency` 또는 `$context.integrationLatency`
API Gateway가 통합 연결을 설정하는 시간부터 통합 응답 스트림이 완료되는 시간까지입니다.
다음 그림은 이러한 액세스 로그 변수가 응답 스트림의 다양한 구성 요소를 나타내는 방법을 보여 줍니다.
![\[API Gateway에서 응답 스트리밍을 위한 액세스 로그 변수\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/response-streaming-figure.png)
액세스 로그에 대한 자세한 내용은 [API Gateway에서 REST API에 대한 CloudWatch 로깅 설정](set-up-logging.md) 단원을 참조하십시오. X-Ray를 사용하여 응답 스트림을 모니터링할 수도 있습니다. 자세한 내용은 [API Gateway에서 X-Ray를 사용하여 REST API에 대한 사용자 요청 추적](apigateway-xray.md) 섹션을 참조하세요.
# API Gateway의 REST API에 대한 프라이빗 통합
프라이빗 통합으로 VPC 외부 클라이언트의 액세스를 위해 Amazon VPC 내의 HTTP/HTTPS 리소스를 공개할 수 있습니다. 이렇게 하면 프라이빗 VPC 리소스에 대한 액세스가 VPC 경계를 넘어 확장됩니다. API Gateway가 지원하는 [권한 부여 방법](apigateway-control-access-to-api.md)을 사용하여 API에 대한 액세스를 제어할 수 있습니다.
프라이빗 통합을 생성하려면 먼저 VPC 링크를 생성해야 합니다. API Gateway는 REST API용 VPC 링크 V2를 지원합니다. VPC 링크 V2를 사용하면 Network Load Balancer를 사용하지 않고도 REST API를 Application Load Balancer에 연결하는 프라이빗 통합을 생성할 수 있습니다. Application Load Balancer를 사용하면 Amazon ECS 컨테이너 기반 애플리케이션 및 기타 많은 백엔드에 연결할 수 있습니다. VPC 링크 V1은 레거시 통합 유형으로 간주됩니다. API Gateway에서 지원되지만 새 VPC 링크 V1을 생성하지 않는 것이 좋습니다.
## 고려 사항
다음 고려 사항은 프라이빗 통합 사용에 영향을 미칠 수 있습니다.
+ 모든 리소스는 동일한 AWS 계정에서 소유해야 합니다. 여기에는 로드 밸런서, VPC 링크 및 REST API가 포함됩니다.
+ 기본적으로 프라이빗 통합 트래픽은 HTTP 프로토콜을 사용합니다. HTTPS를 사용하려면 `https://example.com:443/test`와 같이 보안 서버 이름이 포함된 [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)를 지정합니다.
+ 프라이빗 통합의 경우 API Gateway에서 백엔드 리소스에 대한 요청에 API 엔드포인트의 [스테이지](set-up-stages.md) 부분을 포함합니다. 예를 들어, API의 `test` 스테이지를 요청하면 API Gateway는 해당 프라이빗 통합 요청에 `test/path`를 포함합니다. 백엔드 리소스에 대한 요청에서 스테이지 이름을 제거하려면 [파라미터 매핑](rest-api-parameter-mapping.md)을 사용하여 `$context.requestOverride.path` 변수에 대한 재정의를 생성합니다.
+ AWS Cloud Map와의 프라이빗 통합은 지원되지 않습니다.
**Topics**
+ [고려 사항](#private-integrations-considerations)
+ [API Gateway에서 VPC 링크 V2 설정](apigateway-vpc-links-v2.md)
+ [프라이빗 통합 설정](set-up-private-integration.md)
+ [VPC 링크 V1을 사용한 프라이빗 통합(레거시)](vpc-links-v1.md)
# API Gateway에서 VPC 링크 V2 설정
VPC 링크를 사용하여 API 라우팅을 VPC의 프라이빗 리소스(예: Application Load Balancer 또는 Amazon ECS 컨테이너 기반 애플리케이션)에 연결하는 프라이빗 통합을 생성할 수 있습니다. 프라이빗 통합은 VPC 링크 V2를 사용하여 API Gateway와 대상 VPC 리소스 간의 연결을 캡슐화합니다. 서로 다른 리소스 및 API에서 VPC 링크를 재사용할 수 있습니다.
VPC 링크 V2를 생성할 때 API Gateway는 계정에서 VPC 링크에 대한 [탄력적 네트워크 인터페이스](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)를 생성 및 관리합니다. 이 프로세스는 몇 분 정도 걸릴 수 있습니다. VPC 링크 V2를 사용할 준비가 되면 상태가 `PENDING`에서 `AVAILABLE`로 바뀝니다.
**참고**
60일 동안 VPC 링크를 통해 전송되는 트래픽이 없으면 이것이 `INACTIVE`이 됩니다. VPC 링크가 `INACTIVE` 상태에 있으면 API Gateway는 VPC 링크의 네트워크 인터페이스를 모두 삭제합니다. 이로 인해 VPC 링크를 사용하는 API 요청이 실패하게 됩니다. API 요청이 재개되면 API Gateway는 네트워크 인터페이스를 다시 프로비저닝합니다. 네트워크 인터페이스를 생성하고 VPC 링크를 다시 활성화하는 데 몇 분 정도 걸릴 수 있습니다. VPC 링크 상태를 사용하여 VPC 링크의 상태를 모니터링할 수 있습니다.
## AWS CLI를 사용하여 VPC 링크 V2 생성
VPC 링크 V2를 생성하려면 관련된 모든 리소스를 동일한 AWS 계정이 소유해야 합니다. 다음 [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html) 명령은 VPC 링크를 생성합니다.
```
aws apigatewayv2 create-vpc-link --name MyVpcLink \
--subnet-ids subnet-aaaa subnet-bbbb \
--security-group-ids sg1234 sg5678
```
**참고**
VPC 링크 V2는 변경할 수 없습니다. VPC 링크 V2를 생성한 후에는 해당 서브넷이나 보안 그룹을 변경할 수 없습니다.
## AWS CLI을 사용하여 VPC 링크 V2 삭제
다음 [delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html) 명령은 VPC 링크를 삭제합니다.
```
aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123
```
## 리전별 가용성
VPC 링크 V2는 다음 리전 및 가용 영역에서 지원됩니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/apigateway-vpc-links-v2.html)
# 프라이빗 통합 설정
Application Load Balancer 또는 Network Load Balancer와 프라이빗 통합을 생성하려면 HTTP 프록시 통합을 생성하고, 사용할 [VPC 링크 V2](apigateway-vpc-links-v2.md)를 지정하고, Network Load Balancer 또는 Application Load Balancer의 ARN을 제공해야 합니다. 기본적으로 프라이빗 통합 트래픽은 HTTP 프로토콜을 사용합니다. HTTPS를 사용하려면 `https://example.com:443/test`와 같이 보안 서버 이름이 포함된 [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)를 지정합니다. 프라이빗 통합을 사용하여 REST API를 생성하는 방법에 대한 전체 자습서는 [자습서: 프라이빗 통합을 통해 REST API 생성](getting-started-with-private-integration.md) 섹션을 참조하세요.
## 프라이빗 통합 생성
다음 절차에서는 VPC 링크 V2를 사용하여 로드 밸런서에 연결하는 프라이빗 통합을 생성하는 방법을 보여 줍니다.
------
#### [ AWS Management Console ]
프라이빗 통합을 생성하는 방법에 대한 자습서는 [자습서: 프라이빗 통합을 통해 REST API 생성](getting-started-with-private-integration.md) 섹션을 참조하세요.
------
#### [ AWS CLI ]
다음 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 명령은 VPC 링크 V2를 통해 로드 밸런서에 연결하는 프라이빗 통합을 생성합니다.
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id bbb111
```
연결 ID를 직접 제공하는 대신 스테이지 변수를 사용할 수 있습니다. API를 스테이지에 배포할 때 VPC 링크 V2 ID를 설정합니다. 다음 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 명령은 VPC 링크 V2 ID에 대한 스테이지 변수를 사용하여 프라이빗 통합을 생성합니다.
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkV2Id}"
```
단계 변수 표현식(\$1\$1stageVariables.vpcLinkV2Id\$1)을 큰따옴표로 묶고 \$1 문자를 이스케이프합니다.
------
#### [ OpenAPI ]
API의 OpenAPI 파일을 가져와 프라이빗 통합이 포함된 API를 설정할 수 있습니다. 다음만 제외하면 설정은 HTTP 통합이 포함된 API의 OpenAPI 정의와 비슷합니다.
+ 명시적으로 `connectionType`을 `VPC_LINK`로 설정해야 합니다.
+ 명시적으로 `connectionId`를 `VpcLinkV2`의 ID 또는 `VpcLinkV2`의 ID를 참조하는 단계 변수로 설정해야 합니다.
+ 프라이빗 통합의 `uri` 파라미터는 VPC의 HTTP/HTTPS 엔드포인트를 가리키지만 그 대신 통합 요청의 `Host` 헤더를 설정하는 데 사용됩니다.
+ VPC에 HTTPS 엔드포인트가 있는 프라이빗 통합의 `uri` 파라미터는 VPC 엔드포인트에 설치된 인증서에 있는 이름과 대조하여 지정된 도메인 이름을 확인하는 데 사용됩니다.
단계 변수를 사용하여 `VpcLinkV2` ID를 참조할 수 있습니다. 또는 ID 값을 직접 `connectionId`에 할당할 수 있습니다.
다음 JSON 형식의 OpenAPI 파일은 단계 변수(`${stageVariables.vpcLinkIdV2}`)가 참조하는 VPC 링크가 포함된 API의 예를 보여 줍니다.
```
{
"swagger": "2.0",
"info": {
"version": "2017-11-17T04:40:23Z",
"title": "MyApiWithVpcLinkV2"
},
"host": "abcdef123.execute-api.us-west-2.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "https://example.com:443/path",
"passthroughBehavior": "when_no_match",
"connectionType": "VPC_LINK",
"connectionId": "${stageVariables.vpcLinkV2Id}",
"integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011",
"httpMethod": "GET",
"type": "http_proxy"
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## 프라이빗 통합 업데이트
다음 예시에서는 프라이빗 통합을 위해 VPC 링크 V2를 업데이트합니다.
------
#### [ AWS Management Console ]
**프라이빗 통합 업데이트**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 프라이빗 통합이 포함된 REST API를 선택합니다.
1. 프라이빗 통합을 사용하는 리소스와 메서드를 선택합니다.
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. 프라이빗 통합의 설정을 편집할 수 있습니다. 현재 VPC 링크 V1을 사용하는 경우 VPC 링크를 VPC 링크 V2로 변경할 수 있습니다.
1. **저장**을 선택합니다.
1. 변경 사항을 적용하려면 API를 재배포합니다.
------
#### [ AWS CLI ]
다음 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 명령은 VPC 링크 V2를 사용하도록 프라이빗 통합을 업데이트합니다.
```
aws apigateway update-integration \
--rest-api-id a1b2c3d4e5 \
--resource-id a1b2c3 \
--http-method GET \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]"
```
------
# VPC 링크 V1을 사용한 프라이빗 통합(레거시)
**참고**
프라이빗 통합의 다음 구현에서는 VPC 링크 V1을 사용합니다. VPC 링크 V1은 레거시 리소스입니다. [REST API에는 VPC 링크 V2](apigateway-vpc-links-v2.md)를 사용하는 것이 좋습니다.
프라이빗 통합을 생성하려면 먼저 Network Load Balancer를 생성해야 합니다. Network Load Balancer에는 요청을 VPC의 리소스로 라우팅하는 [리스너](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html)가 있어야 합니다. API의 가용성을 개선하려면 Network Load Balancer에서 AWS 리전의 한 개 이상의 가용 영역에 있는 리소스로 트래픽을 라우팅해야 합니다. 그런 다음 API와 Network Load Balancer를 연결하는 데 사용하는 VPC 링크를 생성합니다. VPC 링크를 생성한 후 프라이빗 통합을 생성하여 VPC 링크 및 Network Load Balancer를 통해 API에서 VPC의 리소스로 트래픽을 라우팅합니다. Network Load Balancer와 API는 동일한 AWS 계정에서 소유해야 합니다.
**Topics**
+ [API Gateway 프라이빗 통합을 위한 Network Load Balancer 설정(레거시)](set-up-nlb-for-vpclink-using-console.md)
+ [API Gateway에 VPC 링크를 생성할 수 있는 권한 부여(레거시)](grant-permissions-to-create-vpclink.md)
+ [AWS CLI를 사용하여 프라이빗 통합이 포함된 API Gateway API 설정(레거시)](set-up-api-with-vpclink-cli.md)
+ [프라이빗 통합에 사용되는 API Gateway 계정(레거시)](set-up-api-with-vpclink-accounts.md)
# API Gateway 프라이빗 통합을 위한 Network Load Balancer 설정(레거시)
**참고**
프라이빗 통합의 다음 구현에서는 VPC 링크 V1을 사용합니다. VPC 링크 V1은 레거시 리소스입니다. [REST API에는 VPC 링크 V2](apigateway-vpc-links-v2.md)를 사용하는 것이 좋습니다.
다음 절차에서는 Amazon EC2 콘솔을 사용하여 API Gateway 프라이빗 통합을 위해 Network Load Balancer(NLB)를 설정하는 단계를 설명하고, 각 단계의 상세한 지침을 위한 참조를 제공합니다.
리소스를 보유한 각 VPC에 대해 하나의 NLB와 하나의 VPCLink만 구성하면 됩니다. NLB는 NLB당 여러 [리스너](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html)와 [대상 그룹](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html)을 지원합니다. 각 서비스를 NLB에서 특정 리스너로 구성하고 단일 VPCLink를 사용해 NLB에 연결할 수 있습니다. API Gateway에서 프라이빗 통합을 생성하는 경우, 각 서비스에 할당된 특정 포트를 사용하여 각 서비스를 정의합니다. 자세한 내용은 [자습서: 프라이빗 통합을 통해 REST API 생성](getting-started-with-private-integration.md) 섹션을 참조하세요. Network Load Balancer와 API는 동일한 AWS 계정에서 소유해야 합니다.
**API Gateway 콘솔을 사용하여 프라이빗 통합을 위한 Network Load Balancer를 생성하려면**
1. AWS Management Console에 로그인하고 [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)에서 Amazon EC2 콘솔을 엽니다.
1. Amazon EC2 인스턴스에서 웹 서버를 설정합니다. 설정 예제는 [Amazon Linux 2에 LAMP 웹 서버 설치](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html) 섹션을 참조하세요.
1. Network Load Balancer를 생성하고 대상 그룹에 EC2 인스턴스를 등록한 다음 대상 그룹을 Network Load Balancer의 리스너에 추가합니다. 자세한 내용은 [Network Load Balancer 시작하기](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html)의 지침을 따르세요.
1. Network Load Balancer가 생성된 후 다음 작업을 수행합니다.
1. Network Load Balancer의 ARN을 기록해 둡니다. API를 Network Load Balancer 뒤의 VPC 리소스와 통합하기 위해 API Gateway에서 VPC 링크를 생성하려면 이 정보가 필요합니다.
1. PrivateLink에 대한 보안 그룹 평가를 해제합니다.
+ 콘솔을 사용하여 PrivateLink 트래픽에 대한 보안 그룹 평가를 끄려면 **보안** 탭을 선택한 다음 **편집**을 선택하면 됩니다. **보안 설정**에서 **PrivateLink 트래픽에 인바운드 규칙 적용**을 선택 해제합니다.
+ 다음 [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html) 명령을 사용하면 PrivateLink 트래픽에 대한 보안 그룹 평가를 끌 수 있습니다.
```
aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \
--security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off
```
**참고**
API Gateway CIDR은 예고 없이 변경될 수 있으므로 종속성을 추가하지 마세요.
# API Gateway에 VPC 링크를 생성할 수 있는 권한 부여(레거시)
**참고**
프라이빗 통합의 다음 구현에서는 VPC 링크 V1을 사용합니다. VPC 링크 V1은 레거시 리소스입니다. [REST API에는 VPC 링크 V2](apigateway-vpc-links-v2.md)를 사용하는 것이 좋습니다.
본인 또는 본인 계정의 사용자가 VPC 링크를 생성 및 유지 관리하려면 VPC 엔드포인트 서비스 구성을 생성, 삭제, 확인하고, VPC 엔드포인트 서비스 권한을 변경하고, 로드 밸런서를 검사할 수 있는 권한이 있어야 합니다. 이러한 권한을 부여하려면 다음 단계를 사용하세요.
**VPC 링크를 생성, 업데이트 및 삭제할 수 있는 권한을 부여하려면**
1. 다음과 비슷한 IAM 정책을 생성합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST",
"apigateway:GET",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/vpclinks",
"arn:aws:apigateway:us-east-1::/vpclinks/*"
]
},
{
"Effect": "Allow",
"Action": [
"elasticloadbalancing:DescribeLoadBalancers"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpointServiceConfiguration",
"ec2:DeleteVpcEndpointServiceConfigurations",
"ec2:DescribeVpcEndpointServiceConfigurations",
"ec2:ModifyVpcEndpointServicePermissions"
],
"Resource": "*"
}
]
}
```
------
VPC 링크에 대해 태그 지정을 활성화하려면 태그 지정 작업을 허용해야 합니다. 자세한 내용은 [태그 지정 작업 허용](apigateway-tagging-iam-policy.md#allow-tagging) 섹션을 참조하세요.
1. IAM 역할을 만들거나 선택하여 앞의 정책을 이 역할에 연결합니다.
1. IAM 역할을 본인 또는 VPC 링크를 생성하는 본인 계정의 사용자에게 할당합니다.
# AWS CLI를 사용하여 프라이빗 통합이 포함된 API Gateway API 설정(레거시)
**참고**
프라이빗 통합의 다음 구현에서는 VPC 링크 V1을 사용합니다. VPC 링크 V1은 레거시 리소스입니다. [REST API에는 VPC 링크 V2](apigateway-vpc-links-v2.md)를 사용하는 것이 좋습니다.
다음 튜토리얼에서는 AWS CLI를 사용하여 VPC 링크와 프라이빗 통합이 생성되는 방법을 보여줍니다. 다음과 같은 사전 조건을 충족해야 합니다.
+ Network Load Balancer를 생성하고 VPC 소스를 대상으로 구성해야 합니다. 자세한 내용은 [API Gateway 프라이빗 통합을 위한 Network Load Balancer 설정(레거시)](set-up-nlb-for-vpclink-using-console.md) 섹션을 참조하세요. 이는 API와 동일한 AWS 계정에 있어야 합니다. VPC 링크를 생성하려면 Network Load Balancer ARN이 필요합니다.
+ `VpcLink`를 생성하고 관리하려면 API에서 `VpcLink`를 생성할 수 있는 권한이 필요합니다. `VpcLink`를 사용하기 위한 권한은 필요하지 않습니다. 자세한 내용은 [API Gateway에 VPC 링크를 생성할 수 있는 권한 부여(레거시)](grant-permissions-to-create-vpclink.md) 섹션을 참조하세요.
**AWS CLI를 사용하여 프라이빗 통합이 포함된 API를 생성하려면**
1. 다음 [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html) 명령을 사용하면 지정된 Network Load Balancer를 대상으로 하는 `VpcLink`를 생성할 수 있습니다.
```
aws apigateway create-vpc-link \
--name my-test-vpc-link \
--target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef
```
이 명령의 출력은 요청 수신을 확인하고 생성 중인 `VpcLink`의 `PENDING` 상태를 보여줍니다.
```
{
"status": "PENDING",
"targetArns": [
"arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef"
],
"id": "gim7c3",
"name": "my-test-vpc-link"
}
```
API Gateway가 `VpcLink` 생성을 완료하는 데 2\$14분이 걸립니다. 작업이 성공적으로 완료되면 `status`는 `AVAILABLE`이 됩니다. 다음 [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html) 명령을 사용하여 이를 확인할 수 있습니다.
```
aws apigateway get-vpc-link --vpc-link-id gim7c3
```
작업이 실패하면 오류 메시지가 포함된 `FAILED`와 함께 `statusMessage` 상태를 얻게 됩니다. 예를 들어 이미 VPC 종단점에 연결된 Network Load Balancer를 사용하여 `VpcLink`를 생성하려는 경우, `statusMessage` 속성에서 다음을 얻게 됩니다.
```
"NLB is already associated with another VPC Endpoint Service"
```
`VpcLink`가 성공적으로 생성되어야 API를 생성하고 `VpcLink`를 통해 VPC 리소스와 통합할 수 있습니다.
새로 생성한 `VpcLink`의 `id` 값을 기록해 둡니다. 이 예제 출력에서는 `gim7c3`입니다. 프라이빗 통합을 설정하려면 이 값이 필요합니다.
1. 다음 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 명령을 사용하면 API Gateway [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스를 생성할 수 있습니다.
```
aws apigateway create-rest-api --name 'My VPC Link Test'
```
반환된 결과에서 `RestApi`의 `id` 값과 `RestApi`의 `rootResourceId` 값을 기록해 둡니다. 이 작업은 API에 대한 추가 작업을 실행하는 데 필요합니다.
그런 다음, 루트 리소스(`GET`)에 `/` 메서드만 있는 API를 생성해 이 메서드를 `VpcLink`와 통합합니다.
1. 다음 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 명령을 사용하여 `GET /` 메서드를 생성합니다.
```
aws apigateway put-method \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--authorization-type "NONE"
```
`VpcLink`에 프록시 통합을 사용하지 않는 경우, 상태 코드가 `200` 이상인 메서드 응답도 설정해야 합니다. 여기서는 프록시 통합을 사용합니다.
1. `GET /` 메서드를 생성한 후 통합을 설정합니다. 프라이빗 통합의 경우 `connection-id` 파라미터를 사용하여 `VpcLink` ID를 제공합니다. 스테이지 변수를 사용하거나 `VpcLink` ID를 직접 입력할 수 있습니다. `uri` 파라미터는 요청을 엔드포인트로 라우팅하는 데 사용되지 않지만 `Host` 헤더 설정 및 인증서 유효성 검사에 사용됩니다.
------
#### [ Use the VPC link ID ]
다음 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 명령을 사용하여 통합에서 `VpcLink` ID를 직접 사용합니다.
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id gim7c3
```
------
#### [ Use a stage variable ]
다음 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 명령을 사용하여 스테이지 변수를 사용하여 VPC 링크 ID를 참조합니다. API를 스테이지에 배포할 때 VPC 링크 ID를 설정합니다.
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkId}"
```
단계 변수 표현식(`${stageVariables.vpcLinkId}`)을 큰따옴표로 묶고 `$` 문자를 이스케이프합니다.
------
또한 언제든지 통합을 업데이트하여 `connection-id`를 변경할 수 있습니다. 다음 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) 명령을 사용하여 통합을 업데이트합니다.
```
aws apigateway update-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]'
```
문자열화된 JSON 목록을 `patch-operations` 파라미터 값으로 사용해야 합니다.
프라이빗 프록시 통합을 사용했기 때문에 이제 API를 배포 및 테스트 실행할 준비가 됐습니다.
1. 스테이지 변수를 사용하여 `connection-id`를 정의한 경우 API를 배포하여 테스트해야 합니다. 다음 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 명령을 사용하면 스테이지 변수를 사용하여 API를 배포할 수 있습니다.
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name test \
--variables vpcLinkId=gim7c3
```
다른 `VpcLink` ID(예: `asf9d7`)로 스테이지 변수를 업데이트하려면 다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 명령을 사용합니다.
```
aws apigateway update-stage \
--rest-api-id abcdef123 \
--stage-name test \
--patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'
```
`VpcLink` ID 리터럴로 `connection-id` 속성을 하드코딩하면 테스트를 위해 API를 배포하지 않아도 됩니다. [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html) 명령을 사용하여 API를 배포하기 전에 테스트할 수 있습니다.
1. 다음 명령을 사용하여 API를 호출합니다.
```
curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test
```
또는 API의 간접 호출 URL을 웹 브라우저에서 입력하여 결과를 볼 수 있습니다.
# 프라이빗 통합에 사용되는 API Gateway 계정(레거시)
다음 리전별 API Gateway 계정 ID는 `AllowedPrincipals`을 생성할 때 `VpcLink`로 VPC 종단점 서비스에 자동으로 추가됩니다 .
| **리전** | **계정 ID**\$1 |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
# API Gateway의 REST API 모의 통합
Amazon API Gateway는 API 메서드에 대한 모의 통합을 지원합니다. 이 기능을 통해 API 개발자는 통합 백엔드가 없어도 API Gateway에서 직접 API 응답을 생성할 수 있습니다. API 개발자라면 이 기능을 사용하여 프로젝트 개발이 완료되기 전에 API로 작업해야 하는 종속 팀에 대한 차단을 해제할 수 있습니다. 또한 이 기능을 활용하여 API의 개요와 탐색 기능을 제공하는 API에 대해 시작 페이지를 프로비저닝할 수 있습니다. 이러한 시작 페이지의 예는 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)에서 설명한 예제 API의 루트 리소스에 대한 GET 메서드의 통합 요청 및 응답을 참조하세요.
API 개발자는 API Gateway가 모의 통합 요청에 응답하는 방법을 결정합니다. 이를 위해, 메서드의 통합 요청 및 통합 응답을 구성하여 정해진 상태 코드와 응답을 연결합니다. 모의 통합이 포함된 메서드가 `200` 응답을 반환하려면 다음을 반환하도록 통합 요청 본문 매핑 템플릿을 구성해야 합니다.
```
{"statusCode": 200}
```
예를 들어 다음의 본문 매핑 템플릿이 포함되도록 `200` 통합 응답을 구성하세요.
```
{
"statusCode": 200,
"message": "Go ahead without me."
}
```
마찬가지로 메서드가 예를 들어 `500` 오류 응답을 반환하려면 다음을 반환하도록 통합 요청 본문 매핑 템플릿을 설정해야 합니다.
```
{"statusCode": 500}
```
예를 들어 다음의 매핑 템플릿을 사용하여 `500` 통합 응답을 설정하세요.
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
또는 통합 요청 매핑 템플릿을 정의하지 않고 모의 통합의 메서드가 기본 통합 응답을 반환하도록 할 수도 있습니다. 기본 통합 응답은 정의되지 않은 **HTTP status regex(HTTP 상태 regex)**가 포함된 응답입니다. 적절한 패스스루 동작이 설정되어야 합니다.
**참고**
모의 통합은 대규모 응답 템플릿을 지원하지 않습니다. 사용 사례에 필요한 경우 대신 Lambda 통합 사용을 고려해야 합니다.
통합 요청 매핑 템플릿을 사용하여 애플리케이션 로직을 삽입하면 특정 조건에 따라 반환할 모의 통합 응답을 결정할 수 있습니다. 예를 들어 수신되는 요청에서 `scope` 쿼리 파라미터를 사용하여 성공 응답을 반환할지 오류 응답을 반환할지 결정할 수 있습니다.
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
이런 방법으로 모의 통합의 메서드는 오류 응답을 포함한 다른 유형의 호출은 거부하면서 내부 호출을 통과시킵니다.
이 단원에서는 API Gateway 콘솔을 사용하여 API 메서드에 대한 모의 통합을 활성화하는 방법에 대해 설명합니다.
**Topics**
+ [API Gateway 콘솔을 사용하여 모의 통합 활성화](how-to-mock-integration-console.md)
# API Gateway 콘솔을 사용하여 모의 통합 활성화
API Gateway에 사용 가능한 메서드가 있어야 합니다. [자습서: HTTP 비 프록시 통합을 통해 REST API 생성](api-gateway-create-api-step-by-step.md)의 지침을 따르세요.
1. API 리소스를 선택하고 **메서드 생성**을 선택합니다.
메서드를 생성하려면 다음을 수행합니다.
1. **메서드 유형**에서 메서드를 선택합니다.
1. **통합 유형**에서 **Mock**을 선택합니다.
1. **메서드 생성**을 선택합니다.
1. **메서드 요청** 탭의 **메서드 요청 설정**에서 **편집**을 선택합니다.
1. **URL 쿼리 문자열 파라미터**를 선택합니다. **쿼리 문자열 추가**를 선택하고 **이름**에 **scope**를 입력합니다. 쿼리 파라미터에 따라 호출자가 내부 호출자인지 아닌지 결정됩니다.
1. **저장**을 선택합니다.
1. **메서드 응답** 탭에서 **응답 생성**을 선택하고 다음을 수행합니다.
1. **HTTP 상태**에 **500**을 입력합니다.
1. **저장**을 선택합니다.
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **매핑 템플릿**을 선택한 후 다음을 수행합니다.
1. **매핑 템플릿 추가(Add mapping template)**를 선택합니다.
1. **콘텐츠 유형**에 **application/json**을 입력합니다.
1. **템플릿 본문**에 다음을 입력합니다.
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
1. **저장**을 선택합니다.
1. **통합 응답** 탭의 **기본값 - 응답**에서 **편집**을 선택합니다.
1. **매핑 템플릿**을 선택한 후 다음을 수행합니다.
1. **콘텐츠 유형**에 **application/json**을 입력합니다.
1. **템플릿 본문**에 다음을 입력합니다.
```
{
"statusCode": 200,
"message": "Go ahead without me"
}
```
1. **저장**을 선택합니다.
1. **응답 생성**을 선택합니다.
500 응답을 생성하려면 다음을 수행합니다.
1. **HTTP 상태 regex**에 **5\$1d\$12\$1**를 입력합니다.
1. **메서드 응답 상태**에서 **500**을 선택합니다.
1. **저장**을 선택합니다.
1. **5\$1d\$12\$1 - 응답**에서 **편집**을 선택합니다.
1. **매핑 템플릿**을 선택한 다음 **매핑 템플릿 추가**를 선택합니다.
1. **콘텐츠 유형**에 **application/json**을 입력합니다.
1. **템플릿 본문**에 다음을 입력합니다.
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
1. **저장**을 선택합니다.
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다. Mock 통합을 테스트하려면 다음을 수행합니다.
1. **쿼리 문자열**에 `scope=internal`을 입력합니다. **테스트**를 선택합니다. 테스트 결과에 다음이 표시됩니다.
```
Request: /?scope=internal
Status: 200
Latency: 26 ms
Response Body
{
"statusCode": 200,
"message": "Go ahead without me"
}
Response Headers
{"Content-Type":"application/json"}
```
1. `scope=public`에 `Query strings`을 입력하거나 비워 둡니다. **테스트**를 선택합니다. 테스트 결과에 다음이 표시됩니다.
```
Request: /
Status: 500
Latency: 16 ms
Response Body
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
Response Headers
{"Content-Type":"application/json"}
```
먼저 메서드 응답에 헤더를 추가한 다음 통합 응답에서 헤더 매핑을 설정하면 모의 통합 응답에서 헤더를 반환할 수도 있습니다. 이는 사실 API Gateway 콘솔이 CORS 필수 헤더를 반환하여 CORS 지원을 활성화하는 방법입니다.
# API Gateway의 REST API API 검증 요청
통합 요청을 진행하기 전에 API 요청의 기본 확인을 수행하도록 API Gateway를 구성할 수 있습니다. 확인되지 않을 경우, API Gateway는 즉시 요청에 실패하고 호출자에게 400 오류 응답을 반환하며 확인 결과를 CloudWatch Logs에 게시합니다. 이렇게 하면 불필요한 백엔드 호출이 줄어듭니다. 무엇보다, 해당 애플리케이션 고유의 확인 작업에 집중할 수 있게 됩니다. 필요한 요청 파라미터가 유효하며 Null이 아님을 확인하거나 더 복잡한 데이터 확인에 대한 모델 스키마를 지정하여 요청 본문을 확인할 수 있습니다.
**Topics**
+ [API Gateway의 기본 요청 확인 개요](#api-gateway-request-validation-basic-definitions)
+ [REST API에 대한 데이터 모델](models-mappings-models.md)
+ [API Gateway의 기본 요청 확인 설정](api-gateway-request-validation-set-up.md)
+ [기본 요청 검증이 포함된 샘플 API의 AWS CloudFormation 템플릿](api-gateway-request-validation-sample-cloudformation.md)
## API Gateway의 기본 요청 확인 개요
API Gateway는 기본 요청 확인을 수행할 수 있으므로 사용자가 백엔드에서 앱별 확인에 집중할 수 있습니다. 확인에서 API Gateway는 다음 조건 중 하나 또는 둘 다를 확인합니다.
+ URI의 필수 요청 파라미터, 쿼리 문자열, 수신 요청의 헤더가 포함되어 있고 비어 있지 않습니다. API Gateway는 파라미터의 존재 여부만 확인하고 유형이나 형식은 확인하지 않습니다.
+ 해당 요청 페이로드는 주어진 콘텐츠 유형에 대한 메서드의 구성된 [JSON 스키마](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) 요청을 준수합니다. 일치하는 콘텐츠 유형이 없는 경우 요청 확인이 수행되지 않습니다. 콘텐츠 유형에 관계없이 동일한 모델을 사용하려면 데이터 모델의 콘텐츠 유형을 `$default`로 설정합니다.
확인을 활성화하려면 [요청 검사기](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)에 확인 규칙을 지정하고, API의 [요청 검사기 맵](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)에 검사기를 추가하고, 개별 API 메서드에 검사기를 할당합니다.
**참고**
요청 본문 확인과 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md)은 별도의 주제입니다. 요청 페이로드에 일치하는 모델 스키마가 없으면 패스스루를 선택하거나 원래 페이로드를 차단할 수 있습니다. 자세한 내용은 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하세요.
# REST API에 대한 데이터 모델
API Gateway에서 모델은 페이로드의 데이터 구조를 정의합니다. API Gateway에서 모델은 [JSON 스키마 드래프트 4](https://tools.ietf.org/html/draft-zyp-json-schema-04)를 사용하여 정의됩니다. 다음 JSON 객체는 Pet Store 예시의 샘플 데이터입니다.
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
데이터에는 반려동물의 `id`, `type` 및 `price`가 포함되어 있습니다. 이 데이터의 모델을 통해 다음을 수행할 수 있습니다.
+ 기본 요청 확인을 사용합니다.
+ 데이터 변환을 위한 매핑 템플릿을 생성합니다.
+ SDK를 생성할 때 사용자 정의 데이터 유형(UDT)을 생성합니다.
![\[PetStore API의 JSON 데이터 모델 예시입니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/how-to-validate-requests.png)
이 모델의 경우:
1. `$schema` 객체는 유효한 JSON 스키마 버전 식별자를 나타냅니다. 이 스키마는 JSON 스키마 드래프트 v4입니다.
1. `title` 객체는 사람이 읽을 수 있는 모델 식별자입니다. 이 제목은 `PetStoreModel`입니다.
1. 기본 요청 확인에서는 `required` 확인 키워드에 `type` 및 `price`가 필요합니다.
1. 모델의 `properties`은 `id`, `type`, `price`입니다. 각 객체에는 모델에 설명된 속성이 있습니다.
1. `type` 객체에는 `dog`, `cat`, 또는 `fish` 값만 있을 수 있습니다.
1. `price` 객체는 숫자이며 `minimum` 25, `maximum` 500으로 제한됩니다.
## PetStore 모델
```
1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3 "title": "PetStoreModel",
4 "type" : "object",
5 "required" : [ "price", "type" ],
6 "properties" : {
7 "id" : {
8 "type" : "integer"
9 },
10 "type" : {
11 "type" : "string",
12 "enum" : [ "dog", "cat", "fish" ]
13 },
14 "price" : {
15 "type" : "number",
16 "minimum" : 25.0,
17 "maximum" : 500.0
18 }
19 }
20 }
```
이 모델의 경우:
1. 2번째 줄에서 `$schema` 객체는 유효한 JSON 스키마 버전 식별자를 나타냅니다. 이 스키마는 JSON 스키마 드래프트 v4입니다.
1. 3번째 줄에서 `title` 객체는 사람이 읽을 수 있는 모델 식별자입니다. 이 제목은 `PetStoreModel`입니다.
1. 5번째 줄에서 기본 요청 확인에서는 `required` 확인 키워드에 `type` 및 `price`가 필요합니다.
1. 6\$117번째 줄에서 모델의 `properties`은 `id`, `type`, `price`입니다. 각 객체에는 모델에 설명된 속성이 있습니다.
1. 12번째 줄에서 `type` 객체에는 `dog`, `cat` 또는 `fish` 값만 있을 수 있습니다.
1. 14\$117번째 줄에서 `price` 객체는 숫자이며 `minimum` 25, `maximum` 500으로 제한됩니다.
## 더 복잡한 모델 생성
`$ref` 프리미티브를 사용하여 더 긴 모델에 대해 재사용 가능한 정의를 만들 수 있습니다. 예를 들어, `price` 객체를 설명하는 `definitions` 섹션에서 `Price`라는 정의를 생성할 수 있습니다. `$ref`의 값은 `Price` 정의입니다.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReUsableRef",
"required" : ["price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "#/definitions/Price"
}
},
"definitions" : {
"Price": {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
외부 모델 파일에 정의된 다른 모델 스키마를 참조할 수도 있습니다. `$ref` 속성 값을 모델의 위치로 설정합니다. 다음 예시에서는 `Price` 모델이 `a1234` API의 `PetStorePrice` 모델에 정의되어 있습니다.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStorePrice",
"type": "number",
"minimum": 25,
"maximum": 500
}
```
더 긴 모델은 `PetStorePrice` 모델을 참조할 수 있습니다.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReusableRefAPI",
"required" : [ "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
}
}
}
```
## 출력 데이터 모델 사용
데이터를 변환하면 통합 응답에서 페이로드 모델을 정의할 수 있습니다. 페이로드 모델은 SDK를 생성할 때 사용할 수 있습니다. Java, Objective-C 또는 Swift 등 강력한 형식의 언어에서 객체는 사용자 정의 데이터 형식(UDT)에 해당합니다. SDK를 생성할 때 데이터 모델과 함께 제공하면 API Gateway가 이러한 UDT를 생성합니다. 데이터 변환에 대한 자세한 내용은 [API Gateway에서 REST API의 데이터 변환 매핑](models-mappings.md) 섹션을 참조하세요.
다음 예시는 통합 응답의 출력 데이터입니다.
```
{
[
{
"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
}
]
}
```
다음 예시는 출력 데이터를 설명하는 페이로드 모델입니다.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetStoreOutputModel",
"type" : "object",
"required" : [ "description", "askingPrice" ],
"properties" : {
"description" : {
"type" : "string"
},
"askingPrice" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
이 모델에서는 `PetStoreOutputModel[i].description` 및 `PetStoreOutputModel[i].askingPrice` 속성을 읽음으로써 `description` 및 `askingPrice` 속성 값을 검색하도록 SDK를 호출할 수 있습니다. 모델이 제공되지 않는 경우, API Gateway는 빈 모델을 사용하여 기본 UDT를 생성합니다.
## 다음 단계
+ 이 섹션에서는 이 주제에 제시된 개념에 대해 자세히 알아보는 데 사용할 수 있는 리소스를 제공합니다.
요청 확인 자습서를 따라 수행할 수 있습니다.
+ [API Gateway 콘솔을 사용하여 요청 확인 설정](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console)
+ [AWS CLI를 사용하여 기본 요청 확인 설정](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli)
+ [OpenAPI 정의를 사용하여 기본 요청 확인 설정](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger)
+ 데이터 변환 및 매핑 템플릿에 대한 자세한 내용은 [API Gateway에서 REST API의 데이터 변환 매핑](models-mappings.md) 섹션을 참조하시기 바랍니다.
# API Gateway의 기본 요청 확인 설정
이 섹션에서는 콘솔과 AWS CLI, OpenAPI 정의를 사용하여 API Gateway에 대한 요청 확인을 설정하는 방법을 보여줍니다.
**Topics**
+ [API Gateway 콘솔을 사용하여 요청 확인 설정](#api-gateway-request-validation-setup-in-console)
+ [AWS CLI를 사용하여 기본 요청 확인 설정](#api-gateway-request-validation-setup-cli)
+ [OpenAPI 정의를 사용하여 기본 요청 확인 설정](#api-gateway-request-validation-setup-importing-swagger)
## API Gateway 콘솔을 사용하여 요청 확인 설정
API Gateway 콘솔을 사용하여 API 요청에 대한 세 가지 검사기 중 하나를 선택하여 요청을 확인할 수 있습니다.
+ **본문을 확인합니다**.
+ **쿼리 문자열 파라미터 및 헤더를 확인합니다**.
+ **본문, 쿼리 문자열 파라미터 및 헤더를 확인합니다**.
API 메서드에서 검사기 중 하나를 적용하면 API Gateway 콘솔은 해당 검사기를 API의 [RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) 맵에 추가합니다.
이 자습서를 따라 하려면 CloudFormation 템플릿을 사용하여 불완전한 API Gateway API를 생성해야 합니다. 이 API에는 `GET` 및 `POST` 메서드가 포함된 `/validator` 리소스가 있습니다. 두 메서드 모두 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 엔드포인트와 통합됩니다. 두 가지 유형의 요청 확인을 구성합니다.
+ `GET` 메서드에서 URL 쿼리 문자열 파라미터에 대한 요청 확인을 구성합니다.
+ `POST` 메서드에서 요청 본문에 대한 요청 확인을 구성합니다.
이렇게 하면 특정 API 호출만 API로 전달될 수 있습니다.
[CloudFormation용 앱 생성 템플릿](samples/request-validation-tutorial-console.zip)을 다운로드하고 압축을 해제합니다. 이 템플릿을 사용하여 불완전한 API를 만들 수 있습니다. API Gateway 콘솔에서 나머지 단계를 완료하게 됩니다.
**CloudFormation 스택을 생성하려면**
1. CloudFormation 콘솔([https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/))을 엽니다.
1. **스택 생성**을 선택한 다음 **새 리소스 사용(표준)**을 선택합니다.
1. **템플릿 지정**에서 **템플릿 파일 업로드**를 선택합니다.
1. 다운로드한 템플릿을 선택합니다.
1. **다음**을 선택합니다.
1. **스택 이름**에 **request-validation-tutorial-console**을 입력하고 **다음**을 선택합니다.
1. **스택 옵션 구성**에서 **다음**을 선택합니다.
1. **기능**의 경우 CloudFormation이 계정에 IAM 리소스를 생성할 수 있음을 확인합니다.
1. **다음**을 선택한 후 **제출**을 선택합니다.
CloudFormation은 템플릿에 지정된 리소스를 프로비저닝합니다. 리소스 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. CloudFormation 스택 상태가 **CREATE\$1COMPLETE**인 경우 다음 단계로 넘어갈 준비가 된 것입니다.
**새로 생성한 API를 선택하는 방법**
1. 새로 생성한 **request-validation-tutorial-console** 스택을 선택합니다.
1. **리소스**를 선택합니다.
1. **물리적 ID**에서 API를 선택합니다. 이 링크는 API Gateway 콘솔로 연결됩니다.
`GET` 및 `POST` 메서드를 수정하기 전에 모델을 만들어야 합니다.
**모델을 생성하는 방법**
1. 수신 요청의 본문에서 요청 확인을 사용하려면 모델이 필요합니다. 모델을 생성하려면 기본 탐색 창에서 **모델**을 선택합니다.
1. **Create model**(모델 생성)을 선택합니다.
1. **이름**에 **PetStoreModel**를 입력합니다.
1. **콘텐츠 유형**에 **application/json**을 입력합니다. 일치하는 콘텐츠 유형이 없는 경우 요청 확인이 수행되지 않습니다. 콘텐츠 유형에 관계없이 동일한 모델을 사용하려면 **\$1default**를 입력합니다.
1. **설명**에 모델 설명으로 **My PetStore Model**을 입력합니다.
1. **모델 스키마**의 경우 다음 모델을 코드 편집기에 붙여 넣고 **생성**을 선택합니다.
```
{
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
모델에 대한 자세한 내용은 [REST API에 대한 데이터 모델](models-mappings-models.md) 섹션을 참조하세요.
**`GET` 메서드에 대한 요청 검사를 구성하려면**
1. 기본 탐색 창에서 **리소스**를 선택하고 **GET** 메서드를 선택합니다.
1. **메서드 요청** 탭의 **메서드 요청 설정**에서 **편집**을 선택합니다.
1. **요청 검사기**에서 **쿼리 문자열 파라미터 및 헤더 검사**를 선택합니다.
1. **URL 쿼리 문자열 파라미터**에서 다음을 수행합니다.
1. **쿼리 문자열 추가(Add query string)**를 선택합니다.
1. **이름**에 **petType**를 입력합니다.
1. **필수**를 끕니다.
1. **캐싱**을 꺼진 상태로 둡니다.
1. **저장**을 선택합니다.
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **URL 쿼리 문자열 파라미터**에서 다음을 수행합니다.
1. **쿼리 문자열 추가(Add query string)**를 선택합니다.
1. **이름**에 **petType**를 입력합니다.
1. **다음에서 매핑됨**에 **method.request.querystring.petType**을 입력합니다. 이렇게 하면 **petType**이 반려동물의 유형에 매핑됩니다.
데이터 매핑에 대한 자세한 내용은 [데이터 매핑 자습서](set-up-data-transformations-in-api-gateway.md#mapping-example-console)를 참조하세요.
1. **캐싱**을 꺼진 상태로 둡니다.
1. **저장**을 선택합니다.
**`GET` 메서드에 대한 요청 검사를 테스트하려면**
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. **쿼리 문자열**에 **petType=dog**를 입력하고 **테스트**를 선택합니다.
1. 메서드 테스트에서 `200 OK`와 dog 목록이 반환됩니다.
이 출력 데이터를 변환하는 방법에 대한 자세한 내용은 [데이터 매핑 자습서](set-up-data-transformations-in-api-gateway.md#mapping-example-console)를 참조하세요.
1. **petType=dog**를 제거하고 **테스트**를 선택합니다.
1. 메서드 테스트에서 다음 오류 메시지와 함께 `400` 오류가 반환됩니다.
```
{
"message": "Missing required request parameters: [petType]"
}
```
**`POST` 메서드에 대한 요청 검사를 구성하려면**
1. 기본 탐색 창에서 **리소스**를 선택하고 **POST** 메서드를 선택합니다.
1. **메서드 요청** 탭의 **메서드 요청 설정**에서 **편집**을 선택합니다.
1. **요청 검사기**에서 **본문 검사**를 선택합니다.
1. **요청 본문**에서 **모델 추가**를 선택합니다.
1. **콘텐츠 유형**에 **application/json**을 입력합니다. 일치하는 콘텐츠 유형이 없는 경우 요청 확인이 수행되지 않습니다. 콘텐츠 유형에 관계없이 동일한 모델을 사용하려면 `$default`를 입력합니다.
**모델**에서 **PetStoreModel**을 선택합니다.
1. **저장**을 선택합니다.
**`POST` 메서드에 대한 요청 검사를 테스트하려면**
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. **요청 본문**에서 다음을 코드 편집기에 붙여 넣습니다.
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 400
}
```
**테스트**를 선택합니다.
1. 메서드 테스트에서 `200 OK`와 함께 성공 메시지가 반환됩니다.
1. **요청 본문**에서 다음을 코드 편집기에 붙여 넣습니다.
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 4000
}
```
**테스트**를 선택합니다.
1. 메서드 테스트에서 다음 오류 메시지와 함께 `400` 오류가 반환됩니다.
```
{
"message": "Invalid request body"
}
```
테스트 로그 하단에 잘못된 요청 본문의 이유가 반환됩니다. 이 경우 반려동물의 가격이 모델에 명시된 최대 가격을 벗어났습니다.
**CloudFormation 스택을 삭제하려면**
1. CloudFormation 콘솔([https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/))을 엽니다.
1. CloudFormation 스택을 선택합니다.
1. **삭제**를 선택한 다음 해당 선택을 확인합니다.
### 다음 단계
+ 출력 데이터를 변환하고 더 많은 데이터 매핑을 수행하는 방법에 대한 자세한 내용은 [데이터 매핑 자습서](set-up-data-transformations-in-api-gateway.md#mapping-example-console)를 참조하세요.
+ AWS CLI를 사용하여 유사한 단계를 수행하려면 [AWS CLI를 사용하여 기본 요청 확인 설정](#api-gateway-request-validation-setup-cli) 자습서를 따라 하세요.
## AWS CLI를 사용하여 기본 요청 확인 설정
AWS CLI를 사용하여 검사기를 만들어 요청 확인을 설정할 수 있습니다. 이 자습서를 따라 하려면 CloudFormation 템플릿을 사용하여 불완전한 API Gateway API를 생성해야 합니다.
**참고**
이 CloudFormation 템플릿은 콘솔 자습서에서 사용한 템플릿과 다릅니다.
미리 노출된 `/validator` 리소스를 사용하여 `GET` 및 `POST` 메서드를 생성합니다. 두 메서드 모두 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 엔드포인트와 통합됩니다. 다음과 같은 두 가지 요청 검사를 구성합니다.
+ `GET` 메서드에서 URL 쿼리 문자열 파라미터를 확인하는 `params-only` 검사기를 생성합니다.
+ `POST` 메서드에서 요청 본문을 확인하는 `body-only` 검사기를 생성합니다.
이렇게 하면 특정 API 호출만 API로 전달될 수 있습니다.
**CloudFormation 스택을 생성하려면**
[CloudFormation용 앱 생성 템플릿](samples/request-validation-tutorial-cli.zip)을 다운로드하고 압축을 해제합니다.
다음 자습서를 완료하려면 [AWS Command Line Interface(AWS CLI) 버전 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)가 필요합니다.
긴 명령의 경우 이스케이프 문자(`\`)를 사용하여 명령을 여러 행으로 분할합니다.
**참고**
Windows에서는 일반적으로 사용하는 일부 Bash CLI 명령(예: `zip`)은 운영 체제의 기본 제공 터미널에서 지원되지 않습니다. Ubuntu와 Bash의 Windows 통합 버전을 가져오려면 [Linux용 Windows Subsystem을 설치](https://learn.microsoft.com/en-us/windows/wsl/install)합니다. 이 안내서의 예제 CLI 명령은 Linux 형식을 사용합니다. Windows CLI를 사용하는 경우 인라인 JSON 문서를 포함하는 명령의 형식을 다시 지정해야 합니다.
1. 다음 명령을 사용하여 CloudFormation 스택을 생성합니다.
```
aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation은 템플릿에 지정된 리소스를 프로비저닝합니다. 리소스 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 다음 명령을 실행하여 CloudFormation 스택의 상태를 확인합니다.
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli
```
1. CloudFormation 스택의 상태가 `StackStatus: "CREATE_COMPLETE"`이면 다음 명령을 사용하여 향후 단계에 대한 관련 출력 값을 검색합니다.
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
출력 값은 다음과 같습니다.
+ APIID는 API의 ID입니다. 이 자습서에서 API ID는 `abc123`입니다.
+ ResourceId는 `GET` 및 `POST` 메서드가 노출되는 검사기 리소스의 ID입니다. 이 자습서에서 리소스 ID는 `efg456`입니다.
**요청 검사기를 생성하고 모델을 가져오는 방법**
1. AWS CLI로 요청 확인을 사용하려면 검사기가 필요합니다. 다음 명령을 사용하여 요청 파라미터만 확인하는 검사기를 만듭니다.
```
aws apigateway create-request-validator --rest-api-id abc123 \
--no-validate-request-body \
--validate-request-parameters \
--name params-only
```
`params-only` 검사기의 ID를 기록해 둡니다.
1. 다음 명령을 사용하여 요청 본문만 확인하는 검사기를 만듭니다.
```
aws apigateway create-request-validator --rest-api-id abc123 \
--validate-request-body \
--no-validate-request-parameters \
--name body-only
```
`body-only` 검사기의 ID를 기록해 둡니다.
1. 수신 요청의 본문에서 요청 확인을 사용하려면 모델이 필요합니다. 다음 명령을 사용하여 모델을 가져옵니다.
```
aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}'
```
일치하는 콘텐츠 유형이 없는 경우 요청 확인이 수행되지 않습니다. 콘텐츠 유형에 관계없이 동일한 모델을 사용하려면 `$default`을(를) 키로 지정합니다.
**`GET` 및 `POST` 메서드를 생성하는 방법**
1. 다음 명령을 사용하여 `/validate` 리소스에 `GET` HTTP 메서드를 추가합니다. 이 명령은 `GET` 메서드를 만들고 `params-only` 검사기를 추가하며 필요에 따라 `petType` 쿼리 문자열을 설정합니다.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--authorization-type "NONE" \
--request-validator-id aaa111 \
--request-parameters "method.request.querystring.petType=true"
```
다음 명령을 사용하여 `/validate` 리소스에 `POST` HTTP 메서드를 추가합니다. 이 명령은 `POST` 메서드를 만들고 `body-only` 검사기를 추가하며 모델을 본문 전용 검사기에 연결합니다.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
--request-validator-id bbb222 \
--request-models 'application/json'=PetStoreModel
```
1. 다음 명령을 사용하여 `GET /validate` 메서드의 `200 OK` 응답을 설정합니다.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200
```
다음 명령을 사용하여 `POST /validate` 메서드의 `200 OK` 응답을 설정합니다.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 다음 명령을 사용하여 `GET /validation` 메서드에 지정된 HTTP 엔드포인트로 `Integration`을 설정합니다.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--type HTTP \
--integration-http-method GET \
--request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
다음 명령을 사용하여 `POST /validation` 메서드에 지정된 HTTP 엔드포인트로 `Integration`을 설정합니다.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
1. 다음 명령을 사용하여 `GET /validation` 메서드 통합 응답을 설정합니다.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456\
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
다음 명령을 사용하여 `POST /validation` 메서드 통합 응답을 설정합니다.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern ""
```
**API를 테스트하려면**
1. 쿼리 문자열에 대한 요청 확인을 수행할 `GET` 메서드를 테스트하려면 다음 명령을 사용합니다.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--path-with-query-string '/validate?petType=dog'
```
결과는 `200 OK` 및 반려견 목록을 반환합니다.
1. `petType` 쿼리 문자열을 포함하지 않고 테스트하려면 다음 명령을 사용합니다.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
결과는 `400` 오류를 반환합니다.
1. 요청 본문에 대한 요청 확인을 수행할 `POST` 메서드를 테스트하려면 다음 명령을 사용합니다.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'
```
결과는 `200 OK` 및 성공 메시지를 반환합니다.
1. 다음 명령을 사용하여 잘못된 본문을 사용하여 테스트합니다.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }'
```
반려견의 가격이 모델에서 정의한 최고 가격을 초과하므로 결과에 `400` 오류가 반환됩니다.
**CloudFormation 스택을 삭제하려면**
+ 다음 명령을 사용하여 CloudFormation 리소스를 삭제합니다.
```
aws cloudformation delete-stack --stack-name request-validation-tutorial-cli
```
## OpenAPI 정의를 사용하여 기본 요청 확인 설정
요청의 어느 부분을 확인할지 선택하기 위해 [x-amazon-apigateway-request-validators.requestValidator 객체](api-gateway-swagger-extensions-request-validators.requestValidator.md) 객체 세트를 [x-amazon-apigateway-request-validators 객체](api-gateway-swagger-extensions-request-validators.md) 맵에 지정하여 API 수준에서 요청 검사기를 선언할 수 있습니다. 예시 OpenAPI 정의에는 두 가지 검사기가 있습니다.
+ `RequestBodyModel` 데이터 모델을 사용하여 본문과 파라미터를 모두 확인하는 `all` 검사기
`RequestBodyModel` 데이터 모델은 입력 JSON 객체가 `name`, `type` 및 `price` 속성을 포함할 것을 요구합니다. `name` 속성은 임의의 문자열이 될 수 있으며, `type`은 지정된 열거 필드(`["dog", "cat", "fish"]`) 중 하나여야 하고, `price`는 25\$1500 사이여야 합니다. `id` 파라미터는 필요하지 않습니다.
+ 파라미터만 확인하는 `param-only` 검사기
API의 모든 메서드에 대해 요청 검사기를 활성화하려면 API OpenAPI 정의의 API 수준에서 [x-amazon-apigateway-request-validator 속성](api-gateway-swagger-extensions-request-validator.md) 속성을 지정합니다. 예시 OpenAPI 정의의 경우, 달리 재정의되지 않는 한 `all` 검사기가 모든 API 메서드에 사용됩니다. 모델을 사용하여 본문을 확인할 때 일치하는 콘텐츠 유형이 없으면 요청 확인이 수행되지 않습니다. 콘텐츠 유형에 관계없이 동일한 모델을 사용하려면 `$default`을(를) 키로 지정합니다.
개별 메서드에 대해 요청 검사기를 활성화하려면 메서드 수준에서 `x-amazon-apigateway-request-validator` 속성을 지정합니다. 예시의 OpenAPI 정의에서는 `param-only` 검사기가 `GET` 메서드의 `all` 검사기를 덮어씁니다.
OpenAPI 예시를 API Gateway로 가져오려면 [리전 API를 API Gateway로 가져오기](import-export-api-endpoints.md) 또는 [엣지 최적화된 API를 API Gateway로 가져오기](import-edge-optimized-api.md)에 대한 다음 지침을 참조하세요.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ReqValidators Sample",
"version" : "1.0.0"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "/v1"
}
}
} ],
"paths" : {
"/validation" : {
"get" : {
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RequestBodyModel"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"RequestBodyModel" : {
"required" : [ "name", "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"maximum" : 500.0,
"minimum" : 25.0,
"type" : "number"
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Error"
}
},
"Error" : {
"type" : "object"
}
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "1.0.0",
"title" : "ReqValidators Sample"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/validation" : {
"get" : {
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"consumes" : [ "application/json" ],
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"type" : "string"
}, {
"in" : "body",
"name" : "RequestBodyModel",
"required" : true,
"schema" : {
"$ref" : "#/definitions/RequestBodyModel"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"definitions" : {
"RequestBodyModel" : {
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Error"
}
},
"Error" : {
"type" : "object"
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
# 기본 요청 검증이 포함된 샘플 API의 AWS CloudFormation 템플릿
다음 CloudFormation 예제 템플릿 정의는 요청 검증이 활성화된 샘플 API를 정의합니다. API는 [PetStore API](http://petstore-demo-endpoint.execute-api.com/petstore/pets)의 하위 집합입니다. `POST` 메서드를 노출시켜 `pets` 모음에 pet을 추가하고, `GET` 메서드를 노출시켜 지정된 유형으로 pet을 쿼리합니다.
두 개의 요청 검사기가 선언되어 있습니다.
**`GETValidator`**
이 검사기는 `GET` 메서드에서 활성화됩니다. API Gateway는 이 검사기를 사용하여 필수 쿼리 파라미터(`q1`)가 수신 요청에 포함되었으며 공백이 아님을 확인할 수 있습니다.
**`POSTValidator`**
이 검사기는 `POST` 메서드에서 활성화됩니다. API Gateway는 이 검사기를 사용하여 콘텐츠 유형이 `application/json`일 때 페이로드 요청 형식이 지정된 `RequestBodyModel`을 준수하는지 확인합니다. 일치하는 콘텐츠 유형이 없는 경우 요청 검증이 수행되지 않습니다. 콘텐츠 유형에 상관없이 동일한 모델을 사용하려면 `$default`를 지정합니다. `RequestBodyModel`에는 pet ID를 정의하는 추가 모델 `RequestBodyModelId`가 포함되어 있습니다.
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: ReqValidatorsSample
RequestBodyModelId:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModelId
properties:
id:
type: integer
RequestBodyModel:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet type, name, price, and ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModel
required:
- price
- name
- type
type: object
properties:
id:
"$ref": !Sub
- 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}'
- Api: !Ref Api
RequestBodyModelId: !Ref RequestBodyModelId
price:
type: number
minimum: 25
maximum: 500
name:
type: string
type:
type: string
enum:
- "dog"
- "cat"
- "fish"
GETValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: params-only
RestApiId: !Ref Api
ValidateRequestBody: False
ValidateRequestParameters: True
POSTValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: body-only
RestApiId: !Ref Api
ValidateRequestBody: True
ValidateRequestParameters: False
ValidationResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'validation'
ValidationMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: GET
AuthorizationType: NONE
RequestValidatorId: !Ref GETValidator
RequestParameters:
method.request.querystring.q1: true
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ValidationMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: POST
AuthorizationType: NONE
RequestValidatorId: !Ref POSTValidator
RequestModels:
application/json : !Ref RequestBodyModel
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: POST
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- ValidationMethodGet
- RequestBodyModel
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# API Gateway에서 REST API의 데이터 변환
**참고**
이 섹션에서는 비프록시 통합에 사용하는 기능에 대해 설명합니다. 그러나 가능하면 REST API에 프록시 통합을 사용하는 것이 좋습니다. 프록시 통합에는 간소화된 통합 설정이 있으며 기존 설정을 손상하지 않고 백엔드와 함께 진화할 수 있습니다. 자세한 내용은 [API Gateway API 통합 유형 선택](api-gateway-api-integration-types.md) 섹션을 참조하세요.
비프록시 통합을 사용하는 경우 API Gateway의 2가지 기능을 사용하여 메서드 요청과 통합 응답을 변환할 수 있습니다. 통합 요청 페이로드와 다른 페이로드 형식을 사용하는 경우 메서드 요청을 변환할 수 있습니다. 메서드 응답에서 반환해야 하는 형식과 다른 페이로드 형식을 반환하는 경우 통합 응답을 변환할 수 있습니다. 요청 수명 주기에 대한 자세한 내용은 [REST API에 대한 리소스 예제](rest-api-develop.md#rest-api-develop-example) 섹션을 참조하시기 바랍니다.
다음 예제는 `"x-version:beta"` 헤더의 경우 `x-version` 헤더 파라미터가 `app-version` 헤더 파라미터로 변환되는 데이터 변환을 보여줍니다. `x-version`에서 `app-version`으로의 데이터 변환은 통합 요청에서 발생합니다. 이렇게 하면 통합 엔드포인트가 변환된 헤더 파라미터 값을 수신합니다. 통합 엔드포인트가 상태 코드를 반환하면 상태 코드가 메서드 응답 전에 `200`에서 `204`로 변환됩니다.
![\[API Gateway 데이터 변환 다이어그램\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/develop-non-proxy.png)
데이터 변환을 만들기 위해 다음 기능을 사용할 수 있습니다.
**파라미터 매핑**
파라미터 매핑에서 통합 요청 URL 경로 파라미터, URL 쿼리 문자열 파라미터 또는 HTTP 헤더 값을 수정할 수 있지만 통합 요청 페이로드를 수정할 수 없습니다. 또한 HTTP 응답 헤더 값을 수정할 수 있습니다. 파라미터 매핑을 사용하여 교차 오리진 리소스 공유(CORS)에 대한 정적 헤더 값을 만듭니다.
프록시 및 비 프록시 통합에 대한 통합 요청에서 파라미터 매핑을 사용할 수 있지만 통합 응답에 파라미터 매핑을 사용하려면 비 프록시 통합이 필요합니다. 파라미터 매핑에는 [Velocity Template Language(VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html)의 스크립팅이 필요하지 않습니다. 자세한 내용은 [API Gateway의 REST API 대한 파라미터 매핑](rest-api-parameter-mapping.md) 섹션을 참조하세요.
**템플릿 변환 매핑**
매핑 템플릿 변환에서 매핑 템플릿을 사용하여 URL 경로 파라미터, URL 쿼리 문자열 파라미터, HTTP 헤더, 통합 요청 또는 통합 응답 본문을 매핑합니다. *매핑 템플릿*이란 [Velocity Template Language(VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html)로 표현된 스크립트로, [JSONPath 표현식](https://goessner.net/articles/JsonPath/)을 사용하여 `Content-type` 헤더 기반 페이로드에 적용됩니다.
매핑 템플릿을 사용하여 다음을 수행할 수 있습니다.
+ Amazon DynamoDB 또는 Lambda 함수 또는 HTTP 엔드포인트와 같은 AWS 서비스와의 통합을 사용하여 전송할 데이터를 선택합니다. 자세한 내용은 [자습서: AWS 서비스에 대한 통합의 통합 요청 및 응답 수정](set-up-data-transformations-in-api-gateway.md) 섹션을 참조하세요.
+ API의 통합 요청 및 통합 응답 파라미터를 조건부로 재정의하고, 새 헤더 값을 만들고, 상태 코드를 재정의합니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 섹션을 참조하세요.
또한 통합 요청 본문에 일치하는 매핑 템플릿이 없는 `Content-type` 헤더가 있는 경우 API의 동작을 지정할 수 있습니다. 통합 패스스루 동작이라고 합니다. 자세한 내용은 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하세요.
## 파라미터 매핑과 매핑 템플릿 변환 중에서 선택
가능하면 파라미터 매핑을 사용하여 데이터를 변환하는 것이 좋습니다. API에서 본문을 변경해야 하거나 수신 통합 요청 또는 통합 응답에 따라 조건부 재정의 및 수정을 수행해야 하고 프록시 통합을 사용할 수 없는 경우 매핑 템플릿 변환을 사용합니다.
# API Gateway의 REST API 대한 파라미터 매핑
**참고**
HTTP API를 사용하는 경우 [API Gateway에서 HTTP API에 대한 API 요청 및 응답 변환](http-api-parameter-mapping.md) 섹션을 참조하시기 바랍니다.
파라미터 매핑에서 요청 또는 응답 파라미터를 매핑합니다. 파라미터 매핑 표현식 또는 정적 값을 사용하여 파라미터를 매핑할 수 있습니다. 매핑 표현식 목록은 [API Gateway의 REST API에 대한 파라미터 매핑 소스 참조](rest-api-parameter-mapping-sources.md) 섹션을 참조하시기 바랍니다. 프록시 및 비 프록시 통합에 대한 통합 요청에서 파라미터 매핑을 사용할 수 있지만 통합 응답에 파라미터 매핑을 사용하려면 비 프록시 통합이 필요합니다.
예를 들어 메서드 요청 헤더 파라미터(`puppies`)를 통합 요청 헤더 파라미터(`DogsAge0`)에 매핑할 수 있습니다. 그런 다음 클라이언트가 API로 `puppies:true` 헤더를 보내면 통합 요청은 요청 헤더(`DogsAge0:true`)를 통합 엔드포인트로 보냅니다. 다음 다이어그램은 이 예제의 요청 수명 주기를 보여줍니다.
![\[요청에 대한 API Gateway 파라미터 매핑 예제 다이어그램\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
API Gateway를 사용하여 이 예제를 만들려면 [예제 1: 메서드 요청 파라미터를 통합 요청 파라미터에 매핑](request-response-data-mappings.md#request-response-data-mappings-example-1) 섹션을 참조하시기 바랍니다.
또 다른 예제로, 통합 응답 헤더 파라미터(`kittens`)를 메서드 응답 헤더 파라미터(`CatsAge0`)에 매핑할 수 있습니다. 그런 다음 통합 엔드포인트가 `kittens:false`를 반환하면 클라이언트는 `CatsAge0:false` 헤더를 수신합니다. 다음 다이어그램은 이 예제의 요청 수명 주기를 보여줍니다.
![\[응답에 대한 API Gateway 파라미터 매핑 예제 다이어그램\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [API Gateway의 REST API에 대한 파라미터 매핑 예제](request-response-data-mappings.md)
+ [API Gateway의 REST API에 대한 파라미터 매핑 소스 참조](rest-api-parameter-mapping-sources.md)
# API Gateway의 REST API에 대한 파라미터 매핑 예제
다음 예제에서는 API Gateway 콘솔, OpenAPI 및 CloudFormation 템플릿을 사용하여 파라미터 매핑 표현식을 만드는 방법을 보여줍니다. 파라미터 매핑을 사용하여 필요한 CORS 헤더를 만드는 방법의 예제는 [API Gateway의 REST API CORS](how-to-cors.md) 섹션을 참조하시기 바랍니다.
## 예제 1: 메서드 요청 파라미터를 통합 요청 파라미터에 매핑
다음 예제에서는 메서드 요청 헤더 파라미터(`puppies`)를 통합 요청 헤더 파라미터(`DogsAge0`)에 매핑합니다.
------
#### [ AWS Management Console ]
**메서드 요청 파라미터 매핑**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 방법을 선택합니다.
메서드에는 비프록시 통합이 있어야 합니다.
1. **메서드 요청 설정** 섹션에서 **편집**을 선택합니다.
1. **HTTP 요청 헤더**를 선택합니다.
1. **헤더 추가(Add header)**를 선택합니다.
1. **이름**에 **puppies**를 입력합니다.
1. **저장**을 선택합니다.
1. **통합 요청** 탭을 선택한 다음 **통합 요청 설정**에서 **편집**을 선택합니다.
AWS Management Console은 `method.request.header.puppies `에서 `puppies`로 파라미터 매핑을 자동으로 추가하지만 통합 엔드포인트에서 예상되는 요청 헤더 파라미터와 일치하도록 **이름**을 변경해야 합니다.
1. **이름**에 **DogsAge0**를 입력합니다.
1. **저장**을 선택합니다.
1. 변경 사항을 적용하려면 API를 재배포합니다.
다음 단계에서는 파라미터 매핑이 성공했는지 확인하는 방법을 보여줍니다.
**(선택 사항) 파라미터 매핑 테스트**
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. 헤더에 **puppies:true**를 입력합니다.
1. **테스트**를 선택합니다.
1. **로그**에 다음과 같은 결과가 표시되어야 합니다.
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
요청 헤더 파라미터가 `puppies`에서 `DogsAge0`으로 변경되었습니다.
------
#### [ CloudFormation ]
이 예제에서는 [본문](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 속성을 사용하여 OpenAPI 정의 파일을 API Gateway로 가져옵니다.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## 예제 2: 여러 메서드 요청 파라미터를 다른 통합 요청 파라미터에 매핑
다음 예제에서는 다중 값 메서드 요청 쿼리 문자열 파라미터(`methodRequestQueryParam`)를 통합 요청 쿼리 문자열 파라미터(`integrationQueryParam`)에 매핑하고 메서드 요청 헤더 파라미터(`methodRequestHeaderParam`)를 통합 요청 경로 파라미터(`integrationPathParam`)에 매핑합니다.
------
#### [ AWS Management Console ]
**메서드 요청 파라미터 매핑**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 방법을 선택합니다.
메서드에는 비프록시 통합이 있어야 합니다.
1. **메서드 요청 설정** 섹션에서 **편집**을 선택합니다.
1. **URL 쿼리 문자열 파라미터**를 선택합니다.
1. **쿼리 문자열 추가(Add query string)**를 선택합니다.
1. **이름**에 **methodRequestQueryParam**를 입력합니다.
1. **HTTP 요청 헤더**를 선택합니다.
1. **헤더 추가(Add header)**를 선택합니다.
1. **이름**에 **methodRequestHeaderParam**를 입력합니다.
1. **저장**을 선택합니다.
1. **통합 요청** 탭을 선택한 다음 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **URL 경로 파라미터**를 선택합니다.
1. **경로 파라미터 추가**를 선택합니다.
1. **이름**에 **integrationPathParam**를 입력합니다.
1. **다음에서 매핑됨**에 **method.request.header.methodRequestHeaderParam**을 입력합니다.
그러면 메서드 요청에서 지정한 메서드 요청 헤더가 새 통합 요청 경로 파라미터에 매핑됩니다.
1. **URL 쿼리 문자열 파라미터**를 선택합니다.
1. **쿼리 문자열 추가(Add query string)**를 선택합니다.
1. **이름**에 **integrationQueryParam**를 입력합니다.
1. **다음에서 매핑됨**에 **method.request.multivaluequerystring.methodRequestQueryParam**을 입력합니다.
그러면 다중 값 쿼리 문자열 파라미터가 새로운 단일 값 통합 요청 쿼리 문자열 파라미터에 매핑됩니다.
1. **저장**을 선택합니다.
1. 변경 사항을 적용하려면 API를 재배포합니다.
------
#### [ CloudFormation ]
이 예제에서는 [본문](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 속성을 사용하여 OpenAPI 정의 파일을 API Gateway로 가져옵니다.
다음 OpenAPI 정의는 HTTP 통합에 대해 다음과 같은 파라미터 매핑을 만듭니다.
+ `methodRequestHeaderParam`이라는 메서드 요청 헤더를 `integrationPathParam`이라는 통합 요청 경로 파라미터로 매핑합니다.
+ `methodRequestQueryParam`이라는 다중 값 메서드 요청 쿼리 문자열은 `integrationQueryParam`이라는 통합 요청 쿼리 문자열에 매핑됩니다.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
다음 OpenAPI 정의는 HTTP 통합에 대해 다음과 같은 파라미터 매핑을 만듭니다.
+ `methodRequestHeaderParam`이라는 메서드 요청 헤더를 `integrationPathParam`이라는 통합 요청 경로 파라미터로 매핑합니다.
+ `methodRequestQueryParam`이라는 다중 값 메서드 요청 쿼리 문자열은 `integrationQueryParam`이라는 통합 요청 쿼리 문자열에 매핑됩니다.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 예제 3: JSON 요청 본문의 필드를 통합 요청 파라미터에 매핑
또한 [JSONPath 표현식](http://goessner.net/articles/JsonPath/index.html#e2)을 사용하여 JSON 요청 본문의 필드에서 통합 요청 파라미터를 매핑할 수 있습니다. 다음 예제에서는 메서드 요청 본문을 `body-header`라는 통합 요청 헤더에 매핑하고 JSON 표현식으로 표현되는 요청 본문의 일부를 `pet-price`라는 통합 요청 헤더에 매핑합니다.
이 예제를 테스트하려면 다음과 같이 가격 범주가 포함된 입력을 제공합니다.
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS Management Console ]
**메서드 요청 파라미터 매핑**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. `POST`, `PUT`, `PATCH` 또는 `ANY` 메서드를 선택합니다.
메서드에는 비프록시 통합이 있어야 합니다.
1. **통합 요청 설정**에서 **편집**을 선택합니다.
1. **요청 헤더 파라미터**를 선택합니다.
1. **요청 헤더 파라미터 추가**를 선택합니다.
1. **이름**에 **body-header**를 입력합니다.
1. **다음에서 매핑됨**에 **method.request.body**을 입력합니다.
그러면 메서드 요청 본문이 새 통합 요청 헤더 파라미터에 매핑됩니다.
1. **요청 헤더 파라미터 추가**를 선택합니다.
1. **이름**에 **pet-price**를 입력합니다.
1. **다음에서 매핑됨**에 ** method.request.body[0].price**을 입력합니다.
그러면 메서드 요청 본문의 일부가 새 통합 요청 헤더 파라미터에 매핑됩니다.
1. **저장**을 선택합니다.
1. 변경 사항을 적용하려면 API를 재배포합니다.
------
#### [ CloudFormation ]
이 예제에서는 [본문](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 속성을 사용하여 OpenAPI 정의 파일을 API Gateway로 가져옵니다.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
다음 OpenAPI 정의는 JSON 요청 본문의 필드에서 통합 요청 파라미터를 매핑합니다.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 예제 4: 통합 응답을 메서드 응답에 매핑
또한 통합 응답을 메서드 응답에 매핑할 수 있습니다. 다음 예제에서는 통합 응답 본문을 `location`이라는 메서드 응답 헤더에 매핑하고, 통합 응답 헤더(`x-app-id`)를 메서드 응답 헤더(`id`)에 매핑하고, 다중 값 통합 응답 헤더(`item`)를 메서드 응답 헤더(`items`)에 매핑합니다.
------
#### [ AWS Management Console ]
**통합 응답 매핑**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 방법을 선택합니다.
메서드에는 비프록시 통합이 있어야 합니다.
1. **메서드 응답** 탭을 선택한 다음 **응답 200**에서 **편집**을 선택합니다.
1. **헤더 이름**에서 **헤더 추가**를 선택합니다.
1. **id**, **item** 및 **location**이라는 헤더 3개를 만듭니다.
1. **저장**을 선택합니다.
1. **통합 응답** 탭을 선택한 다음, **기본값 - 응답**에서 **편집**을 선택합니다.
1. **헤더 매핑** 아래에서 다음을 입력합니다.
1. **id**에 **integration.response.header.x-app-id**를 입력합니다.
1. **항목**에 **integration.response.multivalueheader.item**을 입력합니다.
1. **위치**에 **integration.response.body.redirect.url**을 입력합니다.
1. **저장**을 선택합니다.
1. 변경 사항을 적용하려면 API를 재배포합니다.
------
#### [ CloudFormation ]
이 예제에서는 [본문](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 속성을 사용하여 OpenAPI 정의 파일을 API Gateway로 가져옵니다.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
다음 OpenAPI 정의는 통합 응답을 메서드 응답에 매핑합니다.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# API Gateway의 REST API에 대한 파라미터 매핑 소스 참조
파라미터 매핑을 만들 경우 수정할 메서드 요청 또는 통합 응답 파라미터를 지정하고 이러한 파라미터를 수정하는 방법을 지정합니다.
다음 표에는 매핑할 수 있는 메서드 요청 파라미터와 매핑을 만드는 표현식이 나와 있습니다. 이러한 표현식에서 *name*은 메서드 요청 파라미터의 이름입니다. 예를 들어 요청 헤더 파라미터(`puppies`)를 매핑하려면 `method.request.header.puppies` 표현식을 사용합니다. 표현식은 `'^[a-zA-Z0-9._$-]+$]'` 정규 표현식과 일치해야 합니다. 프록시 및 비 프록시 통합에 대한 통합 요청에서 파라미터 매핑을 사용할 수 있습니다.
| **매핑된 데이터 소스** | **매핑 표현식** |
| --- | --- |
| 메서드 요청 경로 | method.request.path.name |
| 메서드 요청 쿼리 문자열 | method.request.querystring.name |
| 다중 값 메서드 요청 쿼리 문자열 | method.request.multivaluequerystring.name |
| 메서드 요청 헤더 | method.request.header.name |
| 다중 값 메서드 요청 헤더 | method.request.multivalueheader.name |
| 메서드 요청 본문 | method.request.body |
| 메서드 요청 본문(JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION*은 요청 본문의 JSON 필드에 대한 JSONPath 표현식입니다. 자세한 내용은 [JSONPath 표현식](http://goessner.net/articles/JsonPath/index.html#e2)을 참조하시기 바랍니다. |
| 단계 변수 | stageVariables.name |
| 컨텍스트 변수 | `context.name` 이름은 [지원되는 컨텍스트 변수](api-gateway-mapping-template-reference.md#context-variable-reference) 중 하나여야 합니다. |
| 정적 값 | `'static_value'`. *static\$1value*는 문자열 리터럴이며 작은따옴표 쌍으로 묶여야 합니다. 예를 들어 `'https://www.example.com'`입니다. |
다음 표에는 매핑할 수 있는 통합 응답 파라미터와 매핑을 만드는 표현식이 나와 있습니다. 이러한 표현식에서 *name*은 통합 응답 파라미터의 이름입니다. 통합 응답 헤더 또는 통합 응답 본문, \$1context 변수 또는 정적 값에서 메서드 응답 헤더를 매핑할 수 있습니다. 통합 응답에 파라미터 매핑을 사용하려면 비 프록시 통합이 필요합니다.
| 매핑된 데이터 원본 | 매핑 표현식 |
| --- | --- |
| 통합 응답 헤더 | integration.response.header.name |
| 통합 응답 헤더 | integration.response.multivalueheader.name |
| 통합 응답 본문 | integration.response.body |
| 통합 응답 본문(JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION*은 응답 본문의 JSON 필드에 대한 JSONPath 표현식입니다. 자세한 내용은 [JSONPath 표현식](http://goessner.net/articles/JsonPath/index.html#e2)을 참조하시기 바랍니다. |
| 단계 변수 | stageVariables.name |
| 컨텍스트 변수 | `context.name` 이름은 [지원되는 컨텍스트 변수](api-gateway-mapping-template-reference.md#context-variable-reference) 중 하나여야 합니다. |
| 정적 값 | ` 'static_value'` *static\$1value*는 문자열 리터럴이며 작은따옴표 쌍으로 묶여야 합니다. 예를 들어 `'https://www.example.com'`입니다. |
# API Gateway에서 REST API의 데이터 변환 매핑
매핑 템플릿 변환은 매핑 템플릿을 사용하여 통합 요청 또는 통합 응답을 수정합니다. *매핑 템플릿*이란 [Velocity Template Language(VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html)로 표현된 스크립트로, [JSONPath](https://goessner.net/articles/JsonPath/)를 사용하여 `Content-type` 헤더 기반 페이로드에 적용됩니다. 매핑 템플릿 변환을 사용할 경우 매핑 템플릿을 사용합니다. 이 섹션에서는 매핑 템플릿과 관련된 개념 정보를 설명합니다.
다음 다이어그램은 PetStore 통합 엔드포인트와 통합된 `POST /pets` 리소스의 요청 수명 주기를 보여줍니다. 이 API에서 사용자는 반려동물에 대한 데이터를 전송하고 통합 엔드포인트는 반려동물과 관련된 입양 요금을 반환합니다. 이 요청 수명 주기에서 매핑 템플릿 변환은 요청 본문을 통합 엔드포인트로 필터링하고 통합 엔드포인트에서 응답 본문을 필터링합니다.
![\[요청 수명 주기 예제\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/mapping-template-transforms.png)
다음 섹션에서는 요청 및 응답 수명 주기를 설명합니다.
## 메서드 요청 및 통합 요청
이전 예제에서 메서드 요청으로 전송된 요청 본문인 경우:
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
이 요청 본문은 통합 엔드포인트에서 사용할 올바른 형식이 아니므로 API Gateway는 매핑 템플릿 변환을 수행합니다. API Gateway는 콘텐츠 유형 `application/json`에 대해 정의된 매핑 템플릿이 있으므로 매핑 템플릿 변환만 수행합니다. 콘텐츠 유형에 대한 매핑 템플릿을 정의하지 않으면 기본적으로 API Gateway는 통합 요청을 통해 본문을 통합 엔드포인트로 전달합니다. 이 동작을 수정하려면 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하시기 바랍니다.
다음 매핑 템플릿은 통합 엔드포인트로 전송되기 전에 통합 요청의 메서드 요청 데이터를 변환합니다.
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. `$inputRoot` 변수는 이전 단원에서 다룬 원본 JSON 데이터의 루트 객체를 나타냅니다. 지시어는 `#` 기호로 시작됩니다.
1. `dog`는 사용자의 `id`와 문자열 값의 연결입니다.
1. `Age`는 메서드 요청 본문에서 가져온 것입니다.
그런 다음, 다음 출력이 통합 엔드포인트로 전달됩니다.
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## 통합 응답 및 메서드 응답
통합 엔드포인트에 대한 요청이 성공하면 엔드포인트는 API Gateway의 통합 응답에 응답을 보냅니다. 다음은 통합 엔드포인트의 예제 출력 데이터입니다.
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
메서드 응답은 통합 응답에서 반환되는 것과 다른 페이로드를 예상합니다. API Gateway는 매핑 템플릿 변환을 수행합니다. API Gateway는 콘텐츠 유형 `application/json`에 대해 정의된 매핑 템플릿이 있으므로 매핑 템플릿 변환만 수행합니다. 콘텐츠 유형에 대한 매핑 템플릿을 정의하지 않으면 기본적으로 API Gateway는 메서드 응답을 통해 통합 응답으로 본문을 전달합니다. 이 동작을 수정하려면 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하시기 바랍니다.
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
다음은 메서드 응답으로 전송된 출력입니다.
```
{"adoptionFee": 19.95}
```
그러면 예제 매핑 템플릿 변환이 완료됩니다. 가능하면 매핑 템플릿 변환을 사용하는 대신 프록시 통합을 사용하여 데이터를 변환하는 것이 좋습니다. 자세한 내용은 [API Gateway API 통합 유형 선택](api-gateway-api-integration-types.md) 섹션을 참조하세요.
# API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작
메서드 요청에 페이로드가 있고 `Content-Type` 헤더에 대해 정의된 매핑 템플릿이 없는 경우 변환 없이 통합 요청을 통해 클라이언트가 제공한 요청 페이로드를 백엔드로 전달하도록 선택할 수 있습니다. 이 프로세스를 통합 패스스루라고 합니다.
수신 요청의 실제 패스스루 동작은 이 설정에 따라 결정됩니다. 여기에는 다음과 같은 세 가지 옵션이 있습니다.
**요청 Content-Type 헤더와 일치하는 템플릿이 없는 경우**
메서드 요청 콘텐츠 유형이 매핑 템플릿과 연결된 콘텐츠 유형 중 일치하지 않는 경우 메서드 요청 본문이 변환 없이 통합 요청을 지나 백엔드에 전달되도록 하려면 이 옵션을 선택합니다.
API Gateway API를 호출하는 경우 이 옵션을 선택하려면 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)에서 `WHEN_NO_MATCH`를 `passthroughBehavior` 속성 값으로 설정하면 됩니다.
**정의된 템플릿이 없는 경우(권장)**
매핑 템플릿이 통합 요청에 정의되어 있지 않을 때 메서드 요청 본문이 변환 없이 통합 요청을 지나 벡엔드에 전달되도록 하려면 이 옵션을 선택합니다. 이 옵션을 선택할 때 템플릿이 정의되어 있는 경우 정의된 매핑 템플릿과 일치하지 않은 페이로드와 콘텐츠 유형이 있는 메서드 요청은 HTTP 415 미지원 미디어 유형 응답과 함께 거부됩니다.
API Gateway API를 호출하는 경우 이 옵션을 선택하려면 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)에서 `WHEN_NO_TEMPLATES`를 `passthroughBehavior` 속성 값으로 설정하면 됩니다.
**없음**
매핑 템플릿이 통합 요청에 정의되어 있지 않을 때 메서드 요청 본문이 변환 없이 통합 요청을 지나 벡엔드에 전달되지 않도록 하려면 이 옵션을 선택합니다. 이 옵션을 선택할 때 템플릿이 정의되어 있는 경우 매핑되지 않은 콘텐츠 유형의 메서드 요청은 HTTP 415 미지원 미디어 유형 응답과 함께 거부됩니다.
API Gateway API를 호출하는 경우 이 옵션을 선택하려면 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)에서 `NEVER`를 `passthroughBehavior` 속성 값으로 설정하면 됩니다.
다음 예제에서는 가능한 패스스루 동작을 설명합니다.
예제 1: 하나의 매핑 템플릿이 `application/json` 콘텐츠 유형에 대한 통합 요청에 정의되어 있습니다.
| 콘텐츠 유형 | 패스스루 옵션 | 동작 |
| --- | --- | --- |
| 없음 API Gateway의 기본값은 `application/json`입니다. | WHEN\$1NO\$1MATCH | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
| 없음 API Gateway의 기본값은 `application/json`입니다. | WHEN\$1NO\$1TEMPLATES | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
| 없음 API Gateway의 기본값은 `application/json`입니다. | NEVER | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
| application/json | WHEN\$1NO\$1MATCH | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
| application/json | WHEN\$1NO\$1TEMPLATES | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
| application/json | NEVER | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
| application/xml | WHEN\$1NO\$1MATCH | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| application/xml | WHEN\$1NO\$1TEMPLATES | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
| application/xml | NEVER | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
예제 2: 하나의 매핑 템플릿이 `application/xml` 콘텐츠 유형에 대한 통합 요청에 정의되어 있습니다.
| 콘텐츠 유형 | 패스스루 옵션 | 동작 |
| --- | --- | --- |
| 없음 API Gateway의 기본값은 `application/json`입니다. | WHEN\$1NO\$1MATCH | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| 없음 API Gateway의 기본값은 `application/json`입니다. | WHEN\$1NO\$1TEMPLATES | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
| 없음 API Gateway의 기본값은 `application/json`입니다. | NEVER | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
| application/json | WHEN\$1NO\$1MATCH | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| application/json | WHEN\$1NO\$1TEMPLATES | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
| application/json | NEVER | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
| application/xml | WHEN\$1NO\$1MATCH | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
| application/xml | WHEN\$1NO\$1TEMPLATES | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
| application/xml | NEVER | 템플릿을 사용하여 요청 페이로드가 변환됩니다. |
예제 3: 통합 요청에 매핑 템플릿이 정의되지 않았습니다.
| 콘텐츠 유형 | 패스스루 옵션 | 동작 |
| --- | --- | --- |
| 없음 API Gateway의 기본값은 `application/json`입니다. | WHEN\$1NO\$1MATCH | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| 없음 API Gateway의 기본값은 `application/json`입니다. | WHEN\$1NO\$1TEMPLATES | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| 없음 API Gateway의 기본값은 `application/json`입니다. | NEVER | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
| application/json | WHEN\$1NO\$1MATCH | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| application/json | WHEN\$1NO\$1TEMPLATES | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| application/json | NEVER | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
| application/xml | WHEN\$1NO\$1MATCH | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| application/xml | WHEN\$1NO\$1TEMPLATES | 요청 페이로드가 변환되지 않고 백엔드로 그대로 전송됩니다. |
| application/xml | NEVER | 요청이 HTTP 415 Unsupported Media Type 응답과 함께 거부됩니다. |
# API Gateway의 REST API에 대한 추가 매핑 템플릿 예제
다음 예제는 매핑 템플릿을 사용하여 통합 요청 및 통합 응답 데이터를 변환하는 API Gateway의 사진 앨범 API를 보여줍니다. 또한 데이터 모델을 사용하여 메서드 요청 및 통합 응답 페이로드를 정의합니다. 데이터 모델에 대한 자세한 내용은 [REST API에 대한 데이터 모델](models-mappings-models.md) 섹션을 참조합니다.
## 메서드 요청 및 통합 요청
다음은 메서드 요청 본문을 정의하는 모델입니다. 이 입력 모델에는 한 장의 사진을 업로드해야 하며 각 페이지당 사진 수가 최소 10장으로 지정되어 있습니다. 이 입력 모델을 사용하여 SDK를 생성하거나 API에 대한 요청 확인을 사용할 수 있습니다. 요청 검증을 사용하는 동안 메서드 요청 본문이 모델의 데이터 구조를 준수하지 않으면 API Gateway에서 요청이 실패됩니다.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
다음은 이전 데이터 모델의 데이터 구조를 준수하는 메서드 요청 본문의 예제입니다.
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
이 예제에서는 클라이언트가 이전 메서드 요청 본문을 제출한 경우 이 매핑 템플릿은 통합 엔드포인트에 필요한 형식과 일치하도록 페이로드를 변환합니다.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
다음 예제는 변환의 출력 데이터입니다.
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
이 데이터는 통합 요청으로 전송된 다음, 통합 엔드포인트로 전송됩니다.
## 통합 응답 및 메서드 응답
다음은 통합 엔드포인트의 사진 데이터에 대한 예제 출력 모델입니다. API에 유형이 엄격하게 지정된 SDK를 생성할 때 필수인 메서드 응답 모델에 이 모델을 사용할 수 있습니다. 이를 통해 출력은 Java 또는 Objective-C의 적절한 클래스에 캐스팅됩니다.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
통합 엔드포인트는 이 모델의 데이터 구조를 준수하는 응답으로 응답을 반환하지 않을 수 있습니다. 예를 들어 통합 응답은 다음과 같을 수 있습니다.
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
다음 예제 매핑 템플릿은 통합 응답 데이터를 메서드 응답에서 기대하는 형식으로 변환합니다.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
다음 예제는 변환의 출력 데이터입니다.
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
이 데이터는 메서드 응답으로 전송된 다음 클라이언트로 다시 전송됩니다.
# API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의
매핑 템플릿 변환을 사용하여 모든 유형의 요청 파라미터, 응답 헤더 또는 응답 상태 코드를 재정의할 수 있습니다. 매핑 템플릿을 사용하려면 다음과 같이 합니다.
+ 다대일 파라미터 매핑 수행
+ 표준 API Gateway 매핑이 적용된 후 파라미터 재정의
+ 본문 내용이나 기타 파라미터 값을 기반으로 파라미터를 조건부로 매핑
+ 프로그래밍 방식으로 새 파라미터 생성
+ 통합 엔드포인트에서 반환한 상태 코드 재정의
재정의는 최종입니다. 각 파라미터에 한 번만 재정의를 적용할 수 있습니다. 같은 파라미터에 여러 번 재정의를 시도하면 API Gateway에서 `5XX` 응답을 반환합니다. 템플릿에서 같은 파라미터를 여러 번 재정의해야 할 경우에는 변수를 하나 생성하여 템플릿 마지막에 재정의를 적용하는 것이 좋습니다. 전체 템플릿을 구문 분석한 후에만 템플릿이 적용됩니다.
## 예제 1: 통합 본문을 기반으로 상태 코드 재정의
다음 예제에서는 [예제 API](api-gateway-create-api-from-example.md)를 사용하여 통합 응답 본문을 기반으로 상태 코드를 재정의합니다.
------
#### [ AWS Management Console ]
**통합 응답 본문을 기반으로 상태 코드 재정의**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. **API 생성**을 선택합니다.
1. **REST API**에서 **빌드**를 선택합니다.
1. **API 세부 정보**에서 **예제 API**를 선택합니다.
1. **API 생성**을 선택합니다.
API Gateway는 예제 반려동물 저장소 API를 만듭니다. 반려동물에 대한 정보를 검색하려면 `GET /pets/{petId}`의 API 메서드 요청을 사용합니다. 여기서 `{petId}`는 반려동물의 ID 번호에 해당하는 경로 파라미터입니다.
이 예제에서는 오류 조건을 탐지했을 때 `GET` 메서드의 응답 코드를 `400`으로 재정의합니다.
1. **리소스** 트리에서, `/{petId}` 아래의 `GET` 메서드를 선택합니다.
1. 먼저 API의 현재 구현을 테스트합니다.
**테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. **petId**에 **-1**을 입력한 다음 **테스트**를 선택합니다.
**응답 본문**은 범위를 벗어난 오류를 가리킵니다.
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
또한 **로그** 아래의 마지막 줄은 `Method completed with status: 200`으로 끝납니다.
통합이 성공적으로 완료되었지만 오류가 발생했습니다. 이제 통합 응답을 기반으로 상태 코드를 재정의합니다.
1. **통합 응답** 탭의 **기본값 - 응답**에서 **편집**을 선택합니다.
1. **매핑 템플릿**을 선택합니다.
1. **매핑 템플릿 추가(Add mapping template)**를 선택합니다.
1. **콘텐츠 유형**에 **application/json**을 입력합니다.
1. **템플릿 본문**에 다음을 입력합니다.
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
이 매핑 템플릿은 통합 응답에 `error` 문자열이 포함된 경우 `$context.responseOverride.status` 변수를 사용하여 상태 코드를 로 `400`으로 재정의합니다.
1. **저장**을 선택합니다.
1. **테스트** 탭을 선택합니다.
1. **petId**에 **-1**을 입력합니다.
1. 결과에서 **응답 본문(Response Body)**은 범위 밖 오류를 가리킵니다.
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
그러나 **로그** 아래의 마지막 줄은 이제 `Method completed with status: 400`으로 끝납니다.
------
#### [ CloudFormation ]
이 예제에서는 [본문](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 속성을 사용하여 OpenAPI 정의 파일을 API Gateway로 가져옵니다.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
다음 OpenAPI 정의는 `GET pets/{petId}` 리소스를 만들고 통합 본문을 기반으로 상태 코드를 재정의합니다.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## 예제 2: 요청 헤더 재정의 및 새 헤더 만들기
다음 예제에서는 [예제 API](api-gateway-create-api-from-example.md)를 사용하여 요청 헤더를 재정의하고 새 헤더를 만듭니다.
------
#### [ AWS Management Console ]
**새 헤더를 만들어 메서드의 요청 헤더 재정의**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 이전 자습서에서 만든 예제 API를 선택합니다. API의 이름은 **PetStore**여야 합니다.
1. **리소스** 트리에서, `/pet` 아래의 `GET` 메서드를 선택합니다.
1. **메서드 요청** 탭의 **메서드 요청 설정**에서 **편집**을 선택합니다.
1. **HTTP 요청 헤더**를 선택한 다음, **헤더 추가**를 선택합니다.
1. **이름**에 **header1**를 입력합니다.
1. **헤더 추가**를 선택한 다음 **header2**라는 두 번째 헤더를 생성합니다.
1. **저장**을 선택합니다.
이제 매핑 템플릿을 사용하여 이러한 헤더를 하나의 헤더 값으로 결합합니다.
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **요청 본문 패스스루**에서 **정의된 템플릿이 없는 경우(권장)**를 선택합니다.
1. **매핑 템플릿**을 선택한 후 다음을 수행합니다.
1. **매핑 템플릿 추가(Add mapping template)**를 선택합니다.
1. **콘텐츠 유형**에 **application/json**을 입력합니다.
1. **템플릿 본문**에 다음을 입력합니다.
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
이 매핑 템플릿은 `pets` 문자열로 `header1`을 재정의하고 `header1` 및 `header2`를 결합하는 `$header3Value`라는 다중 값 헤더를 만듭니다.
1. **저장**을 선택합니다.
1. **테스트** 탭을 선택합니다.
1. **헤더**에서 다음 코드를 복사합니다.
```
header1:header1Val
header2:header2Val
```
1. **테스트**를 선택합니다.
**로그**에 다음 텍스트가 포함된 항목이 보입니다.
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
이 예제에서는 [본문](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 속성을 사용하여 OpenAPI 정의 파일을 API Gateway로 가져옵니다.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
다음 OpenAPI 정의는 `GET pets` 리소스를 만들고 요청 헤더를 재정의하고 새 헤더를 만듭니다.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
매핑 템플릿 재정의를 사용하려면 다음 `$context` 변수 중 하나 이상을 추가합니다. `$context` 변수 목록은 [데이터 변환용 컨텍스트 변수](api-gateway-mapping-template-reference.md#context-variable-reference) 섹션을 참조하시기 바랍니다.
# 자습서: AWS 서비스에 대한 통합의 통합 요청 및 응답 수정
다음 자습서에서는 콘솔과 AWS CLI를 사용하여 통합 요청 및 응답을 변환하도록 매핑 템플릿을 설정하기 위해 매핑 템플릿 변환을 사용하는 방법을 보여줍니다.
**Topics**
+ [API Gateway 콘솔을 사용하여 데이터 변환 설정](#mapping-example-console)
+ [AWS CLI를 사용하여 데이터 변환 설정](#mapping-example-cli)
+ [완성된 데이터 변환 CloudFormation 템플릿](#api-gateway-data-transformations-full-cfn-stack)
## API Gateway 콘솔을 사용하여 데이터 변환 설정
이 자습서에서는 .zip 파일([data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip))을 사용하여 불완전한 API 및 DynamoDB 테이블을 생성합니다. 이 불완전한 API에는 `GET` 및 `POST` 메서드가 포함된 `/pets` 리소스가 있습니다.
+ `GET` 메서드는 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 엔드포인트에서 데이터를 가져옵니다. 출력 데이터는 [API Gateway에서 REST API의 데이터 변환 매핑](models-mappings.md)의 매핑 템플릿에 따라 변환됩니다.
+ `POST` 메서드를 사용하면 사용자가 매핑 템플릿을 사용하여 Amazon DynamoDB 테이블에 `POST` 반려동물 정보를 입력할 수 있습니다.
[CloudFormation용 앱 생성 템플릿](samples/data-transformation-tutorial-console.zip)을 다운로드하고 압축을 해제합니다. 이 템플릿을 사용하여 반려동물 정보와 불완전한 API를 게시하기 위한 DynamoDB 테이블을 생성할 것입니다. API Gateway 콘솔에서 나머지 단계를 완료하게 됩니다.
**CloudFormation 스택을 생성하려면**
1. CloudFormation 콘솔([https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/))을 엽니다.
1. **스택 생성**을 선택한 다음 **새 리소스 사용(표준)**을 선택합니다.
1. **템플릿 지정**에서 **템플릿 파일 업로드**를 선택합니다.
1. 다운로드한 템플릿을 선택합니다.
1. **다음**을 선택합니다.
1. **스택 이름**에 **data-transformation-tutorial-console**을 입력하고 **다음**을 선택합니다.
1. **스택 옵션 구성**에서 **다음**을 선택합니다.
1. **기능**의 경우 CloudFormation이 계정에 IAM 리소스를 생성할 수 있음을 확인합니다.
1. **다음**을 선택한 후 **제출**을 선택합니다.
CloudFormation은 템플릿에 지정된 리소스를 프로비저닝합니다. 리소스 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. CloudFormation 스택 상태가 **CREATE\$1COMPLETE**인 경우 다음 단계로 넘어갈 준비가 된 것입니다.
**`GET` 통합 응답을 테스트하는 방법**
1. **data-transformation-tutorial-console**의 CloudFormation 스택에 있는 **리소스** 탭에서 API의 물리적 ID를 선택합니다.
1. 기본 탐색 창에서 **리소스**를 선택하고 **GET** 메서드를 선택합니다.
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
테스트 결과는 다음과 같습니다.
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
[API Gateway에서 REST API의 데이터 변환 매핑](models-mappings.md)의 매핑 테이블에 따라 이 출력 데이터를 변환합니다.
**`GET` 통합 응답을 변환하는 방법**
1. **통합 응답** 탭을 선택합니다.
현재 정의된 매핑 템플릿이 없으므로 통합 응답은 변환되지 않습니다.
1. **기본값 - 응답**에서 **편집**을 선택합니다.
1. **매핑 템플릿**을 선택한 후 다음을 수행합니다.
1. **매핑 템플릿 추가(Add mapping template)**를 선택합니다.
1. **콘텐츠 유형**에 **application/json**을 입력합니다.
1. **템플릿 본문**에 다음을 입력합니다.
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
**저장**을 선택합니다.
**`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** 메서드를 선택합니다.
1. **통합 요청** 탭을 선택한 다음 **통합 요청 설정**에서 **편집**을 선택합니다.
CloudFormation 템플릿에 일부 통합 요청 필드가 채워져 있습니다.
+ 통합 유형은 AWS 서비스입니다.
+ AWS 서비스는 DynamoDB입니다.
+ HTTP 메서드는 `POST`입니다.
+ 작업은 `PutItem`입니다.
+ API Gateway가 DynamoDB 테이블에 항목을 넣을 수 있도록 하는 실행 역할은 `data-transformation-tutorial-console-APIGatewayRole`입니다. API Gateway가 DynamoDB와 상호 작용하는 데 필요한 최소한의 권한을 가질 수 있도록 하기 위해 CloudFormation이 생성한 역할입니다.
DynamoDB 테이블의 이름이 지정되지 않았습니다. 다음 단계에서 이름을 지정합니다.
1. **요청 본문 패스스루**에서 **없음**을 선택합니다.
이렇게 하면 API는 매핑 템플릿이 없는 Content-Types의 데이터를 거부합니다.
1. **매핑 템플릿**을 선택합니다.
1. **콘텐츠 유형**이 `application/json`으로 설정되어 있습니다. 이는 application/json이 아닌 콘텐츠 유형은 API에서 거부함을 의미합니다. 통합 패스스루 동작에 관한 자세한 정보는 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하세요.
1. 텍스트 편집기에 다음 코드를 입력합니다.
```
{
"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 검증 요청](api-gateway-method-request-validation.md) 섹션을 참조하세요.
1. **저장**을 선택하여 매핑 템플릿을 저장합니다.
**메서드 및 `POST` 메서드의 통합 응답을 추가하는 방법**
CloudFormation이 빈 메서드와 통합 응답을 만들었습니다. 이 응답을 편집하여 자세한 정보를 제공할 수 있습니다. 응답을 편집하는 방법에 대한 자세한 내용은 [API Gateway의 REST API에 대한 파라미터 매핑 예제](request-response-data-mappings.md) 섹션을 참조하세요.
1. **통합 응답** 탭의 **기본값 - 응답**에서 **편집**을 선택합니다.
1. **매핑 템플릿**을 선택한 다음 **매핑 템플릿 추가**를 선택합니다.
1. **Content-type**에 **application/json**을 입력합니다.
1. 코드 편집기에서 다음 출력 매핑 템플릿을 입력하여 출력 메시지를 보냅니다.
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
컨텍스트 변수에 대한 자세한 내용은 [데이터 변환용 컨텍스트 변수](api-gateway-mapping-template-reference.md#context-variable-reference) 섹션을 참조하세요.
1. **저장**을 선택하여 매핑 템플릿을 저장합니다.
**`POST` 메서드 테스트**
**테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
1. 요청 본문에 다음 예를 입력합니다.
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. **테스트**를 선택합니다.
출력에 성공 메시지가 표시되어야 합니다.
[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)에서 DynamoDB 콘솔을 열어 예시 항목이 테이블에 있는지 확인할 수 있습니다.
**CloudFormation 스택을 삭제하려면**
1. CloudFormation 콘솔([https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/))을 엽니다.
1. CloudFormation 스택을 선택합니다.
1. **삭제**를 선택한 다음 해당 선택을 확인합니다.
## AWS CLI를 사용하여 데이터 변환 설정
이 자습서에서는 .zip 파일([data-transformation-tutorial-cli.zip](samples/data-transformation-tutorial-cli.zip))을 사용하여 불완전한 API 및 DynamoDB 테이블을 생성합니다. 이 불완전한 API에는 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 엔드포인트와 통합된 `GET` 메서드가 포함된 `/pets` 리소스가 있습니다. DynamoDB 테이블에 연결할 `POST` 메서드를 생성하고 매핑 템플릿을 사용하여 DynamoDB 테이블에 데이터를 입력합니다.
+ [API Gateway에서 REST API의 데이터 변환 매핑](models-mappings.md)의 매핑 템플릿에 따라 출력 데이터를 변화합니다.
+ 사용자가 매핑 템플릿을 사용하여 Amazon DynamoDB 테이블에 `POST` 반려동물 정보를 입력할 수 있도록 `POST` 메서드를 생성합니다.
**CloudFormation 스택을 생성하려면**
[CloudFormation용 앱 생성 템플릿](samples/data-transformation-tutorial-cli.zip)을 다운로드하고 압축을 해제합니다.
다음 자습서를 완료하려면 [AWS Command Line Interface(AWS CLI) 버전 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)가 필요합니다.
긴 명령의 경우 이스케이프 문자(`\`)를 사용하여 명령을 여러 행으로 분할합니다.
**참고**
Windows에서는 일반적으로 사용하는 일부 Bash CLI 명령(예: `zip`)은 운영 체제의 기본 제공 터미널에서 지원되지 않습니다. Ubuntu와 Bash의 Windows 통합 버전을 가져오려면 [Linux용 Windows Subsystem을 설치](https://learn.microsoft.com/en-us/windows/wsl/install)합니다. 이 안내서의 예제 CLI 명령은 Linux 형식을 사용합니다. Windows CLI를 사용하는 경우 인라인 JSON 문서를 포함하는 명령의 형식을 다시 지정해야 합니다.
1. 다음 명령을 사용하여 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은 템플릿에 지정된 리소스를 프로비저닝합니다. 리소스 프로비저닝을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 다음 명령을 실행하여 CloudFormation 스택의 상태를 확인합니다.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. 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
}
]
```
[API Gateway에서 REST API의 데이터 변환 매핑](models-mappings.md)의 매핑 테이블에 따라 이 출력 데이터를 변환합니다.
**`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" \
```
이 방법을 사용하면 CloudFormation 스택에 생성한 DynamoDB 테이블로 반려동물 정보를 보낼 수 있습니다.
1. 다음 명령을 사용하여 `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\")} }}"}'
```
1. 다음 명령을 사용하여 성공적인 `POST` 메서드 호출에 대한 메서드 응답을 생성합니다.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 다음 명령을 사용하여 성공적인 `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\"}'
```
출력에 성공 메시지가 표시됩니다.
**CloudFormation 스택을 삭제하려면**
+ 다음 명령을 사용하여 CloudFormation 리소스를 삭제합니다.
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## 완성된 데이터 변환 CloudFormation 템플릿
다음 예시는 `GET` 및 `POST` 메서드가 있는 `/pets` 리소스가 포함된 DynamoDB 테이블과 API를 생성하는 완성된 CloudFormation 템플릿입니다.
+ `GET` 메서드는 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 엔드포인트에서 데이터를 가져옵니다. 출력 데이터는 [API Gateway에서 REST API의 데이터 변환 매핑](models-mappings.md)의 매핑 템플릿에 따라 변환됩니다.
+ `POST` 메서드를 사용하면 사용자가 매핑 템플릿을 사용하여 DynamoDB 테이블에 `POST` 반려동물 정보를 입력할 수 있습니다.
### 예제 CloudFormation 템플릿
```
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
```
# API Gateway의 템플릿 변환 매핑에 변수를 사용하는 예제
다음 예제는 매핑 템플릿에서 `$context`, `input` 및 `util` 변수를 사용하는 방법을 보여줍니다. 모의 통합 또는 입력 이벤트를 API Gateway에 반환하는 Lambda 비프록시 통합을 사용할 수 있습니다. 데이터 변환에 지원되는 모든 변수 목록은 [API Gateway의 데이터 변환을 위한 변수](api-gateway-mapping-template-reference.md) 섹션을 참조하시기 바랍니다.
## 예제 1: 여러 `$context` 변수를 통합 엔드포인트에 전달
다음 예제는 받은 `$context` 변수를, 통합 요청 페이로드에서 약간 다른 이름을 가진 백엔드 변수에 매핑하는 매핑 템플릿을 보여 줍니다.
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
이 매핑 템플릿의 출력은 다음과 같아야 합니다.
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
이러한 변수 중 하나가 API 키입니다. 이 예제는 메서드에 API 키가 필요하다는 것을 전제로 합니다.
## 예제 2: 모든 요청 파라미터를 JSON 페이로드를 통해 통합 엔드포인트로 전달
다음 예제에서는 `path`, `querystring` 및 `header` 파라미터를 포함한 모든 요청 파라미터를 JSON 페이로드를 통해 통합 엔드포인트로 전달합니다.
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
요청에 다음 입력 파라미터가 있는 경우:
+ `myparam`이라는 경로 매개변수
+ 쿼리 문자열 파라미터 `querystring1=value1,value2`
+ `"header1" : "value1"` 헤더입니다.
이 매핑 템플릿의 출력은 다음과 같아야 합니다.
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## 예제 3: 메서드 요청의 하위 섹션을 통합 엔드포인트에 전달
다음 예제에서는 `name` 입력 파라미터를 사용하여 `name` 파라미터만 검색하고 `input.json('$')` 입력 파라미터를 사용하여 메서드 요청의 전체 본문을 검색합니다.
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
쿼리 문자열 `name=Bella&type=dog` 파라미터와 다음 본문이 포함된 요청의 경우:
```
{
"Price" : "249.99",
"Age": "6"
}
```
이 매핑 템플릿의 출력은 다음과 같아야 합니다.
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
이 매핑 템플릿은 `type=dog` 쿼리 문자열 파라미터를 제거합니다.
JSON 입력에 이스케이프 처리되지 않은 문자가 포함되어 있고 이 문자가 자바스크립트로 구문 분석할 수 없는 경우 API 게이트웨이에서 400 응답을 반환할 수 있습니다. `$util.escapeJavaScript($input.json('$'))`을 적용하면 JSON 입력을 올바르게 구문 분석할 수 있습니다.
`$util.escapeJavaScript($input.json('$'))`이 적용된 이전 예는 다음과 같습니다.
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
이 경우 이 매핑 템플릿의 출력은 다음과 같아야 합니다.
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## 예제 4: JSONPath 표현식을 사용하여 메서드 요청의 하위 섹션을 통합 엔드포인트에 전달
다음 예제에서는 JSONPath 표현식을 사용하여 요청 본문에서 `name` 입력 파라미터와 `Age`만 검색합니다.
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
쿼리 문자열 `name=Bella&type=dog` 파라미터와 다음 본문이 포함된 요청의 경우:
```
{
"Price" : "249.99",
"Age": "6"
}
```
이 매핑 템플릿의 출력은 다음과 같아야 합니다.
```
{
"name" : "Bella",
"body" : "6"
}
```
이 매핑 템플릿은 본문에서 `type=dog` 쿼리 문자열 파라미터와 `Price` 필드를 제거합니다.
메서드 요청 페이로드에 이스케이프 처리되지 않은 문자가 포함되어 있고 이 문자가 자바스크립트로 구문 분석할 수 없는 경우 API Gateway에서 `400` 응답을 반환할 수 있습니다. `$util.escapeJavaScript()`을 적용하면 JSON 입력을 올바르게 구문 분석할 수 있습니다.
`$util.escapeJavaScript($input.json('$.Age'))`이 적용된 이전 예는 다음과 같습니다.
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
이 경우 이 매핑 템플릿의 출력은 다음과 같아야 합니다.
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## 예제 5: JSONPath 표현식을 사용하여 메서드 요청에 대한 정보를 통합 엔드포인트에 전달
다음 예제에서는 `$input.params()`, `$input.path()` 및 `$input.json()`을 사용하여 메서드 요청에 대한 정보를 통합 엔드포인트로 전송합니다. 이 매핑 템플릿은 `size()` 메서드를 사용하여 목록의 요소 수를 제공합니다.
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
경로 `123` 매개변수와 다음 본문이 포함된 요청의 경우:
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
이 매핑 템플릿의 출력은 다음과 같아야 합니다.
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
메서드 요청 페이로드에 이스케이프 처리되지 않은 문자가 포함되어 있고 이 문자가 자바스크립트로 구문 분석할 수 없는 경우 API Gateway에서 `400` 응답을 반환할 수 있습니다. `$util.escapeJavaScript()`을 적용하면 JSON 입력을 올바르게 구문 분석할 수 있습니다.
`$util.escapeJavaScript($input.json('$.things'))`이 적용된 이전 예는 다음과 같습니다.
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
이 매핑 템플릿의 출력은 다음과 같아야 합니다.
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# API Gateway의 데이터 변환을 위한 변수
파라미터 매핑을 만들 때 컨텍스트 변수를 데이터 소스로 사용할 수 있습니다. 매핑 템플릿 변환을 만들 때 [Velocity Template Language(VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html)로 작성하는 스크립트에서 컨텍스트 변수, 입력 및 유틸리티 변수를 사용할 수 있습니다. 이러한 참조 변수를 사용하는 예제 매핑 템플릿을 알아보려면 [API Gateway의 템플릿 변환 매핑에 변수를 사용하는 예제](api-gateway-mapping-variable-examples.md) 섹션을 참조하시기 바랍니다.
액세스 로깅을 위한 참조 변수 목록을 알아보려면 [API Gateway에 대한 액세스 로깅 변수](api-gateway-variables-for-access-logging.md) 섹션을 참조하시기 바랍니다.
## 데이터 변환용 컨텍스트 변수
데이터 변환에 다음 대소문자 구분 `$context` 변수를 사용할 수 있습니다.
| 파라미터 | 설명 |
| --- | --- |
| \$1context.accountId | API 소유자의 AWS 계정 ID입니다. |
| \$1context.apiId | 식별자 API Gateway가 API에 할당합니다. |
| \$1context.authorizer.claims.property | 메서드 호출자가 성공적으로 인증된 후 Amazon Cognito 사용자 풀에서 반환된 클레임의 속성입니다. 자세한 내용은 [Amazon Cognito 사용자 풀을 권한 부여자로 사용하여 REST API에 대한 액세스 제어](apigateway-integrate-with-cognito.md) 단원을 참조하세요. `$context.authorizer.claims`를 호출하면 null이 반환됩니다. |
| \$1context.authorizer.principalId | 클라이언트가 전송한 토큰과 연결되고 API Gateway Lambda 권한 부여자(이전에는 사용자 지정 권한 부여자라고 함)에서 반환한 보안 주체 사용자 식별입니다. 자세한 내용은 [API Gateway Lambda 권한 부여자 사용](apigateway-use-lambda-authorizer.md) 단원을 참조하세요. |
| \$1context.authorizer.property | API Gateway Lambda 권한 부여자 함수에서 반환된 `context` 맵의 지정된 키-값 페어의 문자열화된 값입니다. 예를 들어, 권한 부여자는 다음 `context` 맵을 반환합니다.
`$context.authorizer.key`를 호출하면 `"value"` 문자열이 반환되고, `$context.authorizer.numKey`를 호출하면 `"1"` 문자열이 반환되고, `$context.authorizer.boolKey`를 호출하면 `"true"` 문자열이 반환됩니다. *속성*의 경우 지원되는 특수 문자는 밑줄 `(_)` 문자뿐입니다. 자세한 내용은 [API Gateway Lambda 권한 부여자 사용](apigateway-use-lambda-authorizer.md) 섹션을 참조하세요. |
| \$1context.awsEndpointRequestId | AWS 엔드포인트의 요청 ID입니다. |
| \$1context.deploymentId | API 배포의 ID입니다. |
| \$1context.domainName | API를 호출하는 데 사용되는 정식 도메인 이름입니다. 이 이름은 수신되는 `Host` 헤더와 동일해야 합니다. |
| \$1context.domainPrefix | `$context.domainName`의 첫 번째 레이블입니다. |
| \$1context.error.message | API Gateway 오류 메시지가 포함된 문자열입니다. 이 변수는 VTL(Velocity Template Language) 엔진 및 액세스 로깅에서 처리하지 않는 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 본문-매핑 템플릿의 간단한 변수 대체에만 사용할 수 있습니다. 자세한 내용은 [CloudWatch 지표로 WebSocket API 실행 모니터링](apigateway-websocket-api-logging.md) 및 [오류 응답을 사용자 지정하도록 게이트웨이 응답 설정](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) 섹션을 참조하세요. |
| \$1context.error.messageString | \$1context.error.message의 따옴표 붙은 값, 즉 "\$1context.error.message"입니다. |
| \$1context.error.responseType | [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)의 [유형](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)입니다. 이 변수는 VTL(Velocity Template Language) 엔진 및 액세스 로깅에서 처리하지 않는 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 본문-매핑 템플릿의 간단한 변수 대체에만 사용할 수 있습니다. 자세한 내용은 [CloudWatch 지표로 WebSocket API 실행 모니터링](apigateway-websocket-api-logging.md) 및 [오류 응답을 사용자 지정하도록 게이트웨이 응답 설정](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) 섹션을 참조하세요. |
| \$1context.error.validationErrorString | 세부적인 검증 오류 메시지를 포함하는 문자열입니다. |
| \$1context.extendedRequestId | API Gateway가 생성하여 API 요청에 할당하는 확장 ID입니다. 확장 요청 ID에는 디버깅 및 문제 해결에 유용한 정보가 포함되어 있습니다. |
| \$1context.httpMethod | 사용된 HTTP 메서드입니다. 유효한 값에는 `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` 및 `PUT`이 있습니다. |
| \$1context.identity.accountId | 요청과 연결된 AWS 계정 ID입니다. |
| \$1context.identity.apiKey | API 키가 필요한 API 메서드의 경우, 이 변수는 메서드 요청과 연결된 API 키입니다. API 키가 필요 없는 메서드의 경우, 이 변수는 null입니다. 자세한 내용은 [API Gateway의 REST API 사용량 계획 및 API 키](api-gateway-api-usage-plans.md) 단원을 참조하세요. |
| \$1context.identity.apiKeyId | API 키가 필요한 API 요청과 연결된 API 키 ID입니다. |
| \$1context.identity.caller | 요청에 서명한 호출자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. |
| \$1context.identity.cognitoAuthenticationProvider | 요청을 작성한 직접 호출자가 사용한 모든 Amazon Cognito 인증 공급자의 쉼표로 구분된 목록입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. 예를 들어, Amazon Cognito 사용자 풀의 자격 증명의 경우 `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 사용 가능한 Amazon Cognito 인증 공급자에 대한 자세한 내용은 Amazon Cognito 개발자 안내서**의 [페더레이션 자격 증명 사용](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)을 참조하세요. |
| \$1context.identity.cognitoAuthenticationType | 요청을 작성한 호출자의 Amazon Cognito 인증 유형입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. 가능한 값에는 인증 자격 증명에 대한 `authenticated` 및 미인증 자격 증명에 대한 `unauthenticated`이(가) 포함됩니다. |
| \$1context.identity.cognitoIdentityId | 요청을 작성한 호출자의 Amazon Cognito 자격 증명 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. |
| \$1context.identity.cognitoIdentityPoolId | 요청을 작성한 호출자의 Amazon Cognito 자격 증명 풀 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. |
| \$1context.identity.principalOrgId | [AWS 조직 ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html)입니다. |
| \$1context.identity.sourceIp | API Gateway 엔드포인트를 요청하는 즉시 TCP 연결의 소스 IP 주소입니다. |
| \$1context.identity.clientCert.clientCertPem | 상호 TLS 인증 시 클라이언트가 제공한 PEM 인코딩된 클라이언트 인증서입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. |
| \$1context.identity.clientCert.subjectDN | 클라이언트가 제공하는 인증서의 주체가 갖는 고유 이름입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. |
| \$1context.identity.clientCert.issuerDN | 클라이언트가 제공하는 인증서의 발행자가 갖는 고유 이름입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. |
| \$1context.identity.clientCert.serialNumber | 인증서의 일련 번호입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. |
| \$1context.identity.clientCert.validity.notBefore | 인증서의 유효 기간이 시작되는 날짜입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. |
| \$1context.identity.clientCert.validity.notAfter | 인증서의 유효 기간이 끝나는 날짜입니다. 클라이언트에서 상호 TLS가 활성화된 사용자 지정 도메인 이름을 사용하여 API에 액세스할 때 제공됩니다. 상호 TLS 인증이 실패할 경우 액세스 로그에만 제공됩니다. |
| \$1context.identity.vpcId | API Gateway 엔드포인트를 요청하는 VPC의 VPC ID입니다. |
| \$1context.identity.vpceId | API Gateway 엔드포인트를 요청하는 VPC 엔드포인트의 VPC 엔드포인트 ID입니다. 프라이빗 API가 있는 경우에만 존재합니다. |
| \$1context.identity.user | 리소스 액세스에 대해 권한을 부여할 사용자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다. |
| \$1context.identity.userAgent | API 호출자의 [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 헤더입니다. |
| \$1context.identity.userArn | 인증 후 식별된 실제 사용자의 ARN(Amazon Resource Name)입니다. 자세한 내용은 [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) 섹션을 참조하세요. |
| \$1context.isCanaryRequest | 요청이 canary로 전달된 경우 `true`, 요청이 canary로 전달되지 않은 경우 `false`를 반환합니다. canary를 활성화한 경우에만 존재합니다. |
| \$1context.path | 요청 경로입니다. 예를 들어 https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child의 비 프록시 요청 URL의 경우, \$1context.path 값은 /\$1stage\$1/root/child입니다. |
| \$1context.protocol | 요청 프로토콜입니다(예: HTTP/1.1). API Gateway API는 HTTP/2 요청을 수락할 수 있지만 API Gateway는 HTTP/1.1을 사용하여 백엔드 통합에 요청을 보냅니다. 따라서 클라이언트가 HTTP/2를 사용하는 요청을 보내더라도 요청 프로토콜은 HTTP/1.1로 기록됩니다. |
| \$1context.requestId | 요청의 ID입니다. 클라이언트는 이 요청 ID를 재정의할 수 있습니다. API Gateway가 생성하는 고유한 요청 ID에 대한 `$context.extendedRequestId`를 사용합니다. |
| \$1context.requestOverride.header.header\$1name | 요청 헤더 재정의입니다. 이 파라미터를 정의하면 **통합 요청(Integration Request)** 창에서 정의한 **HTTP 헤더(HTTP Headers)** 대신에 사용할 헤더가 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. |
| \$1context.requestOverride.path.path\$1name | 요청 경로 재정의입니다. 이 파라미터를 정의하면 **통합 요청(Integration Request)** 창에서 정의한 **URL 경로 파라미터(URL Path Parameters)** 대신에 사용할 요청 경로가 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. |
| \$1context.requestOverride.querystring.querystring\$1name | 요청 쿼리 문자열 재정의입니다. 이 파라미터를 정의하면 **통합 요청(Integration Request)** 창에서 정의한 **URL 쿼리 문자열 파라미터(URL Query String Parameters)** 대신에 사용할 요청 쿼리 문자열이 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. |
| \$1context.responseOverride.header.header\$1name | 응답 헤더 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Response) 창에서 기본 매핑(Default mapping)으로 정의한 응답 헤더(Response header) 대신에 반환할 헤더가 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. |
| \$1context.responseOverride.status | 응답 상태 코드 재정의입니다. 이 파라미터를 정의하면 통합 요청(Integration Response) 창에서 기본 매핑(Default mapping)으로 정의한 메서드 응답 상태(Method response status) 대신에 반환할 상태 코드가 포함됩니다. 자세한 내용은 [API Gateway에서 REST API에 대한 API 요청, 응답 파라미터, 상태 코드 재정의](apigateway-override-request-response-parameters.md) 단원을 참조하세요. |
| \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 형식 요청 시간(dd/MMM/yyyy:HH:mm:ss \$1-hhmm)입니다. |
| \$1context.requestTimeEpoch | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 형식 요청 시간(밀리초)입니다. |
| \$1context.resourceId | API Gateway가 리소스에 할당하는 식별자입니다. |
| \$1context.resourcePath | 리소스에 대한 경로입니다. 예를 들어 `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`의 비 프록시 요청 URI의 경우, `$context.resourcePath` 값은 `/root/child`입니다. 자세한 내용은 [자습서: HTTP 비 프록시 통합을 통해 REST API 생성](api-gateway-create-api-step-by-step.md) 단원을 참조하세요. |
| \$1context.stage | API 요청의 개발 단계입니다(예: `Beta` 또는 `Prod`). |
| \$1context.wafResponseCode | [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html)에서 받은 응답: `WAF_ALLOW` 또는 `WAF_BLOCK`. 스테이지가 웹 ACL과 연결되어 있지 않은 경우 설정되지 않습니다. 자세한 내용은 [API Gateway에서 AWS WAF를 사용하여 REST API 보호](apigateway-control-access-aws-waf.md) 단원을 참조하세요. |
| \$1context.webaclArn | 요청을 허용할지 차단할지 결정하는 데 사용되는 웹 ACL의 전체 ARN입니다. 스테이지가 웹 ACL과 연결되어 있지 않은 경우 설정되지 않습니다. 자세한 내용은 [API Gateway에서 AWS WAF를 사용하여 REST API 보호](apigateway-control-access-aws-waf.md) 섹션을 참조하세요. |
## 입력 변수
다음 대소문자 구분 `$input` 변수를 사용하여 메서드 요청 페이로드 및 메서드 요청 파라미터를 참조할 수 있습니다. 다음과 같은 기능을 사용할 수 있습니다.
| 변수 및 함수 | 설명 |
| --- | --- |
| \$1input.body | 원시 요청 페이로드를 문자열로 반환합니다. `$input.body`를 사용하여 전체 부동 소수점 숫자를 보존할 수 있습니다(예: `10.00`). |
| \$1input.json(x) | 이 함수는 JSONPath 표현식을 평가하고 결과를 JSON 문자열로 반환합니다. 예를 들어, `$input.json('$.pets')`은 `pets` 구조를 나타내는 JSON 문자열을 반환합니다. JSONPath에 대한 자세한 내용은 [JSONPath](https://goessner.net/articles/JsonPath/) 또는 [Java용 JSONPath](https://github.com/json-path/JsonPath)를 참조하세요. |
| \$1input.params() | 모든 요청 파라미터의 맵을 반환합니다. 잠재적인 주입 공격을 방지하기 위해 `$util.escapeJavaScript`을(를) 사용하여 결과를 삭제하는 것이 좋습니다. 요청 삭제를 완벽하게 제어하려면 템플릿 없이 프록시 통합을 사용하고 통합에서 요청 삭제를 처리합니다. |
| \$1input.params(x) | 파라미터 이름 문자열 `x`가 지정된 경로, 쿼리 문자열 또는 헤더 값(순서대로 검색됨)에서 메서드 요청 파라미터 값을 반환합니다. 잠재적인 주입 공격을 방지하기 위해 `$util.escapeJavaScript`을(를) 사용하여 파라미터를 삭제하는 것이 좋습니다. 파라미터 삭제를 완벽하게 제어하려면 템플릿 없이 프록시 통합을 사용하고 통합에서 요청 삭제를 처리합니다. |
| \$1input.path(x) | JSONPath 표현식 문자열 (`x`)을 가져와서 결과의 JSON 객체로 반환합니다. 이를 통해 기본적으로 [Apache Velocity Template Language(VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html)에서 페이로드 요소에 액세스하고 조작할 수 있습니다. 예를 들어, `$input.path('$.pets')` 표현식이 다음과 같은 객체를 반환할 경우:
`$input.path('$.pets').size()`는 을 반환합니다.`"3"` JSONPath에 대한 자세한 내용은 [JSONPath](https://goessner.net/articles/JsonPath/) 또는 [Java용 JSONPath](https://github.com/json-path/JsonPath)를 참조하세요. |
## 단계 변수
메서드 통합에서 다음 단계 변수를 ARN 및 URL의 자리 표시자로 사용할 수 있습니다. 자세한 내용은 [API Gateway에서 REST API용 스테이지 변수 사용](stage-variables.md) 섹션을 참조하세요.
| 구문 | 설명 |
| --- | --- |
| \$1stageVariables.variable\$1name,\$1stageVariables['variable\$1name'] 또는 \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*은 단계 변수 이름을 나타냅니다. |
## 유틸리티 변수
다음 대소문자 구분 `$util` 변수를 사용하여 매핑 탬플릿용 유틸리티 함수를 사용할 수 있습니다. 달리 지정하지 않는 한, 기본 문자 집합은 UTF-8입니다.
| 함수 | 설명 |
| --- | --- |
| \$1util.escapeJavaScript() | JavaScript 문자열 규칙을 사용하여 문자열의 문자를 이스케이프합니다. 이 함수는 일반 작은따옴표(`'`)를 이스케이프된 작은따옴표(`\'`)로 변환합니다. 그러나 이스케이프된 작은따옴표는 JSON에서 유효하지 않습니다. 따라서 이 함수의 결과를 JSON 속성에서 사용할 경우 이스케이프된 작은따옴표(`\'`)를 다시 일반 작은따옴표(`'`)로 변환해야 합니다. 방법은 다음 예제와 같습니다:
|
| \$1util.parseJson() | "문자열화된" JSON을 가져와서 결과의 객체 표현을 반환합니다. 이 함수의 결과를 사용하여 기본적으로 Apache VTL(Velocity Template Language)에서 페이로드 요소에 액세스하고 조작할 수 있습니다. 예를 들어 다음과 같은 페이로드가 있고
|
| \$1util.urlEncode() | 문자열을 "application/x-www-form-urlencoded" 형식으로 변환합니다. |
| \$1util.urlDecode() | "application/x-www-form-urlencoded" 문자열을 디코딩합니다. |
| \$1util.base64Encode() | 데이터를 base64 인코딩 문자열로 인코딩합니다. |
| \$1util.base64Decode() | 데이터를 base64 인코딩 문자열에서 디코딩합니다. |
# API Gateway의 REST API에 대한 게이트웨이 응답
게이트웨이 응답은 API Gateway에서 정의한 응답 유형으로 식별됩니다. 응답은 HTTP 상태 코드, 파라미터 매핑에 지정되는 추가 헤더 집합, 비 [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html) 매핑 템플릿에 의해 생성되는 페이로드 등으로 구성됩니다.
API Gateway REST API에서 게이트웨이 응답은 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)로 표시됩니다. OpenAPI에서 `GatewayResponse` 인스턴스는 [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) 확장으로 설명됩니다.
게이트웨이 응답을 활성화하려면 API 수준에서 [지원되는 응답 유형](supported-gateway-response-types.md)에 대한 게이트웨이 응답을 설정합니다. API Gateway에서 해당 유형의 응답을 반환할 때마다 게이트웨이 응답에 정의된 헤더 매핑 및 페이로드 매핑 템플릿을 적용하여 매핑된 결과가 API 호출자에게 반환됩니다.
다음 섹션에서는 API Gateway 콘솔 및 API Gateway REST API를 사용하여 게이트웨이 응답을 설정하는 방법을 보여줍니다.
## 오류 응답을 사용자 지정하도록 게이트웨이 응답 설정
API Gateway에서 수신 요청을 처리하지 못한 경우 요청을 통합 백엔드에 전달하지 않고 클라이언트에 오류 응답을 반환합니다. 기본적으로 오류 응답에는 오류를 설명하는 짧은 설명이 포함되어 있습니다. 예를 들어 정의되지 않은 API 리소스에 대한 작업을 호출할 경우 `{ "message": "Missing Authentication Token" }` 메시지를 포함하는 오류 응답이 수신됩니다. API Gateway를 처음 사용할 경우 실제로 무엇이 잘못되었는지 이해하기 어려울 수 있습니다.
일부 오류 응답에 대해 API 개발자는 API Gateway를 통해 다양한 형식으로 응답을 반환하도록 사용자 지정할 수 있습니다. `Missing Authentication Token` 예제에서 가능한 원인을 사용하여 원래 응답 페이로드에 힌트를 추가할 수 있습니다. 예를 들면 다음과 같습니다. `{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`.
API가 외부 Exchange와 AWS 클라우드 사이에서 중재할 경우, 통합 요청 또는 통합 응답에 대한 VTL 매핑 템플릿을 사용하여 페이로드를 다른 형식으로 매핑합니다. 하지만 VTL 매핑 템플릿은 성공적인 응답을 포함하는 유효한 요청에 대해서만 작동합니다.
요청이 유효하지 않은 경우 API Gateway에서는 통합을 완전히 무시하고 오류 응답을 반환합니다. 사용자 지정을 사용하여 오류 응답을 Exchange 호환 형식으로 렌더링해야 합니다. 여기서 사용자 지정은 간단한 변수 대체만 지원하는 비 VTL 매핑 템플릿으로 렌더링됩니다.
API Gateway에서 생성된 오류 응답을 API Gateway에서 생성되는 응답으로 일반화하며, 이를 *게이트웨이 응답*이라고 합니다. 이는 API Gateway에서 생성된 응답을 통합 응답과 구별합니다. 게이트웨이 응답 매핑 템플릿에서는 `$context` 변수 값, `$stageVariables` 속성 값 및 메서드 요청 파라미터에 `method.request.param-position.param-name` 형식으로 액세스할 수 있습니다.
`$context` 변수에 대한 자세한 내용은 [데이터 변환용 컨텍스트 변수](api-gateway-mapping-template-reference.md#context-variable-reference) 단원을 참조하십시오. `$stageVariables`에 대한 자세한 내용은 [단계 변수](api-gateway-mapping-template-reference.md#stagevariables-template-reference) 단원을 참조하세요. 메서드 요청 파라미터에 대한 자세한 내용은 [입력 변수](api-gateway-mapping-template-reference.md#input-variable-reference) 단원을 참조하세요.
**Topics**
+ [오류 응답을 사용자 지정하도록 게이트웨이 응답 설정](#customize-gateway-responses)
+ [API Gateway 콘솔을 사용하여 REST API에 대한 게이트웨이 응답 설정](set-up-gateway-response-using-the-console.md)
+ [API Gateway REST API를 사용하여 게이트웨이 응답 설정](set-up-gateway-response-using-the-api.md)
+ [OpenAPI에서 게이트웨이 응답 사용자 지정 설정](set-up-gateway-responses-in-swagger.md)
+ [API Gateway의 게이트웨이 응답 유형](supported-gateway-response-types.md)
# API Gateway 콘솔을 사용하여 REST API에 대한 게이트웨이 응답 설정
다음 예시에서는 API Gateway 콘솔을 사용하여 REST API에 대한 게이트웨이 응답을 설정하는 방법을 보여줍니다.
**API Gateway 콘솔을 사용하여 게이트웨이 응답을 사용자 지정하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 기본 탐색 창에서 **게이트웨이 응답**을 선택합니다.
1. 응답 유형을 선택한 다음 **편집**을 선택합니다. 이 연습에서는 **누락된 인증 토큰**을 예로 들겠습니다.
1. API Gateway가 생성한 **상태 코드**를 변경하여, 사용자 API의 요구 사항에 부합하는 다른 상태 코드를 반환할 수 있습니다. 이 예에서 사용자 지정은 상태 코드를 기본값(`403`)에서 `404`로 변경합니다. 클라이언트가 지원되지 않거나 잘못되어 찾을 수 없는 리소스를 호출할 경우 이 오류 메시지가 발생하기 때문입니다.
1. 사용자 지정 헤더를 반환하려면 **응답 헤더**에서 **헤더 추가**를 선택합니다. 설명을 위해 다음 사용자 지정 헤더를 추가하겠습니다.
```
Access-Control-Allow-Origin:'a.b.c'
x-request-id:method.request.header.x-amzn-RequestId
x-request-path:method.request.path.petId
x-request-query:method.request.querystring.q
```
앞서 본 헤더 매핑에서 정적 도메인 이름(`'a.b.c'`)은 `Allow-Control-Allow-Origin` 헤더에 매핑되어 API에 대한 CORS 액세스를 허용합니다. `x-amzn-RequestId`의 입력 요청 헤더는 응답의 `request-id`에 매핑됩니다. 수신되는 요청의 `petId` 경로 변수는 응답의 `request-path` 헤더에 매핑됩니다. 원래 요청의 `q` 쿼리 파라미터는 응답의 `request-query` 헤더에 매핑됩니다.
1. **응답 템플릿**에서 **콘텐츠 유형**은 `application/json`를 유지하고 **템플릿 본문** 편집기에 다음과 같은 본문 매핑 템플릿을 입력합니다.
```
{
"message":"$context.error.messageString",
"type": "$context.error.responseType",
"statusCode": "'404'",
"stage": "$context.stage",
"resourcePath": "$context.resourcePath",
"stageVariables.a": "$stageVariables.a"
}
```
이 예는 게이트웨이 응답 본문의 속성에 `$context` 및 `$stageVariables` 속성을 매핑하는 방법을 보여줍니다.
1. **변경 사항 저장**을 선택합니다.
1. 새 단계 또는 기존 단계에 API를 배포합니다.
해당 API 메서드의 호출 URL이 `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}`라고 가정하고 다음 CURL 명령을 호출하여 게이트웨이 응답을 테스트합니다.
```
curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1
```
추가적인 쿼리 문자열 파라미터 `q=1`이 API와 호환되지 않기 때문에 지정된 게이트웨이 응답에서 오류가 반환됩니다. 다음과 비슷한 게이트웨이 응답이 표시됩니다.
```
> GET /custErr/pets/5?q=1 HTTP/1.1
Host: o81lxisefl.execute-api.us-east-1.amazonaws.com
User-Agent: curl/7.51.0
Accept: */*
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 334
Connection: keep-alive
Date: Tue, 02 May 2017 03:15:47 GMT
x-amzn-RequestId: 123344566
Access-Control-Allow-Origin: a.b.c
x-amzn-ErrorType: MissingAuthenticationTokenException
header-1: static
x-request-query: 1
x-request-path: 5
X-Cache: Error from cloudfront
Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront)
X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA==
{
"message":"Missing Authentication Token",
"type": MISSING_AUTHENTICATION_TOKEN,
"statusCode": '404',
"stage": custErr,
"resourcePath": /pets/{petId},
"stageVariables.a": a
}
```
앞의 예에서는 API 백엔드가 [Pet Store](http://petstore-demo-endpoint.execute-api.com/petstore/pets)이고 API에 단계 변수, `a`가 정의된 것으로 가정했습니다.
# API Gateway REST API를 사용하여 게이트웨이 응답 설정
API를 생성하고 식별자를 획득한 이후에 API Gateway REST API를 사용하여 게이트웨이 응답을 사용자 지정해야 합니다. API 식별자를 검색하려면 [restapi:gateway-responses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) 링크 관계를 따르고 결과를 검사할 수 있습니다.
**API Gateway REST API를 사용하여 게이트웨이 응답을 사용자 지정하려면**
1. 전체 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 인스턴스를 덮어쓰려면 [gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html) 작업을 호출합니다. URL 경로 파라미터에 원하는 [responseType](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)을 지정하고 요청 페이로드에 [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters) 및 [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseTemplates) 매핑을 제공합니다.
1. `GatewayResponse` 인스턴스의 일부를 업데이트하려면 [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html) 작업을 호출합니다. URL 경로 파라미터에 원하는 `responseType`을 지정하고 요청 페이로드에 원하는 개별 `GatewayResponse` 속성(예: `responseParameters` 또는 `responseTemplates` 매핑)을 제공합니다.
# OpenAPI에서 게이트웨이 응답 사용자 지정 설정
API 루트 수준에서 `x-amazon-apigateway-gateway-responses` 확장을 사용하여 OpenAPI에서 게이트웨이 응답을 사용자 지정할 수 있습니다. 다음 OpenAPI 정의는 `MISSING_AUTHENTICATION_TOKEN` 유형의 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)를 사용자 지정하는 예를 보여줍니다.
```
"x-amazon-apigateway-gateway-responses": {
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.x-request-path": "method.input.params.petId",
"gatewayresponse.header.x-request-query": "method.input.params.q",
"gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'",
"gatewayresponse.header.x-request-header": "method.input.params.Accept"
},
"responseTemplates": {
"application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}"
}
}
```
이 예제의 사용자 지정은 상태 코드를 기본값(`403`)에서 `404`로 변경합니다. 또한 `application/json` 미디어 유형에 대한 헤더 파라미터 네 개와 본문 매핑 템플릿 하나를 추가합니다.
# API Gateway의 게이트웨이 응답 유형
API Gateway에서는 API 개발자가 사용자 지정할 수 있도록 다음과 같은 게이트웨이 응답을 공개합니다.
| 게이트웨이 응답 유형 | 기본 상태 코드 | 설명 |
| --- | --- | --- |
| ACCESS\$1DENIED | 403 | 권한 부여 실패(예: 사용자 지정 또는 Amazon Cognito 권한 부여자가 액세스를 거부한 경우)에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| API\$1CONFIGURATION\$1ERROR | 500 | 유효하지 않은 엔드포인트 주소가 제출된 경우, 이진 지원이 수행될 때 이진 데이터에 대해 base64 디코딩이 실패한 경우, 통합 응답 매핑이 어떤 템플릿과도 일치할 수 없어서 기본 템플릿이 구성되어 있지 않은 경우를 포함하여 유효하지 않은 API 구성에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_5XX`입니다. |
| AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | 사용자 지정 또는 Amazon Cognito 권한 부여자 연결 실패에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_5XX`입니다. |
| AUTHORIZER\$1FAILURE | 500 | 사용자 지정 또는 Amazon Cognito 권한 부여자가 호출자를 인증하지 못한 경우의 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_5XX`입니다. |
| BAD\$1REQUEST\$1PARAMETERS | 400 | 활성화된 요청 검사기에 따라 요청 파라미터를 확인할 수 없는 경우의 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| BAD\$1REQUEST\$1BODY | 400 | 활성화된 요청 검사기에 따라 요청 본문을 확인할 수 없는 경우의 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| DEFAULT\$14XX | Null | 상태 코드가 `4XX`인 지정되지 않은 응답 유형에 대한 기본 게이트웨이 응답입니다. 이 대체 게이트웨이 응답의 상태 코드를 변경하면 모든 다른 `4XX` 응답의 상태 코드가 새 값으로 변경됩니다. 이 상태 코드를 null로 재설정하면 모든 다른 `4XX` 응답의 상태 코드가 원래 값으로 되돌아갑니다. [AWS WAF 사용자 지정 응답](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html)은 사용자 지정 게이트웨이 응답보다 우선합니다. |
| DEFAULT\$15XX | Null | 상태 코드가 `5XX`인 지정되지 않은 응답 유형에 대한 기본 게이트웨이 응답입니다. 이 대체 게이트웨이 응답의 상태 코드를 변경하면 모든 다른 `5XX` 응답의 상태 코드가 새 값으로 변경됩니다. 이 상태 코드를 null로 재설정하면 모든 다른 `5XX` 응답의 상태 코드가 원래 값으로 되돌아갑니다. |
| EXPIRED\$1TOKEN | 403 | AWS 인증 토큰 만료 오류에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| INTEGRATION\$1FAILURE | 504 | 통합 실패 오류에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_5XX`입니다. |
| INTEGRATION\$1TIMEOUT | 504 | 통합 시간 초과 오류에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_5XX`입니다. |
| INVALID\$1API\$1KEY | 403 | API 키를 요구하는 메서드에 대해 제출되는 잘못된 API 키에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| INVALID\$1SIGNATURE | 403 | 잘못된 AWS 서명 오류에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| MISSING\$1AUTHENTICATION\$1TOKEN | 403 | 클라이언트가 지원되지 않는 API 메서드 또는 리소스를 호출하려고 시도하는 경우를 비롯한 누락된 인증 토큰 오류에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| QUOTA\$1EXCEEDED | 429 | 사용량 계획 할당량 초과 오류에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| REQUEST\$1TOO\$1LARGE | 413 | 요청이 너무 큼 오류에 대한 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본값은 `HTTP content length exceeded 10485760 bytes`입니다. |
| RESOURCE\$1NOT\$1FOUND | 404 | API 키 인증 및 권한 부여를 제외하고 API 요청에서 인증 및 권한 부여를 전달한 이후에 API Gateway에서 지정된 리소스를 찾을 수 없는 경우의 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| THROTTLED | 429 | 사용량 계획, 메서드, 단계 또는 계정 수준 조절 한도가 초과한 경우의 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| UNAUTHORIZED | 401 | 사용자 지정 또는 Amazon Cognito 권한 부여자가 호출자를 인증하지 못한 경우의 게이트웨이 응답입니다. |
| UNSUPPORTED\$1MEDIA\$1TYPE | 415 | 엄격한 패스스루 동작을 활성화한 경우에 페이로드가 지원되지 않는 미디어 유형일 때의 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. |
| WAF\$1FILTERED | 403 | 요청이 AWS WAF에 의해 차단될 때의 게이트웨이 응답입니다. 응답 유형이 지정되지 않은 경우 이 응답의 기본 유형은 `DEFAULT_4XX`입니다. [AWS WAF 사용자 지정 응답](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html)은 사용자 지정 게이트웨이 응답보다 우선합니다. |
# API Gateway의 REST API CORS
[CORS(Cross-origin 리소스 공유)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)는 브라우저에서 실행 중인 스크립트에서 시작되는 cross-origin HTTP 요청을 제한하는 브라우저 보안 기능입니다. 자세한 내용은 [CORS란 무엇인가요?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)를 참조하세요.
## CORS 지원 활성화 여부 확인
*cross-origin* HTTP 요청은 다음에 대해 이루어지는 요청입니다.
+ 다른 *도메인*(예: `example.com`에서 `amazondomains.com`으로)
+ 다른 *하위 도메인*(예: `example.com`에서 `petstore.example.com`으로)
+ 다른 *포트*(예: `example.com`에서 `example.com:10777`으로)
+ 다른 *프로토콜*(예: `https://example.com`에서 `http://example.com`으로)
API에 액세스할 수 없고 `Cross-Origin Request Blocked`가 포함된 오류 메시지를 수신하는 경우 CORS를 활성화해야 할 수 있습니다.
Cross-origin HTTP 요청은 *단순* 요청과 *비 단순* 요청의 두 가지 유형으로 나눌 수 있습니다.
## 단순한 요청을 위한 CORS 사용 설정
다음과 같은 모든 조건을 충족하는 HTTP 요청은 *단순* 요청입니다.
+ `GET`, `HEAD`, `POST` 요청만 허용하는 API 리소스에 대해 발행된 요청입니다.
+ `POST` 메서드 요청인 경우 `Origin` 헤더를 포함해야 합니다.
+ 요청 페이로드 콘텐츠 유형이 `text/plain`, `multipart/form-data` 또는 `application/x-www-form-urlencoded`입니다.
+ 요청에 사용자 지정 헤더가 없습니다.
+ [단순 요청에 대한 Mozilla CORS 문서](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests)에 나열된 추가 요청.
간단한 교차 오리진 `POST` 메서드 요청의 경우 리소스의 응답에 `Access-Control-Allow-Origin: '*'` 또는 `Access-Control-Allow-Origin:'origin'` 헤더가 포함되어야 합니다.
다른 모든 cross-origin HTTP 요청은 *비 단순* 요청입니다.
## 단순하지 않은 요청을 위한 CORS 사용 설정
API 리소스가 단순하지 않은 요청을 받는 경우 통합 유형에 따라 추가 CORS 지원을 사용 설정해야 합니다.
### 비프록시 통합을 위한 CORS 사용 설정
이러한 통합의 경우 [CORS 프로토콜](https://fetch.spec.whatwg.org/#http-cors-protocol)은 브라우저에 사전 요청을 서버로 보내고, 서버 승인(또는 보안 인증 정보 요청)을 기다린 후 실제 요청을 보내도록 요구합니다. 사전 요청에 적절한 응답을 보내도록 API를 구성해야 합니다.
사전 요청에 대한 응답을 만드는 방법
1. 임의 통합으로 `OPTIONS` 메서드를 생성합니다.
1. 다음 응답 헤더를 200 메서드 응답에 추가합니다.
+ `Access-Control-Allow-Headers`
+ `Access-Control-Allow-Methods`
+ `Access-Control-Allow-Origin`
1. 통합 패스스루 동작을 `NEVER`로 설정합니다. 이 경우 매핑되지 않은 콘텐츠 유형의 메서드 요청은 HTTP 415 미지원 미디어 유형 응답과 함께 거부됩니다. 자세한 내용은 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하세요.
1. 응답 헤더의 값을 입력합니다. 모든 오리진, 모든 메서드 및 일반적인 헤더를 허용하려면 다음 헤더 값을 사용합니다.
+ `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'`
+ `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'`
+ `Access-Control-Allow-Origin: '*'`
사전 요청을 생성한 후에는 CORS 사용이 설정된 모든 메서드에서 최소 200개 응답 모두에 대해 `Access-Control-Allow-Origin: '*'` 또는 `Access-Control-Allow-Origin:'origin'` 헤더를 반환해야 합니다.
### AWS Management Console을 사용하여 비프록시 통합을 위한 CORS 사용 설정
AWS Management Console을 사용하여 CORS를 활성화할 수 있습니다. API Gateway에서 `OPTIONS` 메서드를 생성하고 기존 메서드 통합 응답에 `Access-Control-Allow-Origin` 헤더를 추가합니다. 이 방법이 항상 효과가 있는 것은 아니며, CORS 사용이 설정된 모든 메서드에서 최소 200개 응답 모두에 대해 `Access-Control-Allow-Origin` 헤더를 반환하도록 통합 응답을 수동으로 수정해야 하는 경우도 있습니다.
API에 대해 바이너리 미디어 유형이 `*/*`로 설정된 경우 API Gateway가 `OPTIONS` 메서드를 생성할 때 `contentHandling`을 `CONVERT_TO_TEXT`로 변경합니다.
다음 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) 명령은 통합 요청에 대해 `contentHandling`을 `CONVERT_TO_TEXT`로 변경합니다.
```
aws apigateway update-integration \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
다음 [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) 명령은 통합 응답에 대해 `contentHandling`을 `CONVERT_TO_TEXT`로 변경합니다.
```
aws apigateway update-integration-response \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--status-code 200 \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
## 프록시 통합을 위한 CORS 지원 사용 설정
Lambda 프록시 통합 또는 HTTP 프록시 통합의 경우 프록시 통합은 통합 응답을 반환하지 않기 때문에 `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers` 헤더를 반환할 책임이 백엔드에 있습니다.
다음 예제 Lambda 함수는 필요한 CORS 헤더를 반환합니다.
------
#### [ Node.js ]
```
export const handler = async (event) => {
const response = {
statusCode: 200,
headers: {
"Access-Control-Allow-Headers" : "Content-Type",
"Access-Control-Allow-Origin": "https://www.example.com",
"Access-Control-Allow-Methods": "OPTIONS,POST,GET"
},
body: JSON.stringify('Hello from Lambda!'),
};
return response;
};
```
------
#### [ Python 3 ]
```
import json
def lambda_handler(event, context):
return {
'statusCode': 200,
'headers': {
'Access-Control-Allow-Headers': 'Content-Type',
'Access-Control-Allow-Origin': 'https://www.example.com',
'Access-Control-Allow-Methods': 'OPTIONS,POST,GET'
},
'body': json.dumps('Hello from Lambda!')
}
```
------
**Topics**
+ [CORS 지원 활성화 여부 확인](#apigateway-cors-request-types)
+ [단순한 요청을 위한 CORS 사용 설정](#apigateway-cors-simple-request)
+ [단순하지 않은 요청을 위한 CORS 사용 설정](#apigateway-enable-cors-non-simple)
+ [프록시 통합을 위한 CORS 지원 사용 설정](#apigateway-enable-cors-proxy)
+ [API Gateway 콘솔을 사용하여 리소스에서 CORS 활성화](how-to-cors-console.md)
+ [API Gateway 가져오기 API를 사용하여 리소스에서 CORS 활성화](enable-cors-for-resource-using-swagger-importer-tool.md)
+ [API Gateway API용 CORS 테스트](apigateway-test-cors.md)
# API Gateway 콘솔을 사용하여 리소스에서 CORS 활성화
생성한 REST API 리소스의 한 메서드 또는 모든 메서드에 대해 API Gateway 콘솔을 사용하여 CORS 지원을 활성화할 수 있습니다. COR 지원을 활성화한 후 통합 패스스루 동작을 `NEVER`로 설정합니다. 이 경우 매핑되지 않은 콘텐츠 유형의 메서드 요청은 HTTP 415 미지원 미디어 유형 응답과 함께 거부됩니다. 자세한 내용은 [API Gateway의 REST API에 대한 매핑 템플릿이 없는 페이로드의 메서드 요청 동작](integration-passthrough-behaviors.md) 섹션을 참조하세요.
**중요**
리소스는 하위 리소스를 포함할 수 있습니다. 리소스와 그 메서드에 대한 CORS 지원 활성화는 하위 리소스와 그 메서드에 대해 재귀적으로 활성화되지 않습니다.
**REST API 리소스에 대해 CORS 지원을 활성화하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API를 선택합니다.
1. **리소스**에서 리소스를 선택합니다.
1. **리소스 세부 정보** 섹션에서 **CORS 활성화**를 선택합니다.
![\[리소스 창에서 CORS 활성화를 선택합니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png)
1. **CORS 활성화** 상자에서 다음을 수행합니다.
1. (선택 사항) 사용자 지정 게이트웨이 응답을 생성한 후 응답에 대한 CORS 지원을 활성화하려면 게이트웨이 응답을 선택합니다.
1. 각 메서드를 선택하여 CORS 지원을 활성화합니다. `OPTION` 메서드에 CORS가 활성화되어 있어야 합니다.
`ANY` 메서드에 대해 CORS 지원을 활성화하면 모든 메서드에 대해 CORS가 활성화됩니다.
1. **Access-Control-Allow-Headers** 입력 필드에 클라이언트가 실제 리소스 요청 시에 제출해야 할 쉼표로 분리된 헤더 목록의 정적 문자열을 입력합니다. 콘솔에서 제공하는 `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'`의 헤더 목록을 사용하거나 자체 헤더를 사용합니다.
1. 콘솔에서 제공하는 `'*'` 값을 **Access-Control-Allow-Origin** 헤더 값으로 사용하여 모든 오리진으로부터 수신되는 액세스 요청을 허용하거나 리소스에 대한 액세스를 허용할 오리진을 지정합니다.
1. **저장**을 선택합니다.
![\[허용할 헤더 선택\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png)
**중요**
상기 지침을 프록시 통합에서 `ANY` 메서드에 적용할 때 어떤 적용 가능한 CORS도 설정하지 않습니다. 대신 백엔드에서 해당 CORS 헤더를 반환해야 합니다(예: `Access-Control-Allow-Origin`).
`GET` 메서드에 대해 CORS가 활성화되면 `OPTIONS` 메서드가 리소스에 추가됩니다(아직 없는 경우). `OPTIONS` 메서드의 `200` 응답은 preflight 핸드셰이크를 수행하기 위해 `Access-Control-Allow-*` 헤더 세 개를 반환하도록 자동으로 구성됩니다. 또한 실제 (`GET`) 메서드는 기본적으로 200 응답에 `Access-Control-Allow-Origin` 헤더를 반환하도록 구성됩니다. 다른 응답 유형의 경우, `Cross-origin access` 오류를 반환하지 않으려면 '\$1' 또는 특정 오리진을 포함하는 `Access-Control-Allow-Origin'` 헤더를 반환하도록 수동으로 구성해야 합니다.
리소스에 대해 CORS 지원을 활성화한 후 API를 배포하거나 다시 배포해야 새로운 설정이 적용됩니다. 자세한 내용은 [배포를 생성합니다.](set-up-deployments.md#create-deployment) 섹션을 참조하세요.
**참고**
절차를 따른 후에도 리소스에서 CORS 지원을 활성화할 수 없는 경우 CORS 구성을 예제 API `/pets` 리소스와 비교하는 것이 좋습니다. 예제 API 생성 방법은 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md) 단원을 참조하십시오.
# API Gateway 가져오기 API를 사용하여 리소스에서 CORS 활성화
[API Gateway API 가져오기](api-gateway-import-api.md)를 사용하는 경우 OpenAPI 파일을 사용하여 CORS 지원을 설정할 수 있습니다. 먼저, 필요한 헤더를 반환하는 리소스에 `OPTIONS` 메서드를 정의해야 합니다.
**참고**
웹 브라우저는 CORS 요청을 허용하는 각 API 메서드에서 Access-Control-Allow-Headers 및 Access-Control-Allow-Origin 헤더를 설정할 것을 기대합니다. 또한 일부 브라우저는 먼저 동일한 리소스의 `OPTIONS` 메서드에 HTTP 요청을 한 후 동일한 헤더를 받을 것으로 예상합니다.
## `Options` 메서드 예시
다음 예제에서는 모의 통합을 위해 `OPTIONS` 메서드를 생성합니다.
------
#### [ OpenAPI 3.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
tags:
- CORS
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
type: mock
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
```
------
#### [ OpenAPI 2.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
consumes:
- "application/json"
produces:
- "application/json"
tags:
- CORS
x-amazon-apigateway-integration:
type: mock
requestTemplates: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
리소스에 대해 `OPTIONS` 메서드를 구성한 후에는 CORS 요청을 수락해야 하는 동일한 리소스의 다른 메서드에 필요한 헤더를 추가할 수 있습니다.
1. **Access-Control-Allow-Origin** 및 **헤더(Headers)**를 응답 유형에 선언합니다.
------
#### [ OpenAPI 3.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
1. `x-amazon-apigateway-integration` 태그에서 이들 헤더의 정적 값에 대한 매핑을 설정합니다.
------
#### [ OpenAPI 3.0 ]
```
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
responseTemplates:
application/json: |
{}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
```
------
## 예시 API
다음 예시는 `OPTIONS` 메서드가 포함된 완전한 API 및 `HTTP` 통합이 있는 `GET` 메서드를 만듭니다.
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "cors-api"
description: "cors-api"
version: "2024-01-16T18:36:01Z"
servers:
- url: "/{basePath}"
variables:
basePath:
default: "/test"
paths:
/:
get:
operationId: "GetPet"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
components:
schemas:
Empty:
type: "object"
```
------
#### [ OpenAPI 2.0 ]
```
swagger: "2.0"
info:
description: "cors-api"
version: "2024-01-16T18:36:01Z"
title: "cors-api"
basePath: "/test"
schemes:
- "https"
paths:
/:
get:
operationId: "GetPet"
produces:
- "application/json"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
"200":
description: "200 response"
schema:
$ref: "#/definitions/Empty"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Headers:
type: "string"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
definitions:
Empty:
type: "object"
```
------
# API Gateway API용 CORS 테스트
API를 호출하고 응답에서 CORS 헤더를 확인하여 API의 CORS 구성을 테스트할 수 있습니다. 다음 `curl` 명령은 배포된 API에 OPTIONS 요청을 보냅니다.
```
curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}
```
```
< HTTP/1.1 200 OK
< Date: Tue, 19 May 2020 00:55:22 GMT
< Content-Type: application/json
< Content-Length: 0
< Connection: keep-alive
< x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token
< x-amz-apigw-id: Abcd=
< Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT
```
응답의 `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers` 및 `Access-Control-Allow-Methods` 헤더는 API가 CORS를 지원함을 나타냅니다. 자세한 내용은 [API Gateway의 REST API CORS](how-to-cors.md) 섹션을 참조하세요.
# API Gateway의 REST API에 대한 이진 미디어 유형
API Gateway에서 API 요청과 응답은 텍스트 또는 이진 페이로드를 포함합니다. 텍스트 페이로드는 `UTF-8` 인코딩 형식의 JSON 문자열입니다. 이진 페이로드는 텍스트 페이로드를 제외한 페이로드입니다. 예를 들어 JPEG 파일, GZip 파일, XML 파일 등이 이진 페이로드가 될 수 있습니다. 이진 미디어를 지원하는 데 필요한 API 구성은 API가 프록시 통합을 사용하는지 아니면 비 프록시 통합을 사용하는지에 따라 달라집니다.
프록시 통합을 페이로드 응답 스트리밍과 함께 사용하는 경우 바이너리 미디어 유형을 구성할 필요가 없습니다. 자세한 내용은 [API Gateway에서 프록시 통합에 대한 통합 응답 스트리밍](response-transfer-mode.md) 섹션을 참조하세요.
## AWS Lambda 프록시 통합
AWS Lambda 프록시 통합을 위한 이진 페이로드를 처리하려면 함수의 응답을 base64로 인코딩해야 합니다. 또한 API에 대한 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)를 구성해야 합니다. API의 `binaryMediaTypes` 구성은 API가 이진 데이터로 처리하는 콘텐츠 유형 목록입니다. 이진 미디어 유형의 예로는 `image/png` 또는 `application/octet-stream` 등이 있습니다. 와일드카드 문자(`*`)를 사용하여 여러 미디어 유형을 처리할 수 있습니다.
API Gateway는 클라이언트의 첫 번째 `Accept` 헤더를 사용하여 응답이 이진 미디어를 반환해야 하는지 결정합니다. 브라우저의 요청과 같이 `Accept` 헤더 값의 순서를 제어할 수 없을 때 이진 미디어를 반환하려면 API의 이진 미디어 유형을 `*/*`로 설정합니다.
예제 코드는 [API Gateway의 Lambda 프록시 통합에서 이진 미디어 반환](lambda-proxy-binary-media.md) 항목을 참조하세요.
Lambda 프록시 통합을 페이로드 응답 스트리밍과 함께 사용하는 경우 바이너리 미디어 유형을 구성할 필요가 없습니다. 자세한 내용은 [API Gateway에서 페이로드 응답 스트리밍과 Lambda 프록시 통합 설정](response-transfer-mode-lambda.md) 섹션을 참조하세요.
## 비 프록시 통합
비 프록시 통합을 위한 이진 페이로드를 처리하려면 `RestApi` 리소스의 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) 목록에 미디어 유형을 추가합니다. API의 `binaryMediaTypes` 구성은 API가 이진 데이터로 처리하는 콘텐츠 유형 목록입니다. 또는 [통합(Integration)](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 및 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스에서 [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) 속성을 설정할 수 있습니다. `contentHandling` 값은 `CONVERT_TO_BINARY` 또는 `CONVERT_TO_TEXT`이거나 정의되지 않을 수 있습니다.
**참고**
`MOCK` 또는 프라이빗 통합의 경우 `contentHandling` 속성 설정은 AWS Management Console에서 지원되지 않습니다. `contentHandling` 속성을 설정하려면 AWS CLI, CloudFormation 또는 SDK를 사용해야 합니다.
`contentHandling` 값과 응답의 `Content-Type` 헤더 또는 수신 요청의 `Accept` 헤더가 `binaryMediaTypes` 목록의 항목과 일치하는지 여부에 따라 API Gateway에서 원시 이진 유형을 base64로 인코딩된 문자열로 인코딩하거나, base64로 인코딩된 문자열을 원시 바이트로 다시 디코딩하거나, 본문을 수정하지 않고 전달할 수 있습니다.
API Gateway에서 API에 대해 이진 페이로드를 지원하려면 API를 다음과 같이 구성해야 합니다.
+ [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스의 `binaryMediaTypes` 목록에 원하는 이진 미디어 형식을 추가합니다. 이 속성과 `contentHandling` 속성을 정의하지 않은 경우 페이로드는 UTF-8로 인코딩된 JSON 문자열로 처리됩니다.
+ [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스의 `contentHandling` 속성을 설정합니다.
+ 요청 페이로드를 base64로 인코딩된 문자열에서 이진 Blob로 변환하려면 속성을 `CONVERT_TO_BINARY`로 설정합니다.
+ 요청 페이로드를 이진 Blob에서 base64로 인코딩된 문자열로 변환하려면 속성을 `CONVERT_TO_TEXT`로 설정합니다.
+ 페이로드를 수정하지 않고 전달하려면 속성을 정의되지 않은 상태로 둡니다. 이진 페이로드를 수정하지 않고 전달하려면 `Content-Type`이 `binaryMediaTypes` 항목 중 하나와 일치하고 API에 대해 [패스스루 동작](integration-passthrough-behaviors.md)이 활성화되어 있어야 합니다.
+ [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스의 `contentHandling` 속성을 설정합니다. `contentHandling` 속성, 클라이언트 요청의 `Accept` 헤더 및 API `binaryMediaTypes`의 조합에 따라 API Gateway에서 콘텐츠 유형 변환을 처리하는 방법이 결정됩니다. 자세한 내용은 [API Gateway의 콘텐츠 유형 변환](api-gateway-payload-encodings-workflow.md) 단원을 참조하세요.
**중요**
요청의 `Accept` 헤더에 여러 미디어 유형이 포함되어 있는 경우 API Gateway에서는 첫 번째 `Accept` 미디어 유형만 인식합니다. `Accept` 미디어 유형의 순서를 제어할 수 없고 이진 콘텐츠의 미디어 유형이 목록의 맨 앞에 있지 않은 경우, API의 `Accept` 목록에서 첫 번째 `binaryMediaTypes` 미디어 유형을 추가합니다. API Gateway는 이 목록의 모든 콘텐츠 유형을 이진수로 처리합니다.
예를 들어 브라우저에서 `` 요소를 사용하여 JPEG 파일을 보내려는 경우 브라우저에서 요청에 `Accept:image/webp,image/*,*/*;q=0.8`을 전송할 수 있습니다. `image/webp`를 `binaryMediaTypes` 목록에 추가하여 엔드포인트에서 JPEG 파일을 이진 유형으로 수신합니다.
API Gateway에서 텍스트 및 이진 페이로드를 처리하는 방법에 대한 자세한 내용은 [API Gateway의 콘텐츠 유형 변환](api-gateway-payload-encodings-workflow.md) 단원을 참조하세요.
# API Gateway의 콘텐츠 유형 변환
API `binaryMediaTypes`, 클라이언트 요청의 헤더 및 통합 `contentHandling` 속성의 조합에 따라 API Gateway에서 페이로드를 인코딩하는 방법이 결정됩니다.
다음 표는 API Gateway가 요청 `Content-Type` 헤더의 특정 구성, [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스의 `binaryMediaTypes` 목록 및 [통합](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 리소스의 `contentHandling` 속성 값에 대한 요청 페이로드를 어떻게 변환하는지 보여 줍니다.
| 메서드 요청 페이로드 | 요청 `Content-Type` 헤더 | `binaryMediaTypes` | `contentHandling` | 통합 요청 페이로드 |
| --- | --- | --- | --- | --- |
| 텍스트 데이터 | 모든 데이터 형식 | 정의되지 않음 | 정의되지 않음 | UTF8로 인코딩된 문자열 |
| 텍스트 데이터 | 모든 데이터 형식 | 정의되지 않음 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 이진 BLOB |
| 텍스트 데이터 | 모든 데이터 형식 | 정의되지 않음 | CONVERT\$1TO\$1TEXT | UTF8로 인코딩된 문자열 |
| 텍스트 데이터 | 텍스트 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | 텍스트 데이터 |
| 텍스트 데이터 | 텍스트 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 이진 BLOB |
| 텍스트 데이터 | 텍스트 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | 텍스트 데이터 |
| 이진 데이터 | 이진 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | 이진 데이터 |
| 이진 데이터 | 이진 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | 이진 데이터 |
| 이진 데이터 | 이진 데이터 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | Base64로 인코딩된 문자열 |
다음 표는 API Gateway가 요청 `Accept` 헤더의 특정 구성, [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스의 `binaryMediaTypes` 목록 및 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 리소스의 `contentHandling` 속성 값에 대한 응답 페이로드를 어떻게 변환하는지 보여 줍니다.
**중요**
요청의 `Accept` 헤더에 여러 미디어 유형이 포함되어 있는 경우 API Gateway에서는 첫 번째 `Accept` 미디어 유형만 인식합니다. `Accept` 미디어 유형의 순서를 제어할 수 없고 이진 콘텐츠의 미디어 유형이 목록의 맨 앞에 있지 않은 경우, API의 `Accept` 목록에서 첫 번째 `binaryMediaTypes` 미디어 유형을 추가합니다. API Gateway는 이 목록의 모든 콘텐츠 유형을 이진수로 처리합니다.
예를 들어 브라우저에서 `` 요소를 사용하여 JPEG 파일을 보내려는 경우 브라우저에서 요청에 `Accept:image/webp,image/*,*/*;q=0.8`을 전송할 수 있습니다. `image/webp`를 `binaryMediaTypes` 목록에 추가하여 엔드포인트에서 JPEG 파일을 이진 유형으로 수신합니다.
| 통합 응답 페이로드 | 요청 `Accept` 헤더 | `binaryMediaTypes` | `contentHandling` | 메서드 응답 페이로드 |
| --- | --- | --- | --- | --- |
| 텍스트 또는 이진 데이터 | 텍스트 유형 | 정의되지 않음 | 정의되지 않음 | UTF8로 인코딩된 문자열 |
| 텍스트 또는 이진 데이터 | 텍스트 유형 | 정의되지 않음 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 BLOB |
| 텍스트 또는 이진 데이터 | 텍스트 유형 | 정의되지 않음 | CONVERT\$1TO\$1TEXT | UTF8로 인코딩된 문자열 |
| 텍스트 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | 텍스트 데이터 |
| 텍스트 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 BLOB |
| 텍스트 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | UTF8로 인코딩된 문자열 |
| 텍스트 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | Base64로 디코딩된 BLOB |
| 텍스트 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | Base64로 디코딩된 BLOB |
| 텍스트 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | UTF8로 인코딩된 문자열 |
| 이진 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | Base64로 인코딩된 문자열 |
| 이진 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | 이진 데이터 |
| 이진 데이터 | 텍스트 유형 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | Base64로 인코딩된 문자열 |
| 이진 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | 정의되지 않음 | 이진 데이터 |
| 이진 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1BINARY | 이진 데이터 |
| 이진 데이터 | 이진수 형식 | 일치하는 미디어 유형이 있는 세트 | CONVERT\$1TO\$1TEXT | Base64로 인코딩된 문자열 |
텍스트 페이로드를 이진 BLOB으로 변환할 때 API Gateway에서는 텍스트 데이터가 Base64로 인코딩된 문자열인 것으로 간주하고 이진 데이터를 Base64로 디코딩된 BLOB으로 출력합니다. 변환에 실패하면 API 구성 오류를 나타내는 `500` 응답이 반환됩니다. API에 대해 [패스스루 동작](integration-passthrough-behaviors.md)을 활성화해야 하되, 이러한 변환에 대해 매핑 템플릿을 제공하지 않습니다.
이진 페이로드를 텍스트 문자열로 변환할 경우 API Gateway에서는 항상 이진 데이터에 Base64 인코딩을 적용합니다. 다음과 같은 예제 매핑 템플릿에 표시된 것처럼 이러한 페이로드에 대해 매핑 템플릿을 정의할 수 있지만, `$input.body`를 통해서만 매핑 템플릿의 Base64로 인코딩된 문자열에 액세스할 수 있습니다.
```
{
"data": "$input.body"
}
```
이진 페이로드를 수정하지 않고 전달하려면 API에서 [패스스루 동작](integration-passthrough-behaviors.md)을 활성화해야 합니다.
# API Gateway 콘솔을 사용하여 이진 지원 활성화
이 단원에서는 API Gateway 콘솔을 사용하여 이진 지원을 활성화하는 방법을 설명합니다. 예를 들어 Amazon S3에 통합된 API를 사용합니다. 지원되는 미디어 유형을 설정하고 페이로드를 처리하는 방법을 지정하는 작업을 중점적으로 다룹니다. Amazon S3에 통합된 API를 생성하는 방법에 대한 자세한 내용은 [자습서: Amazon Kinesis 프록시로 REST API 생성](integrating-api-with-aws-services-s3.md) 단원을 참조하세요.
**API Gateway 콘솔을 사용하여 이진 지원을 활성화하려면**
1. API에 이진 미디어 형식 설정:
1. 새 API를 생성하거나 기존 API를 선택합니다. 이 예에서는 API 이름을 `FileMan`으로 지정합니다.
1. 기본 탐색 창에서 선택한 API 아래에서 **API 설정**을 선택합니다.
1. **API 설정** 창의 **이진 미디어 형식** 섹션에서 **미디어 형식 관리**를 선택합니다.
1. **이진 미디어 형식 추가**를 선택합니다.
1. 입력 텍스트 필드에 필요한 미디어 형식(예: **image/png**)을 입력합니다. 필요한 경우 이 단계를 반복하여 미디어 유형을 더 추가합니다. 모든 이진수 미디어 유형을 지원하려면 `*/*`을(를) 지정합니다.
1. **변경 사항 저장**을 선택합니다.
1. API 메서드에 메시지 페이로드가 처리되는 방식을 설정합니다.
1. 새 리소스를 생성하거나 API에서 기존 리소스를 선택합니다. 이 예에서는 `/{folder}/{item}` 리소스를 사용합니다.
1. 새 메서드를 생성하거나 리소스에서 기존 메서드를 선택합니다. 예를 들어 Amazon S3에서 `GET /{folder}/{item}` 작업과 통합된 `Object GET` 메서드를 사용합니다.
1. **콘텐츠 처리**에서 옵션을 선택합니다.
![\[API Gateway 콘솔에서 GET 메서드를 설정합니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png)
클라이언트와 백엔드가 동일한 이진 형식을 수락하는 경우 본문을 변환하고 싶지 않다면 **패스스루(Passthrough)**를 선택합니다. 백엔드에서 이진 요청 페이로드를 JSON 속성으로 전달 받기를 요구하는 등의 경우, **텍스트로 변환**을 선택하여 이진 본문을 Base64로 인코딩된 문자열로 변환합니다. 클라이언트가 Base64로 인코딩된 문자열을 제출하고 백엔드에서 원래 이진 형식을 요구하는 경우나 엔드포인트가 Base64로 인코딩된 문자열을 반환하고 클라이언트가 이진 출력만 수락하는 경우에는 **이진으로 변환**을 선택합니다.
1. **요청 본문 패스스루**에서 **정의된 템플릿이 없는 경우(권장)**를 선택하여 요청 본문에 패스스루 동작을 활성화합니다.
**안 함**을 선택할 수도 있습니다. 이렇게 하면 API가 매핑 템플릿이 없는 content-types의 데이터를 거부합니다.
1. 수신되는 요청의 `Accept` 헤더를 통합 요청에 보존합니다. `contentHandling`을 `passthrough`로 설정하고 실행 시간에 이 설정을 재정의하고 싶은 경우 이렇게 해야 합니다.
![\[통합 요청에 Accept 헤더를 유지합니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png)
1. 텍스트로 전환하려면 필요한 형식에 Base64로 인코딩된 이진 데이터를 입력하도록 매핑 템플릿을 정의합니다.
텍스트로 변환할 매핑 템플릿의 예는 다음과 같습니다.
```
{
"operation": "thumbnail",
"base64Image": "$input.body"
}
```
이 매핑 템플릿의 형식은 입력 항목의 엔드포인트 요구 사항에 따라 결정됩니다.
1. **저장**을 선택합니다.
# API Gateway REST API를 사용하여 이진 지원 활성화
다음 작업에서는 API Gateway REST API 호출을 사용하여 이진 지원을 활성화하는 방법을 보여 줍니다.
**Topics**
+ [지원되는 이진 미디어 지원을 API에 추가 및 업데이트](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [요청 페이로드 변환 구성](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [응답 페이로드 변환 구성](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [이진 데이터를 텍스트 데이터로 변환](#api-gateway-payload-encodings-convert-binary-to-string)
+ [텍스트 데이터를 이진 페이로드로 변환](#api-gateway-payload-encodings-convert-string-to-binary)
+ [이진 페이로드 패스스루](#api-gateway-payload-encodings-pass-binary-as-is)
## 지원되는 이진 미디어 지원을 API에 추가 및 업데이트
API Gateway에서 새로운 이진 미디어 유형을 지원하도록 활성화하려면 이진 미디어 유형을 `binaryMediaTypes` 리소스의 `RestApi` 목록에 추가해야 합니다. 예를 들어 API Gateway에서 JPEG 이미지를 처리하도록 하려면 `PATCH` 요청을 `RestApi` 리소스에 제출합니다.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/image~1jpeg"
}
]
}
```
`image/jpeg` 속성 값의 일부인 `path`의 MIME 유형 사양은 `image~1jpeg`로 이스케이프됩니다.
지원되는 이진 미디어 유형을 업데이트하려면 `binaryMediaTypes` 리소스의 `RestApi` 목록에서 미디어 유형을 교체하거나 제거합니다. 예를 들어 이진 지원을 JPEG 파일에서 원시 바이트로 변경하려면 다음과 같이 `PATCH` 요청을 `RestApi` 리소스에 제출합니다.
```
PATCH /restapis/
{
"patchOperations" : [{
"op" : "replace",
"path" : "/binaryMediaTypes/image~1jpeg",
"value" : "application/octet-stream"
},
{
"op" : "remove",
"path" : "/binaryMediaTypes/image~1jpeg"
}]
}
```
## 요청 페이로드 변환 구성
엔드포인트에 이진 입력이 필요한 경우 `contentHandling` 리소스의 `Integration` 속성을 `CONVERT_TO_BINARY`로 설정합니다. 이렇게 하려면 다음과 같이 `PATCH` 요청을 제출합니다.
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## 응답 페이로드 변환 구성
클라이언트에서 엔드포인트에서 반환되는 Base64로 인코딩된 페이로드가 아닌 이진 BLOB 형태의 결과를 수락하는 경우, `contentHandling` 리소스의 `IntegrationResponse` 속성을 `CONVERT_TO_BINARY`로 설정합니다. 이렇게 하려면 다음과 같이 `PATCH` 요청을 제출합니다.
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## 이진 데이터를 텍스트 데이터로 변환
API Gateway를 통해 이진 데이터를 AWS Lambda 또는 Kinesis에 대한 입력의 JSON 속성으로 전송하려면 다음을 수행합니다.
1. `application/octet-stream`의 새 이진 미디어 유형을 API의 `binaryMediaTypes` 목록에 추가하여 API의 이진 페이로드 지원을 활성화합니다.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. `CONVERT_TO_TEXT` 리소스의 `contentHandling` 속성에서 `Integration`를 설정하고 매핑 템플릿을 제공하여 이진 데이터의 Base64로 인코딩된 문자열을 JSON 속성에 할당합니다. 다음 예제에서 JSON 속성은 `body`이고 `$input.body`는 Base64로 인코딩된 문자열을 보유합니다.
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_TEXT"
},
{
"op" : "add",
"path" : "/requestTemplates/application~1octet-stream",
"value" : "{\"body\": \"$input.body\"}"
}
]
}
```
## 텍스트 데이터를 이진 페이로드로 변환
Lambda 함수가 이미지 파일을 Base64로 인코딩된 문자열로 반환한다고 가정합니다. API Gateway를 통해 이 이진 출력을 클라이언트에 전달하려면 다음을 수행합니다.
1. `binaryMediaTypes`의 이진 미디어 유형을 추가하여(목록에 아직 없는 경우) API의 `application/octet-stream` 목록을 업데이트합니다.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream",
}]
}
```
1. `contentHandling` 리소스의 `Integration` 속성을 `CONVERT_TO_BINARY`로 설정합니다. 매핑 템플릿을 정의하지 마세요. 매핑 템플릿을 정의하지 않을 경우, API Gateway에서 패스스루 템플릿을 호출하여 Base64로 디코딩된 이진 BLOB을 클라이언트에 이미지 파일로 반환합니다.
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}
]
}
```
## 이진 페이로드 패스스루
API Gateway를 사용하여 Amazon S3 버킷에 이미지를 저장하려면 다음을 수행합니다.
1. `binaryMediaTypes`의 이진 미디어 유형을 추가하여(목록에 아직 없는 경우) API의 `application/octet-stream` 목록을 업데이트합니다.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. `contentHandling` 리소스의 `Integration` 속성을 `CONVERT_TO_BINARY`로 설정합니다. 매핑 템플릿을 정의하지 않고 `WHEN_NO_MATCH`를 `passthroughBehavior` 속성 값으로 설정합니다. 그러면 API Gateway에서 패스스루 템플릿을 호출할 수 있습니다.
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
},
{
"op" : "replace",
"path" : "/passthroughBehaviors",
"value" : "WHEN_NO_MATCH"
}
]
}
```
# API Gateway에 대한 콘텐츠 인코딩 가져오기 및 내보내기
[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)에서 `binaryMediaTypes` 목록을 가져오려면 API의 OpenAPI 정의 파일에 대해 다음 API Gateway 확장을 사용합니다. 이 확장은 API 설정을 내보내는 데에도 사용됩니다.
+ [x-amazon-apigateway-binary-media-types 속성](api-gateway-swagger-extensions-binary-media-types.md)
`contentHandling` 또는 `Integration` 리소스에서 `IntegrationResponse` 속성 값을 가져오거나 내보내려면 OpenAPI 정의에 대해 다음 API Gateway 확장을 사용합니다.
+ [x-amazon-apigateway-integration 객체](api-gateway-swagger-extensions-integration.md)
+ [x-amazon-apigateway-integration.response 객체](api-gateway-swagger-extensions-integration-response.md)
# API Gateway의 Lambda 프록시 통합에서 이진 미디어 반환
[AWS Lambda 프록시 통합](set-up-lambda-proxy-integrations.md)에서 이진 미디어를 반환하려면 Lambda 함수의 응답을 base64로 인코딩합니다. 또한 [API의 이진 미디어 유형을 구성](api-gateway-payload-encodings-configure-with-console.md)해야 합니다. API의 바이너리 미디어 유형을 구성하면 API가 해당 콘텐츠 유형을 바이너리 데이터로 취급합니다. 페이로드 크기 제한은 10MB입니다.
**참고**
웹 브라우저를 사용하여 이 예제 통합이 포함된 API를 호출하려면 API의 이진 미디어 유형을 `*/*`로 설정합니다. API Gateway는 클라이언트의 첫 번째 `Accept` 헤더를 사용하여 응답이 이진 미디어를 반환해야 하는지 결정합니다. 브라우저의 요청과 같이 `Accept` 헤더 값의 순서를 제어할 수 없을 때 이진 미디어를 반환하려면 API의 이진 미디어 유형을 `*/*`(모든 콘텐츠 유형에 대해)로 설정합니다.
다음 예시 Lambda 함수는 Amazon S3의 이진 이미지나 텍스트를 클라이언트에 반환할 수 있습니다. 함수의 응답에는 클라이언트에 반환하는 데이터 유형을 나타내는 `Content-Type` 헤더가 포함됩니다. 이 함수는 반환하는 데이터 유형에 따라 응답에 `isBase64Encoded` 속성을 조건부로 설정합니다.
------
#### [ Node.js ]
```
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"
const client = new S3Client({region: 'us-east-2'});
export const handler = async (event) => {
var randomint = function(max) {
return Math.floor(Math.random() * max);
}
var number = randomint(2);
if (number == 1){
const input = {
"Bucket" : "bucket-name",
"Key" : "image.png"
}
try {
const command = new GetObjectCommand(input)
const response = await client.send(command);
var str = await response.Body.transformToByteArray();
} catch (err) {
console.error(err);
}
const base64body = Buffer.from(str).toString('base64');
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64body,
'isBase64Encoded': true
}
} else {
return {
'headers': { "Content-Type": "text/html" },
'statusCode': 200,
'body': "
",
}
```
------
이진 미디어 유형에 대한 자세한 내용은 [API Gateway의 REST API에 대한 이진 미디어 유형](api-gateway-payload-encodings.md) 단원을 참조하세요.
# API Gateway API를 통해 Amazon S3에서 이진 파일에 액세스
다음 예에서는 Amazon S3에서 이미지에 액세스하는 데 사용되는 OpenAPI 파일, Amazon S3에서 이미지를 다운로드하는 방법, Amazon S3에 이미지를 업로드하는 방법을 보여줍니다.
**Topics**
+ [Amazon S3에서 이미지에 액세스하는 샘플 API의 OpenAPI 파일](#api-gateway-content-encodings-example-image-s3-swagger-file)
+ [Amazon S3에서 이미지 다운로드](#api-gateway-content-encodings-example-download-image-from-s3)
+ [Amazon S3에 이미지 업로드](#api-gateway-content-encodings-example-upload-image-to-s3)
## Amazon S3에서 이미지에 액세스하는 샘플 API의 OpenAPI 파일
다음 OpenAPI 파일은 Amazon S3에서 이미지 파일을 다운로드하거나 Amazon S3에 업로드하는 방법을 설명하는 샘플 API를 보여줍니다. 이 API는 지정된 이미지 파일을 다운로드하거나 업로드하기 위한 `GET /s3?key={file-name}` 및 `PUT /s3?key={file-name}` 메서드를 노출합니다. `GET` 메서드는 200 OK 응답에서 제공된 매핑 템플릿에 따라 JSON 출력의 일부로서 이미지 파일을 Base64로 인코딩된 문자열 형태로 반환합니다. `PUT` 메서드는 원시 이진 BLOB을 입력으로 사용하여 빈 페이로드를 포함하는 200 OK 응답을 반환합니다.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/s3": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling": "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/s3": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200" }
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling" : "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Amazon S3에서 이미지 다운로드
Amazon S3에서 이미지 파일(`image.jpg`)을 이진 BLOB으로 다운로드하려면
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
성공적인 응답은 다음과 같습니다.
```
200 OK HTTP/1.1
[raw bytes]
```
`Accept` 헤더가 `application/octet-stream`의 이진 미디어 유형으로 설정되고 API에 대해 이진 지원이 활성화되어 있으므로 원시 바이트가 반환됩니다.
또는 Amazon S3에서 이미지 파일(`image.jpg`)을 JSON 속성으로 형식 지정되고 Base64로 인코딩된 문자열로 다운로드하려면, 아래 굵은 글꼴의 OpenAPI 정의 블록에서와 같이 200 통합 응답에 응답 템플릿을 추가합니다.
```
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
},
```
이미지 파일 다운로드 요청은 다음과 같습니다.
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
성공적인 응답은 다음과 같습니다.
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## Amazon S3에 이미지 업로드
이미지 파일(`image.jpg`)을 Amazon S3에 이진 BLOB으로 업로드하려면
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
성공적인 응답은 다음과 같습니다.
```
200 OK HTTP/1.1
```
이미지 파일(`image.jpg`)을 Amazon S3에 Base64로 인코딩된 문자열로 업로드하려면
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
`Content-Type` 헤더 값이 `application/json`으로 설정되어 있으므로 입력 페이로드는 Base64로 인코딩된 문자열이어야 합니다. 성공적인 응답은 다음과 같습니다.
```
200 OK HTTP/1.1
```
# API Gateway API를 사용하여 Lambda의 이진 파일에 액세스
다음 OpenAPI 예에서는 API Gateway API를 통해 AWS Lambda에서 이진 파일에 액세스하는 방법을 보여줍니다. 이 API는 지정된 이미지 파일을 다운로드하거나 업로드하기 위한 `GET /lambda?key={file-name}` 및 `PUT /lambda?key={file-name}` 메서드를 노출합니다. `GET` 메서드는 200 OK 응답에서 제공된 매핑 템플릿에 따라 JSON 출력의 일부로서 이미지 파일을 Base64로 인코딩된 문자열 형태로 반환합니다. `PUT` 메서드는 원시 이진 BLOB을 입력으로 사용하여 빈 페이로드를 포함하는 200 OK 응답을 반환합니다.
API가 직접적으로 호출하는 Lambda 함수를 생성합니다. 이 함수는 `Content-Type` 헤더가 `application/json`인 base64 인코딩 문자열을 반환해야 합니다.
**Topics**
+ [Lambda에서 이미지에 액세스하는 샘플 API의 OpenAPI 파일](#api-gateway-content-encodings-example-image-lambda-swagger-file)
+ [Lambda에서 이미지 다운로드](#api-gateway-content-encodings-example-download-image-from-lambda)
+ [Lambda에 이미지 업로드](#api-gateway-content-encodings-example-upload-image-to-lambda)
## Lambda에서 이미지에 액세스하는 샘플 API의 OpenAPI 파일
다음 OpenAPI 파일은 Lambda에서 이미지 파일을 다운로드하거나 Lambda에 업로드하는 방법을 설명하는 예제 API를 보여줍니다.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/lambda": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/lambda": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling" : "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Lambda에서 이미지 다운로드
Lambda에서 이미지 파일(`image.jpg`)을 이진 BLOB으로 다운로드하려면
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
성공적인 응답은 다음과 같습니다.
```
200 OK HTTP/1.1
[raw bytes]
```
Lambda에서 이미지 파일(`image.jpg`)을 JSON 속성으로 형식 지정되고 Base64로 인코딩된 문자열로 다운로드하려면
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
성공적인 응답은 다음과 같습니다.
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## Lambda에 이미지 업로드
이미지 파일(`image.jpg`)을 Lambda에 이진 BLOB으로 업로드하려면
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
성공적인 응답은 다음과 같습니다.
```
200 OK
```
이미지 파일(`image.jpg`)을 Lambda에 base64로 인코딩된 문자열로 업로드하려면
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
성공적인 응답은 다음과 같습니다.
```
200 OK
```
# API Gateway에서 REST API 간접 호출
배포된 API를 호출하기 위해 클라이언트는 API 실행을 위한 API Gateway 구성 요소 서비스(예: `execute-api`)에 대한 URL 요청을 제출합니다.
기본 REST API URL의 형식은 다음과 같습니다.
```
https://api-id.execute-api.region.amazonaws.com/stage/
```
여기서 *api-id*는 API 식별자이고, *region*은 AWS 리전이고, *stage*는 API 배포의 스테이지 이름입니다.
**중요**
API를 호출하기 전에 API Gateway에서 배포해야 합니다. API 배포에 대한 지침은 [API Gateway에서 REST API 배포](how-to-deploy-api.md)을 참조합니다.
**Topics**
+ [API의 간접 호출 URL 얻기](#apigateway-how-to-call-rest-api)
+ [API 간접 호출](#apigateway-call-api)
+ [API Gateway 콘솔을 사용하여 REST API 메서드 테스트](how-to-test-method.md)
+ [API Gateway에서 생성한 REST API용 Java SDK 사용](how-to-call-apigateway-generated-java-sdk.md)
+ [API Gateway에서 생성한 REST API용 Android SDK 사용](how-to-generate-sdk-android.md)
+ [API Gateway에서 생성한 REST API용 JavaScript SDK 사용](how-to-generate-sdk-javascript.md)
+ [API Gateway에서 생성한 REST API용 Ruby SDK 사용](how-to-call-sdk-ruby.md)
+ [Objective-C 또는 Swift에서 API Gateway에 의해 생성되는 REST API용 iOS SDK 사용](how-to-generate-sdk-ios.md)
## API의 간접 호출 URL 얻기
콘솔, AWS CLI 또는 내보낸 OpenAPI 정의를 사용하여 API의 간접 호출 URL을 가져올 수 있습니다.
### 콘솔을 사용하여 API의 간접 호출 URL 얻기
다음 절차에서는 REST API 콘솔에서 API의 간접 호출 URL을 얻는 방법을 보여 줍니다.
**REST API 콘솔을 사용하여 API의 간접 호출 URL을 얻으려는 경우**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 배포된 API를 선택합니다.
1. 기본 탐색 창에서 **스테이지**를 선택합니다.
1. **스테이지 세부 정보**에서 복사 아이콘을 선택하여 API의 호출 URL을 복사합니다.
이 URL은 API의 루트 리소스용입니다.
![\[REST API를 생성하면 콘솔에 API의 호출 URL이 표시됩니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png)
1. API의 다른 리소스에 대한 API의 간접 호출 URL을 얻으려면 보조 탐색 창 아래에서 단계를 확장한 다음 메서드를 선택합니다.
1. 복사 아이콘을 선택해 API의 리소스 수준 간접 호출 URL을 복사합니다.
![\[REST API의 리소스 수준 URL은 스테이지의 보조 탐색 창 아래에 있습니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/resource-level-invoke-url.png)
#### AWS CLI를 사용하여 API의 간접 호출 URL 얻기
다음 절차에서는 AWS CLI를 사용하여 API의 간접 호출 URL을 얻는 방법을 보여 줍니다.
**AWS CLI를 사용하여 콘솔에서 API의 간접 호출 URL 얻으려는 경우**
1. `rest-api-id`를 편집하려면 다음 명령을 입력합니다. 이 명령은 해당 지역의 모든 `rest-api-id` 값을 반환합니다. 자세한 내용은 [get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html)을 참조하세요
```
aws apigateway get-rest-apis
```
1. 예제 `rest-api-id`를 `rest-api-id`로 바꾸고, 예제 *\$1stage-name\$1*을 *\$1stage-name\$1*로 바꾸고, *\$1region\$1*을 해당 리전으로 바꿉니다.
```
https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/
```
##### 내보낸 API의 OpenAPI 정의 파일을 사용하여 API의 간접 호출 URL 가져오기
API의 내보낸 OpenAPI 정의 파일에서 `host` 필드와 `basePath` 필드를 결합하여 이 루트 URL을 구성할 수도 있습니다. API 내보내기 방법에 대한 지침은 [API Gateway에서 REST API 내보내기](api-gateway-export-api.md) 섹션을 참조하세요.
## API 간접 호출
브라우저, curl 또는 [Postman](https://www.postman.com/)과 같은 기타 애플리케이션을 사용하여 배포된 API를 직접 호출할 수 있습니다.
또한 API Gateway 콘솔을 사용하여 API 호출을 테스트할 수 있습니다. 테스트에서는 API Gateway의 `TestInvoke` 기능을 사용하므로 API를 배포하기 전에 API를 테스트할 수 있습니다. 자세한 내용은 [API Gateway 콘솔을 사용하여 REST API 메서드 테스트](how-to-test-method.md) 단원을 참조하십시오.
**참고**
호출 URL의 쿼리 문자열 파라미터 값은 `%%`를 포함할 수 없습니다.
### 웹 브라우저를 사용하여 API 간접 호출
API에서 익명 액세스를 허용하는 경우 웹 브라우저를 사용하여 `GET` 메서드를 간접 호출할 수 있습니다. 브라우저의 주소 표시줄에 전체 간접 호출 URL을 입력합니다.
다른 방법이나 인증이 필요한 직접 호출의 경우 페이로드를 지정하거나 요청에 서명해야 합니다. AWS SDK 중 하나를 사용하여 HTML 페이지 뒤의 스크립트나 클라이언트 애플리케이션에서 이러한 호출을 처리할 수 있습니다.
#### curl을 사용하여 API 간접 호출
터미널에서 [curl](https://curl.se/)과 같은 도구를 사용하여 API를 직접 호출할 수 있습니다. 다음 예제 curl 명령은 API `prod` 스테이지의 `getUsers` 리소스에서 GET 메서드를 간접 호출합니다.
------
#### [ Linux or Macintosh ]
```
curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
------
#### [ Windows ]
```
curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers"
```
------
# API Gateway 콘솔을 사용하여 REST API 메서드 테스트
API Gateway 콘솔을 사용하여 REST API 메서드를 테스트합니다.
**Topics**
+ [사전 조건](#how-to-test-method-prerequisites)
+ [API Gateway 콘솔을 사용하여 메서드 테스트](#how-to-test-method-console)
## 사전 조건
+ 테스트하려는 메서드의 설정을 지정해야 합니다. [API Gateway의 REST API 메서드](how-to-method-settings.md)의 지침을 따르세요.
## API Gateway 콘솔을 사용하여 메서드 테스트
**중요**
API Gateway 콘솔을 사용하여 메서드를 테스트하면 리소스가 변경될 수 있으며 이 변경은 취소할 수 없습니다. API Gateway 콘솔을 사용하여 메서드를 테스트하는 것은 API Gateway 콘솔 외부에서 메서드를 호출하는 것과 같습니다. 예를 들어 API Gateway 콘솔을 사용하여 API 리소스를 삭제하는 메서드를 호출할 경우 메서드 호출이 성공하면 API 리소스가 삭제됩니다.
**메서드를 테스트하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. **리소스** 창에서 테스트하려는 메서드를 선택합니다.
1. **테스트** 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.
![\[테스트 탭을 사용하여 API를 테스트합니다. 메서드 응답 탭 옆에 있습니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/api-gateway-test-new-console.png)
표시된 임의의 상자(예: **쿼리 문자열**, **헤더** 및 **요청 본문**)에 값을 입력합니다. 콘솔에는 기본 애플리케이션/json 양식으로 메서드 요청에 이러한 값이 포함됩니다.
지정할 필요가 있는 추가 옵션에 대해서는 API 소유자에게 문의하세요.
1. **테스트**를 선택합니다. 다음 정보가 표시됩니다.
+ **요청**은 메서드에 대해 호출된 리소스의 경로입니다.
+ **상태**는 응답의 HTTP 상태 코드입니다.
+ **지연 시간(밀리초)**은 호출자로부터 요청을 수신한 시간과 응답 반환 시간의 시간차입니다.
+ **응답 본문**은 HTTP 응답 본문입니다.
+ **응답 헤더**는 HTTP 응답 헤더입니다.
**작은 정보**
매핑에 따라 HTTP 상태 코드, 응답 본문 및 응답 헤더가 Lambda 함수, HTTP 프록시 또는 AWS 서비스 프록시에서 전송한 것과 다를 수 있습니다.
+ **Logs**는 이 메서드가 API Gateway 콘솔 밖에서 호출되었을 경우 작성되었을 시뮬레이션된 Amazon CloudWatch Logs 입력입니다.
**참고**
CloudWatch Logs 입력은 시뮬레이션된 것이지만 메서드 호출의 결과는 실제입니다.
API Gateway 콘솔을 사용하는 것 이외에 AWS CLI 또는 API Gateway용 AWS SDK를 사용해 메서드 호출을 테스트할 수 있습니다. AWS CLI를 사용해 테스트하려면 [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html) 단원을 참조하십시오.
# API Gateway에서 생성한 REST API용 Java SDK 사용
이 단원에서는 API Gateway에서 생성된 REST API용 Java SDK를 사용하는 단계를 [간편 계산기](simple-calc-lambda-api-swagger-definition.md) API를 예로 들어 설명합니다. 계속하려면 먼저 [API Gateway에서 REST API SDK 생성](how-to-generate-sdk.md)의 단계를 완료해야 합니다.
**API Gateway가 생성한 Java SDK를 설치하고 사용하려면**
1. 앞서 다운로드한 API Gateway가 생성한 .zip 파일의 압축을 풉니다.
1. [Apache Maven](https://maven.apache.org/)(버전 3.5 이상)을 다운로드하여 설치합니다.
1. [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)을 다운로드하여 설치합니다.
1. `JAVA_HOME` 환경 변수를 설정합니다.
1. pom.xml 파일이 있는, 압축을 해제한 SDK 폴더로 이동합니다. 기본적으로 이 폴더는 `generated-code`입니다. **mvn install** 명령을 실행해 컴파일된 아티팩트 파일을 로컬 Maven 리포지토리에 설치합니다. 그러면 컴파일된 SDK 라이브러리를 포함하는 `target` 폴더가 생성됩니다.
1. 빈 디렉터리에 다음 명령을 입력해 클라이언트 프로젝트 스텁을 생성하여 설치된 SDK 라이브러리를 사용해 API를 호출합니다.
```
mvn -B archetype:generate \
-DarchetypeGroupdId=org.apache.maven.archetypes \
-DgroupId=examples.aws.apig.simpleCalc.sdk.app \
-DartifactId=SimpleCalc-sdkClient
```
**참고**
앞의 명령에서 가독성을 높이기 위해 `\` 구분자가 포함됩니다. 전체 명령은 구분자 없이 한 줄로 표시되어야 합니다.
이 명령은 애플리케이션 스텁을 생성합니다. 이 애플리케이션 스텁은 프로젝트의 루트 디렉터리에 `pom.xml` 파일과 `src` 폴더를 포함합니다(앞의 명령에서 *SimpleCalc-sdkClient*). 처음에는 두 개의 소스 파일, `src/main/java/{package-path}/App.java`와 `src/test/java/{package-path}/AppTest.java`가 있습니다. 이 예제에서 *\$1package-path\$1*는 `examples/aws/apig/simpleCalc/sdk/app`입니다. 이 패키지 경로는 `DarchetypeGroupdId` 값에서 파생됩니다. 클라이언트 애플리케이션에 `App.java` 파일을 템플릿으로 사용하고, 필요에 따라 같은 폴더에 다른 템플릿을 추가할 수 있습니다. 애플리케이션에 `AppTest.java` 파일을 단위 테스트 템플릿으로 사용하고, 필요에 따라 같은 테스트 폴더에 다른 테스트 코드 파일을 추가할 수 있습니다.
1. 생성된 `pom.xml` 파일의 패키지 종속성을 다음과 같이 업데이트하여, 프로젝트의 `groupId`, `artifactId`, `version`, `name` 속성을 대체합니다.
```
4.0.0examples.aws.apig.simpleCalc.sdk.appSimpleCalc-sdkClientjar1.0-SNAPSHOTSimpleCalc-sdkClienthttp://maven.apache.orgcom.amazonawsaws-java-sdk-core1.11.94my-apig-api-examplessimple-calc-sdk1.0.0junitjunit4.12testcommons-iocommons-io2.5org.apache.maven.pluginsmaven-compiler-plugin3.5.11.81.8
```
**참고**
`aws-java-sdk-core`의 종속 아티팩트 새 버전이 위에서 지정한 버전(`1.11.94`)과 호환되지 않는 경우, `` 태그를 새 버전으로 업데이트해야 합니다.
1. 다음으로, SDK의 `getABOp(GetABOpRequest req)`, `getApiRoot(GetApiRootRequest req)`, `postApiRoot(PostApiRootRequest req)` 메서드를 호출하여, SDK를 사용해 API를 호출하는 방법을 살펴봅니다. 이 메서드는 각각 `GET /{a}/{b}/{op}` API 요청의 페이로드가 포함된 `GET /?a={x}&b={y}&op={operator}`, `POST /`, `{"a": x, "b": y, "op": "operator"}` 메서드에 해당합니다.
다음과 같이 `App.java` 파일을 업데이트합니다.
```
package examples.aws.apig.simpleCalc.sdk.app;
import java.io.IOException;
import com.amazonaws.opensdk.config.ConnectionConfiguration;
import com.amazonaws.opensdk.config.TimeoutConfiguration;
import examples.aws.apig.simpleCalc.sdk.*;
import examples.aws.apig.simpleCalc.sdk.model.*;
import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*;
public class App
{
SimpleCalcSdk sdkClient;
public App() {
initSdk();
}
// The configuration settings are for illustration purposes and may not be a recommended best practice.
private void initSdk() {
sdkClient = SimpleCalcSdk.builder()
.connectionConfiguration(
new ConnectionConfiguration()
.maxConnections(100)
.connectionMaxIdleMillis(1000))
.timeoutConfiguration(
new TimeoutConfiguration()
.httpRequestTimeout(3000)
.totalExecutionTimeout(10000)
.socketTimeout(2000))
.build();
}
// Calling shutdown is not necessary unless you want to exert explicit control of this resource.
public void shutdown() {
sdkClient.shutdown();
}
// GetABOpResult getABOp(GetABOpRequest getABOpRequest)
public Output getResultWithPathParameters(String x, String y, String operator) {
operator = operator.equals("+") ? "add" : operator;
operator = operator.equals("/") ? "div" : operator;
GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator));
return abopResult.getResult().getOutput();
}
public Output getResultWithQueryParameters(String a, String b, String op) {
GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op));
return rootResult.getResult().getOutput();
}
public Output getResultByPostInputBody(Double x, Double y, String o) {
PostApiRootResult postResult = sdkClient.postApiRoot(
new PostApiRootRequest().input(new Input().a(x).b(y).op(o)));
return postResult.getResult().getOutput();
}
public static void main( String[] args )
{
System.out.println( "Simple calc" );
// to begin
App calc = new App();
// call the SimpleCalc API
Output res = calc.getResultWithPathParameters("1", "2", "-");
System.out.printf("GET /1/2/-: %s\n", res.getC());
// Use the type query parameter
res = calc.getResultWithQueryParameters("1", "2", "+");
System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC());
// Call POST with an Input body.
res = calc.getResultByPostInputBody(1.0, 2.0, "*");
System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC());
}
}
```
앞의 예에서 SDK 클라이언트를 인스턴스화하는 데 사용된 구성 설정은 설명용이며, 권장되는 모범 사례라고 볼 수는 없습니다. `sdkClient.shutdown()` 호출도 마찬가지로, 리소스 확보 시점에 대한 정밀한 제어가 필요한 경우 등에 선택하는 옵션입니다.
Java SDK를 사용하여 API를 호출하는 기본 패턴은 이미 살펴보았습니다. 다른 API 메서드 호출에도 이 지침을 적용할 수 있습니다.
# API Gateway에서 생성한 REST API용 Android SDK 사용
이 단원에서는 API Gateway에서 생성된 REST API용 Android SDK의 사용 단계를 살펴봅니다. [API Gateway에서 REST API SDK 생성](how-to-generate-sdk.md)의 단계를 이미 완료한 경우에만 계속 진행할 수 있습니다.
**참고**
생성된 SDK는 Android 4.4 이하 버전에서는 호환되지 않습니다. 자세한 내용은 [Amazon API Gateway 중요 정보](api-gateway-known-issues.md) 단원을 참조하십시오.
**API Gateway가 생성한 Android SDK 설치 및 사용 방법**
1. 앞서 다운로드한 API Gateway가 생성한 .zip 파일의 압축을 풉니다.
1. [Apache Maven](https://maven.apache.org/)(버전 3.x 권장)을 다운로드하여 설치합니다.
1. [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)을 다운로드하여 설치합니다.
1. `JAVA_HOME` 환경 변수를 설정합니다.
1. **mvn install** 명령을 실행해 컴파일된 아티팩트 파일을 로컬 Maven 리포지토리에 설치합니다. 그러면 컴파일된 SDK 라이브러리를 포함하는 `target` 폴더가 생성됩니다.
1. `target` 폴더에서 SDK 파일(이름은 SDK를 생성할 때 지정한 **아티팩트 ID(Artifact Id)** 및 **아티팩트 버전(Artifact Version)**에서 파생됨(예: `simple-calcsdk-1.0.0.jar`))을 `target/lib` 폴더의 다른 모든 라이브러리와 함께 프로젝트의 `lib` 폴더로 복사합니다.
Android Studio를 사용하는 경우, 클라이언트 앱 모듈에 `libs` 폴더를 생성하고 필수 .jar 파일을 복사하여 이 폴더에 붙여 넣습니다. 모듈의 gradle 파일에 있는 종속성 섹션에 다음이 포함되어 있는지 확인합니다.
```
compile fileTree(include: ['*.jar'], dir: 'libs')
compile fileTree(include: ['*.jar'], dir: 'app/libs')
```
복제된 .jar 파일이 선언되지 않도록 합니다.
1. `ApiClientFactory` 클래스를 사용하여 API Gateway에서 생성한 SDK를 초기화합니다. 예:
```
ApiClientFactory factory = new ApiClientFactory();
// Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway.
final SimpleCalcClient client = factory.build(SimpleCalcClient.class);
// Invoke a method:
// For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method:
Result output = client.rootGet("1", "2", "+");
// where the Result class of the SDK corresponds to the Result model of the API.
//
// For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request,
Result output = client.aBOpGet(a, b, c);
// where a, b, c can be "1", "2", "add", respectively.
// For the following API method:
// POST /
// host: ...
// Content-Type: application/json
//
// { "a": 1, "b": 2, "op": "+" }
// you can call invoke it by calling the rootPost method of the SDK as follows:
Input body = new Input();
input.a=1;
input.b=2;
input.op="+";
Result output = client.rootPost(body);
// where the Input class of the SDK corresponds to the Input model of the API.
// Parse the result:
// If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as
String result=output.c;
```
1. Amazon Cognito 자격 증명 제공자를 이용하여 API에 대한 호출에 권한을 부여하려면, 다음 예제와 같이 `ApiClientFactory` 클래스를 사용하여 API Gateway에 의해 생성된 SDK를 통해 일단의 AWS 자격 증명을 전달합니다.
```
// Use CognitoCachingCredentialsProvider to provide AWS credentials
// for the ApiClientFactory
AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(
context, // activity context
"identityPoolId", // Cognito identity pool id
Regions.US_EAST_1 // region of Cognito identity pool
);
ApiClientFactory factory = new ApiClientFactory()
.credentialsProvider(credentialsProvider);
```
1. API Gateway에 의해 생성된 SDK를 사용해 API 키를 설정하려면 다음과 비슷한 코드를 사용합니다.
```
ApiClientFactory factory = new ApiClientFactory()
.apiKey("YOUR_API_KEY");
```
# API Gateway에서 생성한 REST API용 JavaScript SDK 사용
다음 절차에서는 API Gateway에서 생성한 JavaScript SDK를 사용하는 방법을 보여줍니다.
**참고**
이러한 지침에서는 [API Gateway에서 REST API SDK 생성](how-to-generate-sdk.md)의 지침을 이미 완료한 것으로 가정합니다.
**중요**
API에 ANY 메서드만 정의된 경우 생성된 SDK 패키지에는 `apigClient.js` 파일이 포함되지 않으므로 ANY 메서드를 직접 정의할 필요가 없습니다.
**API Gateway가 생성한 REST API용 JavaScript SDK를 설치, 시작, 호출하려면**
1. 앞서 다운로드한 API Gateway가 생성한 .zip 파일의 압축을 풉니다.
1. API Gateway에서 생성한 SDK에 의해 생성된 모든 메서드에 대한 CORS(cross-origin 리소스 공유)를 활성화합니다. 지침은 [API Gateway의 REST API CORS](how-to-cors.md) 단원을 참조하십시오.
1. 웹 페이지에서 다음 스크립트에 참조를 포함시킵니다.
```
```
1. 코드에서 다음과 비슷한 코드를 사용하여 API Gateway에 의해 생성된 SDK를 초기화합니다.
```
var apigClient = apigClientFactory.newClient();
```
AWS 자격 증명과 함께 API Gateway에 의해 생성된 SDK를 초기화하려면 다음과 비슷한 코드를 사용합니다. AWS 자격 증명을 사용하는 경우 API에 대한 모든 요청이 서명되어야 합니다.
```
var apigClient = apigClientFactory.newClient({
accessKey: 'ACCESS_KEY',
secretKey: 'SECRET_KEY',
});
```
API 키를 API Gateway에 의해 생성된 SDK와 함께 사용하려면 다음과 비슷한 코드를 사용하여 API 키를 `Factory` 객체에 파라미터로 전달합니다. API 키를 사용하는 경우 키는 `x-api-key` 헤더의 일부로 지정되며 API에 대한 모든 요청이 서명됩니다. 이는 각 요청에 대해 적절한 CORS 수락 헤더를 설정해야 한다는 의미입니다.
```
var apigClient = apigClientFactory.newClient({
apiKey: 'API_KEY'
});
```
1. 다음과 비슷한 코드를 사용하여 API 메서드를 API Gateway에 호출합니다. 각 호출은 성공 및 실패 콜백과 함께 프라미스를 반환합니다.
```
var params = {
// This is where any modeled request parameters should be added.
// The key is the parameter name, as it is defined in the API in API Gateway.
param0: '',
param1: ''
};
var body = {
// This is where you define the body of the request,
};
var additionalParams = {
// If there are any unmodeled query parameters or headers that must be
// sent with the request, add them here.
headers: {
param0: '',
param1: ''
},
queryParams: {
param0: '',
param1: ''
}
};
apigClient.methodName(params, body, additionalParams)
.then(function(result){
// Add success callback code here.
}).catch( function(result){
// Add error callback code here.
});
```
여기에서는 *methodName*이 메서드 요청의 리소스 경로 및 HTTP 동사로부터 구성됩니다. SimpleCalc API의 경우, 해당하는 SDK 메서드의 API 메서드에 대한
```
1. GET /?a=...&b=...&op=...
2. POST /
{ "a": ..., "b": ..., "op": ...}
3. GET /{a}/{b}/{op}
```
SDK 메서드는 다음과 같습니다.
```
1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters
2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...}
3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters
```
# API Gateway에서 생성한 REST API용 Ruby SDK 사용
다음 절차에서는 API Gateway에서 생성한 Ruby SDK를 사용하는 방법을 보여줍니다.
**참고**
이 지침에서는 [API Gateway에서 REST API SDK 생성](how-to-generate-sdk.md)의 지침을 이미 완료한 것으로 가정합니다.
**API Gateway가 생성한 REST API용 Ruby SDK를 설치, 인스턴스화, 호출하려면**
1. 다운로드한 Ruby SDK 파일 압축을 풉니다. 생성된 SDK 원본은 다음과 같이 표시됩니다.
![\[다운로드한 Ruby SDK 파일을 Ruby 모듈에 압축 해제\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png)
1. 터미널 창에서 다음 셸 명령을 사용하여 생성된 SDK 원본에서 Ruby Gem을 구축합니다.
```
# change to /simplecalc-sdk directory
cd simplecalc-sdk
# build the generated gem
gem build simplecalc-sdk.gemspec
```
이 작업 후 **simplecalc-sdk-1.0.0.gem**을 사용할 수 있게 됩니다.
1. Gem 설치:
```
gem install simplecalc-sdk-1.0.0.gem
```
1. 클라이언트 애플리케이션을 생성합니다. 앱에서 Ruby SDK 클라이언트를 인스턴스화하고 초기화합니다.
```
require 'simplecalc-sdk'
client = SimpleCalc::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50
)
```
API에 `AWS_IAM` 유형의 권한 부여가 구성되어 있는 경우, 초기화 도중 `accessKey` 및 `secretKey`를 제공하여 호출자의 AWS 자격 증명을 포함할 수 있습니다.
```
require 'pet-sdk'
client = Pet::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50,
access_key_id: 'ACCESS_KEY',
secret_access_key: 'SECRET_KEY'
)
```
1. 앱에서 SDK를 통해 API를 호출합니다.
**작은 정보**
SDK 메서드 호출 규칙에 익숙하지 않다면 생성된 SDK `client.rb` 폴더에 있는 `lib` 파일을 검토할 수 있습니다. 이 폴더에는 지원되는 각각의 API 메서드 호출 설명서가 포함되어 있습니다.
지원되는 연산을 검색하려면
```
# to show supported operations:
puts client.operation_names
```
이로 인해 각각 `GET /?a={.}&b={.}&op={.}`, `GET /{a}/{b}/{op}` 및 `POST /` API 메서드와 `{a:"…", b:"…", op:"…"}` 형식의 페이로드에 해당하는 다음의 표시가 나타납니다.
```
[:get_api_root, :get_ab_op, :post_api_root]
```
`GET /?a=1&b=2&op=+` API 메서드를 호출하려면 다음 Ruby SDK 메서드를 호출하십시오.
```
resp = client.get_api_root({a:"1", b:"2", op:"+"})
```
`POST /` 페이로드가 포함된 `{a: "1", b: "2", "op": "+"}` API 메서드를 호출하려면 다음 Ruby SDK 메서드를 호출하세요.
```
resp = client.post_api_root(input: {a:"1", b:"2", op:"+"})
```
`GET /1/2/+` API 메서드를 호출하려면 다음 Ruby SDK 메서드를 호출하십시오.
```
resp = client.get_ab_op({a:"1", b:"2", op:"+"})
```
SDK 메서드 호출이 성공하면 다음과 같은 응답을 반환합니다.
```
resp : {
result: {
input: {
a: 1,
b: 2,
op: "+"
},
output: {
c: 3
}
}
}
```
# Objective-C 또는 Swift에서 API Gateway에 의해 생성되는 REST API용 iOS SDK 사용
이 자습서에서는 Objective-C 또는 Swift 앱에서 API Gateway에 의해 생성되는 REST API용 iOS SDK를 사용하여 기본 API를 호출하는 방법을 보여줍니다. [SimpleCalc API](simple-calc-lambda-api.md)를 예제로 사용하여 다음 주제를 설명합니다.
+ 필요한 AWS Mobile SDK 구성 요소를 Xcode 프로젝트에 설치하는 방법
+ API 메서드를 호출하기 전에 API 클라이언트 객체를 생성하는 방법
+ API 클라이언트 객체에서 해당 SDK 메서드를 통해 API 메서드를 호출하는 방법
+ 메서드 입력을 준비하고 SDK의 해당 모델 클래스를 사용하여 결과를 구문 분석하는 방법
**Topics**
+ [생성된 iOS SDK(Objective-C)를 사용하여 API 호출](#how-to-use-sdk-ios-objc)
+ [API를 호출하기 위해 생성된 iOS SDK(Swift) 사용](#how-to-generate-sdk-ios-swift)
## 생성된 iOS SDK(Objective-C)를 사용하여 API 호출
다음 절차를 시작하기 전에 Objective-C에서 iOS에 대한 [API Gateway에서 REST API SDK 생성](how-to-generate-sdk.md)의 단계를 완료하고 생성된 SDK에 대한 .zip 파일을 다운로드해야 합니다.
### Objective-C 프로젝트에서 API Gateway에 의해 생성되는 iOS SDK 및 AWS Mobile SDK 설치
다음 절차에서는 SDK를 설치하는 방법을 설명합니다.
**Objective-C에서 API Gateway가 생성한 iOS SDK를 설치하고 사용하려면**
1. 앞서 다운로드한 API Gateway가 생성한 .zip 파일의 압축을 풉니다. [SimpleCalc API](simple-calc-lambda-api.md)를 사용하여 압축 해제된 SDK 폴더의 이름을 **sdk\$1objc\$1simple\$1calc** 등으로 바꿉니다. 이 SDK 폴더에는 `README.md` 파일과 `Podfile` 파일이 있습니다. `README.md` 파일에는 SDK를 설치하고 사용하기 위한 지침이 포함되어 있습니다. 이 자습서는 이러한 지침에 대한 세부 정보를 제공합니다. 설치 시 [CocoaPods](https://cocoapods.org)를 활용해 필요한 API Gateway 라이브러리와 기타 종속 AWS Mobile SDK 구성 요소를 가져옵니다. `Podfile`을 업데이트하여 앱의 Xcode 프로젝트로 SDK를 가져와야 합니다. 아카이빙을 해제한 SDK 폴더에는 사용자 API에서 생성한 SDK의 소스 코드를 포함하는 `generated-src` 폴더도 포함되어 있습니다.
1. Xcode를 시작하고 새로운 iOS Objective-C 프로젝트를 생성합니다. 프로젝트의 대상을 기록해 둡니다. `Podfile`에 이를 설정해야 합니다.
![\[Xcode에서 대상을 찾습니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png)
1. CocoaPods를 이용해 AWS Mobile SDK for iOS를 Xcode 프로젝트로 가져오려면 다음과 같이 하십시오.
1. 터미널 창에 다음 명령을 실행하여 CocoaPods를 설치합니다.
```
sudo gem install cocoapods
pod setup
```
1. 압축을 푼 SDK 폴더에서 `Podfile` 파일을 복사하여 Xcode 프로젝트 파일을 포함하는 동일 디렉터리에 추가합니다. 다음 블록:
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
을 프로젝트 대상 이름: 으로 바꿉니다.
```
target 'app_objc_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
Xcode 프로젝트에 이미 `Podfile`이라는 파일이 있는 경우, 다음 코드 줄을 추가합니다.
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. 터미널 창을 열고 다음 명령을 실행합니다.
```
pod install
```
그러면 API Gateway 구성 요소와 기타 종속 AWS Mobile SDK 구성 요소가 설치됩니다.
1. Xcode 프로젝트를 닫은 후 `.xcworkspace` 파일을 열어 Xcode를 다시 시작합니다.
1. 압축을 푼 SDK의 `.h` 디렉터리에 포함된 모든 `.m` 및 `generated-src` 파일을 Xcode 프로젝트에 추가합니다.
![\[.h 및 .m 파일은 generated-src에 있습니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png)
AWS Mobile SDK를 명시적으로 다운로드하거나 [Carthage](https://github.com/Carthage/Carthage#installing-carthage)를 이용해 프로젝트로 AWS Mobile SDK for iOS Objective-C를 가져오려면 *README.md* 파일의 지침을 따르세요. 이러한 옵션 중 하나만 사용하여 AWS Mobile SDK를 가져와야 합니다.
### Objective-C 프로젝트에서 API Gateway에 의해 생성되는 iOS SDK를 사용하여 API 메서드 호출
이 [SimpleCalc API](simple-calc-lambda-api.md)에 대한 `SIMPLE_CALC` 접두사와 메서드의 입력(`Input`) 및 출력(`Result`)에 대한 두 모델을 사용하여 SDK를 생성한 경우 SDK에서 결과 API 클라이언트 클래스는 `SIMPLE_CALCSimpleCalcClient`이고 해당 데이터 클래스는 각각 `SIMPLE_CALCInput` 및 `SIMPLE_CALCResult`입니다. API 요청 및 응답은 SDK 메서드에 다음과 같이 매핑됩니다.
+ 다음의 API 요청이
```
GET /?a=...&b=...&op=...
```
다음의 SDK 메서드가 됩니다.
```
(AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b
```
`AWSTask.result` 모델이 메서드 응답에 추가된 경우 `SIMPLE_CALCResult` 속성은 `Result` 유형입니다. 그렇지 않은 경우 속성은 `NSDictionary` 유형입니다.
+ 다음의 이 API 요청이
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
다음의 SDK 메서드가 됩니다.
```
(AWSTask *)rootPost:(SIMPLE_CALCInput *)body
```
+ 다음의 API 요청이
```
GET /{a}/{b}/{op}
```
다음의 SDK 메서드가 됩니다.
```
(AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op
```
다음 절차에서는 Objective-C 앱 소스 코드에서 API 메서드를 호출하는 방법(예: `viewDidLoad` 파일에서 `ViewController.m` 위임자의 일부로 호출)을 설명합니다.
**API Gateway가 생성한 iOS SDK를 통해 API를 호출하려면**
1. API 클라이언트 클래스 헤더 파일을 가져와 앱에서 API 클라이언트 클래스를 호출할 수 있도록 합니다.
```
#import "SIMPLE_CALCSimpleCalc.h"
```
`#import` 명령문은 두 모델 클래스에 대한 `SIMPLE_CALCInput.h` 및 `SIMPLE_CALCResult.h`도 가져옵니다.
1. API 클라이언트 클래스 인스턴스화:
```
SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient];
```
API를 통해 Amazon Cognito를 사용하려면 다음과 같이 기본 `AWSServiceManager` 객체에 `defaultServiceConfiguration` 속성을 설정한 후 `defaultClient` 메서드를 호출해 API 클라이언트 객체를 생성합니다(앞의 예와 같음).
```
AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id];
AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds];
AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
```
1. `GET /?a=1&b=2&op=+` 메서드를 호출하여 `1+2`를 수행합니다.
```
[[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField1.text = [self handleApiResponse:task];
return nil;
}];
```
여기에서 헬퍼 함수 `handleApiResponse:task`는 결과 서식을 텍스트 필드 (`_textField1`)에 표시할 문자열로 지정합니다.
```
- (NSString *)handleApiResponse:(AWSTask *)task {
if (task.error != nil) {
return [NSString stringWithFormat: @"Error: %@", task.error.description];
} else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) {
return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c];
}
return nil;
}
```
표시되는 결과는 `1 + 2 = 3`입니다.
1. 페이로드와 함께 `POST /` 메서드를 호출하여 `1-2`를 수행합니다.
```
SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init];
input.a = [NSNumber numberWithInt:1];
input.b = [NSNumber numberWithInt:2];
input.op = @"-";
[[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField2.text = [self handleApiResponse:task];
return nil;
}];
```
표시되는 결과는 `1 - 2 = -1`입니다.
1. `GET /{a}/{b}/{op}`를 호출하여 `1/2`를 수행합니다.
```
[[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField3.text = [self handleApiResponse:task];
return nil;
}];
```
표시되는 결과는 `1 div 2 = 0.5`입니다. 여기서 `div` 자리에 `/`가 사용되는데, 이유는 백엔드의 [간단한 Lambda 함수](simple-calc-nodejs-lambda-function.md)가 URL로 인코딩된 경로 변수를 처리하지 않기 때문입니다.
## API를 호출하기 위해 생성된 iOS SDK(Swift) 사용
다음 절차를 시작하기 전에 Swift에서 iOS에 대한 [API Gateway에서 REST API SDK 생성](how-to-generate-sdk.md)의 단계를 완료하고 생성된 SDK에 대한 .zip 파일을 다운로드해야 합니다.
**Topics**
+ [AWS Mobile SDK 및 API Gateway 생성 SDK를 Swift 프로젝트에 설치](#use-sdk-ios-swift-install-sdk)
+ [Swift 프로젝트에서 API Gateway가 생성한 iOS SDK를 통해 API 메서드 호출](#use-sdk-ios-swift-call-api)
### AWS Mobile SDK 및 API Gateway 생성 SDK를 Swift 프로젝트에 설치
다음 절차에서는 SDK를 설치하는 방법을 설명합니다.
**Swift에서 API Gateway가 생성한 iOS SDK를 설치하고 사용하려면**
1. 앞서 다운로드한 API Gateway가 생성한 .zip 파일의 압축을 풉니다. [SimpleCalc API](simple-calc-lambda-api.md)를 사용하여 압축 해제된 SDK 폴더의 이름을 **sdk\$1swift\$1simple\$1calc** 등으로 바꿉니다. 이 SDK 폴더에는 `README.md` 파일과 `Podfile` 파일이 있습니다. `README.md` 파일에는 SDK를 설치하고 사용하기 위한 지침이 포함되어 있습니다. 이 자습서는 이러한 지침에 대한 세부 정보를 제공합니다. 설치 시 [CocoaPods](https://cocoapods.org)를 활용해 필요한 AWS Mobile SDK 구성 요소를 가져옵니다. `Podfile`을 업데이트하여 Swift 앱의 Xcode 프로젝트로 SDK를 가져와야 합니다. 아카이빙을 해제한 SDK 폴더에는 사용자 API에서 생성한 SDK의 소스 코드를 포함하는 `generated-src` 폴더도 포함되어 있습니다.
1. Xcode를 시작하고 새로운 iOS Swift 프로젝트를 생성합니다. 프로젝트의 대상을 기록해 둡니다. `Podfile`에 이를 설정해야 합니다.
![\[Xcode에서 대상을 찾습니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png)
1. CocoaPods를 이용해 필요한 AWS Mobile SDK 구성 요소를 Xcode 프로젝트로 가져오려면 다음과 같이 합니다.
1. CocoaPods가 아직 설치되어 있지 않은 경우 터미널 창에 다음 명령을 실행하여 설치합니다.
```
sudo gem install cocoapods
pod setup
```
1. 압축을 푼 SDK 폴더에서 `Podfile` 파일을 복사하여 Xcode 프로젝트 파일을 포함하는 동일 디렉터리에 추가합니다. 다음 블록:
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
프로젝트 대상 이름은 다음과 같습니다.
```
target 'app_swift_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
Xcode 프로젝트에 이미 올바른 대상의 `Podfile`이 있는 경우, 다음 코드 줄을 `do ... end` 루프에 추가하기만 하면 됩니다.
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. 터미널 창을 열고 앱 디렉터리에서 다음 명령을 실행합니다.
```
pod install
```
그러면 앱의 프로젝트에 API Gateway 구성 요소와 종속 AWS Mobile SDK 구성 요소가 설치됩니다.
1. Xcode 프로젝트를 닫은 후 `*.xcworkspace` 파일을 열어 Xcode를 다시 시작합니다.
1. 추출한 `.h` 디렉터리에서 SDK의 모든 헤더 파일(`.swift`) 및 Swift 소스 코드 파일(`generated-src`)을 Xcode 프로젝트에 추가합니다.
![\[.h 및 .swift 파일은 generated-src에 있습니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png)
1. Swift 코드 프로젝트에서 AWS Mobile SDK의 Objective-C 라이브러리 호출을 활성화하려면 Xcode 프로젝트 구성의 **Swift Compiler - General** 설정에서 **Objective-C Bridging Header** 속성에 `Bridging_Header.h` 파일 경로를 설정합니다.
![\[Swift Compiler - General에서 Bridging_Header.h 파일 경로를 설정합니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png)
**작은 정보**
Xcode의 검색 상자에 **bridging**을 입력하여 **Objective-C Bridging Header** 속성을 찾을 수 있습니다.
1. Xcode 프로젝트를 구축하여 적절하게 구성되어 있는지 확인한 후 다음 단계로 진행합니다. Xcode가 AWS Mobile SDK에 지원되는 Swift보다 최신 버전을 사용하는 경우, Swift 컴파일러 오류를 받게 됩니다. 이 경우 **Swift Compiler - Version** 설정에서 **Use Legacy Swift Language Version** 속성을 **예**로 설정합니다.
![\[Legacy Swift Language Version 속성을 Yes로 설정합니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png)
AWS Mobile SDK를 명시적으로 다운로드하거나 [Carthage](https://github.com/Carthage/Carthage#installing-carthage)를 이용해 Swift에서 AWS Mobile SDK for iOS를 프로젝트로 가져오려면 SDK 패키지와 함께 제공된 `README.md` 파일의 지침을 따릅니다. 이러한 옵션 중 하나만 사용하여 AWS Mobile SDK를 가져와야 합니다.
### Swift 프로젝트에서 API Gateway가 생성한 iOS SDK를 통해 API 메서드 호출
API 요청 및 응답의 입력(`Input`) 및 출력(`Result`)을 설명하는 두 가지 모델을 사용하여 이 [SimpleCalc API](simple-calc-lambda-api.md)에 대한 `SIMPLE_CALC` 접두사를 사용하여 SDK를 생성한 경우 SDK에서 결과 API 클라이언트 클래스는 `SIMPLE_CALCSimpleCalcClient`가 되고 해당 데이터 클래스는 각각 `SIMPLE_CALCInput` 및 `SIMPLE_CALCResult`입니다. API 요청 및 응답은 SDK 메서드에 다음과 같이 매핑됩니다.
+ 다음의 API 요청이
```
GET /?a=...&b=...&op=...
```
다음의 SDK 메서드가 됩니다.
```
public func rootGet(op: String?, a: String?, b: String?) -> AWSTask
```
`AWSTask.result` 모델이 메서드 응답에 추가된 경우 `SIMPLE_CALCResult` 속성은 `Result` 유형입니다. 그렇지 않으면 `NSDictionary` 유형입니다.
+ 다음의 이 API 요청이
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
다음의 SDK 메서드가 됩니다.
```
public func rootPost(body: SIMPLE_CALCInput) -> AWSTask
```
+ 다음의 API 요청이
```
GET /{a}/{b}/{op}
```
다음의 SDK 메서드가 됩니다.
```
public func aBOpGet(a: String, b: String, op: String) -> AWSTask
```
다음 절차에서는 Swift 앱 소스 코드에서 API 메서드를 호출하는 방법(예: `viewDidLoad()` 파일에서 `ViewController.m` 위임자의 일부로 호출)을 설명합니다.
**API Gateway가 생성한 iOS SDK를 통해 API를 호출하려면**
1. API 클라이언트 클래스 인스턴스화:
```
let client = SIMPLE_CALCSimpleCalcClient.default()
```
API를 통해 Amazon Cognito를 사용하려면 (다음과 같이) 기본 AWS 서비스 구성을 설정한 후, (이전과 같이) `default` 메서드를 가져옵니다.
```
let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id")
let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider)
AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration
```
1. `GET /?a=1&b=2&op=+` 메서드를 호출하여 `1+2`를 수행합니다.
```
client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
헬퍼 함수 `self.showResult(task)`가 콘솔에 결과나 오류를 인쇄합니다. 예:
```
func showResult(task: AWSTask) {
if let error = task.error {
print("Error: \(error)")
} else if let result = task.result {
if result is SIMPLE_CALCResult {
let res = result as! SIMPLE_CALCResult
print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!))
} else if result is NSDictionary {
let res = result as! NSDictionary
print("NSDictionary: \(res)")
}
}
}
```
생산 앱에서 텍스트 필드에 결과나 오류를 표시할 수 있습니다. 표시되는 결과는 `1 + 2 = 3`입니다.
1. 페이로드와 함께 `POST /` 메서드를 호출하여 `1-2`를 수행합니다.
```
let body = SIMPLE_CALCInput()
body.a=1
body.b=2
body.op="-"
client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
표시되는 결과는 `1 - 2 = -1`입니다.
1. `GET /{a}/{b}/{op}`를 호출하여 `1/2`를 수행합니다.
```
client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
표시되는 결과는 `1 div 2 = 0.5`입니다. 여기서 `div` 자리에 `/`가 사용되는데, 이유는 백엔드의 [간단한 Lambda 함수](simple-calc-nodejs-lambda-function.md)가 URL로 인코딩된 경로 변수를 처리하지 않기 때문입니다.
# API Gateway에서 OpenAPI를 사용하여 REST API 개발
API Gateway를 사용하여 외부 정의 파일에서 API Gateway로 REST API를 가져올 수 있습니다. 현재 API Gateway는 [Amazon API Gateway의 REST API 중요 정보](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis)에 나열된 파일을 제외하고 [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) 및 [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) 정의 파일을 지원합니다. 새 정의로 덮어쓰기를 해서API를 업데이트하거나, 정의를 기존 API에 병합할 수 있습니다. 요청 URL에서 `mode` 쿼리 파라미터를 사용하여 옵션을 지정합니다.
API Gateway 콘솔에서 API 가져오기 기능을 사용하려면 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)을 참조하세요.
**Topics**
+ [엣지 최적화된 API를 API Gateway로 가져오기](import-edge-optimized-api.md)
+ [리전 API를 API Gateway로 가져오기](import-export-api-endpoints.md)
+ [OpenAPI 파일을 가져와 기존 API 정의 업데이트](api-gateway-import-api-update.md)
+ [OpenAPI `basePath` 속성 설정](api-gateway-import-api-basePath.md)
+ [AWSOpenAPI 가져오기를 위한 변수](import-api-aws-variables.md)
+ [API를 API Gateway로 가져올 때 발생하는 오류 및 경고](api-gateway-import-api-errors-warnings.md)
+ [API Gateway에서 REST API 내보내기](api-gateway-export-api.md)
# 엣지 최적화된 API를 API Gateway로 가져오기
API OpenAPI 정의 파일을 가져와 `EDGE` 엔드포인트 유형을 OpenAPI 파일 외에 추가 입력으로 가져오기 작업에 지정함으로써 새로운 엣지 최적화 API를 생성할 수 있습니다. API Gateway 콘솔, AWS CLI 또는 AWS SDK를 사용하여 이를 수행할 수 있습니다.
API Gateway 콘솔에서 API 가져오기 기능을 사용하려면 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)을 참조하세요.
**Topics**
+ [API Gateway 콘솔을 사용하여 엣지 최적화 API 가져오기](#import-edge-optimized-api-with-console)
+ [AWS CLI를 사용해 엣지 최적화 API 가져오기](#import-edge-optimized-api-with-awscli)
## API Gateway 콘솔을 사용하여 엣지 최적화 API 가져오기
API Gateway 콘솔을 사용해 엣지 최적화 API 가져오려면 다음을 따릅니다.
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. **API 생성**을 선택합니다.
1. **REST API** 아래에서 **가져오기**를 선택합니다.
1. API의 OpenAPI 정의를 복사하여 코드 편집기에 붙여넣거나 **파일 선택**을 선택하여 로컬 드라이브로부터 OpenAPI 파일을 로드합니다.
1. **API 엔드포인트 유형**에서 **엣지 최적화**를 선택합니다.
1. OpenAPI 정의를 가져오려면 **API 생성**을 선택합니다.
## AWS CLI를 사용해 엣지 최적화 API 가져오기
다음 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 명령은 OpenAPI 정의 파일에서 API를 가져와 새로운 엣지 최적화 API를 생성합니다.
```
aws apigateway import-rest-api \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
또는 다음과 같이 `endpointConfigurationTypes`에 대한 `EDGE` 쿼리 문자열 파라미터의 명시적인 사양을 사용합니다.
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=EDGE \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# 리전 API를 API Gateway로 가져오기
API를 가져올 때 API에 대해 리전 엔드포인트 구성을 선택할 수 있습니다. API Gateway 콘솔, AWS CLI 또는 AWS SDK를 사용할 수 있습니다.
API를 내보낼 때 내보낸 API 정의에 API 엔드포인트 구성은 포함되지 않습니다.
API Gateway 콘솔에서 API 가져오기 기능을 사용하려면 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)을 참조하세요.
**Topics**
+ [API Gateway 콘솔을 사용하여 리전 API 가져오기](#import-regional-api-with-console)
+ [AWS CLI를 사용하여 리전 API 가져오기](#import-regional-api-with-awscli)
## API Gateway 콘솔을 사용하여 리전 API 가져오기
API Gateway 콘솔을 사용하여 리전 엔드포인트의 API를 가져오려면 다음과 같이 합니다.
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. **API 생성**을 선택합니다.
1. **REST API** 아래에서 **가져오기**를 선택합니다.
1. API의 OpenAPI 정의를 복사하여 코드 편집기에 붙여넣거나 **파일 선택**을 선택하여 로컬 드라이브로부터 OpenAPI 파일을 로드합니다.
1. **API 엔드포인트 유형**에서 **지역**을 선택합니다.
1. OpenAPI 정의를 가져오려면 **API 생성**을 선택합니다.
## AWS CLI를 사용하여 리전 API 가져오기
다음 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 명령은 OpenAPI 정의 파일을 가져오고 엔드포인트 유형을 리전으로 설정합니다.
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=REGIONAL \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# OpenAPI 파일을 가져와 기존 API 정의 업데이트
단계와 단계 변수 또는 API 키에 대한 참조뿐 아니라 엔드포인트 구성을 변경하지 않은 상태에서 기존 API를 업데이트만할 목적으로 API 정의를 가져올 수 있습니다.
가져와 업데이트하는 작업은 병합 또는 덮어쓰기의 두 가지 모드에서 발생할 수 있습니다.
API(`A`)를 다른 API(`B`)로 병합할 때 두 API가 충돌하는 정의를 공유하지 않으면 그 결과로 얻는 API는 `A`와 `B`의 정의를 모두 유지합니다. 충돌이 발생하는 경우 병합하는 API(`A`)의 메서드 정의가 병합되는 API(`B`)의 해당하는 메서드 정의를 재정의합니다. 예를 들어 `B`가 다음 메서드를 선언하여 `200` 및 `206` 응답을 반환했다고 가정하겠습니다.
```
GET /a
POST /a
```
그리고 `A`는 다음 메서드를 선언하여 `200` 및 `400` 응답을 반환합니다.
```
GET /a
```
`A`를 `B`에 병합하면 그 결과로 얻는 API는 다음 메서드를 출력합니다.
```
GET /a
```
`200` 및 `400` 응답을 반환하고
```
POST /a
```
`200` 및 `206` 응답을 반환합니다.
외부 API 정의를 여러 개의 더 작은 파트로 분해하고 한 번에 한 파트의 변경사항만 적용할 경우 API 병합이 유용합니다. 예를 들어, 여러 팀이 API의 서로 다른 파트를 담당하고 있고 다른 비율로 변경사항을 사용할 수 있는 경우 병합이 발생할 수 있습니다. 이 모드에서는 가져온 정의에 특별히 정의되지 않은 기존 API의 항목이 그대로 유지됩니다.
API(`A`)가 다른 API(`B`)를 덮어쓰면 그 결과로 얻는 API는 덮어쓴 API(`A`)의 정의를 취합니다. API 덮어쓰기는 외부 API 정의에 API의 전체 정의가 포함된 경우 유용합니다. 이 모드에서는 가져온 정의에 특별히 정의되지 않은 기존 API의 항목이 삭제됩니다.
API를 병합하려면 `PUT`에 `https://apigateway..amazonaws.com/restapis/?mode=merge` 요청을 제출하세요. `restapi_id` 경로 파라미터 값이 제공된 API 정의가 병합되는 API를 지정합니다.
다음 코드 조각에서는 JSON의 OpenAPI API 정의를 페이로드로 API Gateway의 이미 지정된 API와 병합하는 `PUT` 요청 예를 보여줍니다.
```
PUT /restapis/?mode=merge
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
병합 업데이트 작업에서는 2개의 전체 API 정의를 가져와서 함께 병합합니다. 소규모 증분 변경사항의 경우 [리소스 업데이트](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html) 작업을 사용할 수 있습니다.
API를 덮어쓰려면 `PUT` 요청을 `https://apigateway..amazonaws.com/restapis/?mode=overwrite`에 제출하세요. `restapi_id` 경로 파라미터는 제공된 API 정의로 덮어쓰는 API를 지정합니다.
다음 코드 조각에서는 JSON 형식의 OpenAPI 정의의 페이로드가 포함된 덮어쓰기 요청의 예를 보여줍니다.
```
PUT /restapis/?mode=overwrite
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
`mode` 쿼리 파라미터가 지정되지 않은 경우 병합이 사용됩니다.
**참고**
`PUT` 작업은 idempotent 방식이지만 원자성 작업은 아닙니다. 즉, 처리 과정에서 시스템 오류가 발생하면 API의 상태가 좋지 않을 수 있습니다. 그러나 작업을 성공적으로 반복하면 API가 첫 번째 작업이 성공한 것과 동일한 최종 상태가 됩니다.
# OpenAPI `basePath` 속성 설정
[OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md)에서 `basePath` 속성을 사용하여 `paths` 속성에 정의된 각 경로 앞에 하나 이상의 경로 파트를 제공할 수 있습니다. API Gateway에 리소스 경로를 표시할 여러 방법이 있기 때문에 Import API 기능은 가져오기 과정에서 `basePath` 속성을 해석하기 위한 옵션(무시, 앞에 추가, 분할)을 제공합니다.
[https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/)에서, `basePath`는 더 이상 상위 수준 속성이 아닙니다. 대신 API Gateway는 [서버 변수](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject)를 규칙으로 사용합니다. Import API 기능은 가져오기 중에 기본 경로를 해석하기 위한 동일한 옵션을 제공합니다. 기본 경로는 다음과 같이 식별됩니다.
+ API에 `basePath` 변수가 없을 경우 Import API 기능은 `server.url` 문자열을 확인하여 `"/"` 위의 경로를 포함하는지 확인합니다. 포함할 경우 이 경로가 기본 경로로 사용됩니다.
+ API에 `basePath` 변수가 한 개만 있을 경우 Import API 기능은 `server.url`에 참조되지 않았더라도 이 변수를 기본 경로로 사용합니다.
+ API에 `basePath` 변수가 여러 개 있을 경우 Import API 기능은 첫 번째 변수만 기본 경로로 사용합니다.
## Ignore
OpenAPI 파일에서 `basePath` 값이 `/a/b/c`이고, `paths` 속성에 `/e` 및 `/f`가 포함된 경우 다음 `POST` 또는 `PUT` 요청은
```
POST /restapis?mode=import&basepath=ignore
```
```
PUT /restapis/api_id?basepath=ignore
```
API에 다음 리소스를 생성합니다.
+ `/`
+ `/e`
+ `/f`
그 결과 `basePath`는 존재하지 않는 것처럼 처리되고, 선언된 모든 API 리소스가 호스트를 기준으로 제공됩니다. 예를 들어, 프로덕션 단계를 참조하는 *Base Path* 및 *Stage* 값을 포함하지 않는 API 매핑이 포함된 사용자 지정 도메인 이름이 있는 경우 이 옵션을 사용할 수 있습니다.
**참고**
API Gateway는 정의 파일에 명시적으로 선언되지 않은 경우에도 자동으로 루트 리소스를 생성합니다.
지정하지 않을 경우 `basePath`는 기본적으로 `ignore`를 사용합니다.
## Prepend
OpenAPI 파일에서 `basePath` 값이 `/a/b/c`이고, `paths` 속성에 `/e` 및 `/f`가 포함된 경우 다음 `POST` 또는 `PUT` 요청은
```
POST /restapis?mode=import&basepath=prepend
```
```
PUT /restapis/api_id?basepath=prepend
```
API에 다음 리소스를 생성합니다.
+ `/`
+ `/a`
+ `/a/b`
+ `/a/b/c`
+ `/a/b/c/e`
+ `/a/b/c/f`
그 결과 `basePath`는 (메서드 없는) 추가 리소스 지정으로 처리되고 이 리소스를 선언된 리소스 세트에 추가합니다. 예를 들어, 다른 팀이 API의 다른 파트를 담당하고 있고 `basePath`가 각 팀의 API 파트에 대한 경로 위치를 참조할 수 있는 경우 이 옵션을 사용할 수 있습니다.
**참고**
API Gateway는 정의에 명시적으로 선언되지 않은 경우에도 자동으로 중간 리소스를 생성합니다.
## 분할
OpenAPI 파일에서 `basePath` 값이 `/a/b/c`이고, `paths` 속성에 `/e` 및 `/f`가 포함된 경우 다음 `POST` 또는 `PUT` 요청은
```
POST /restapis?mode=import&basepath=split
```
```
PUT /restapis/api_id?basepath=split
```
API에 다음 리소스를 생성합니다.
+ `/`
+ `/b`
+ `/b/c`
+ `/b/c/e`
+ `/b/c/f`
그 결과 가장 위의 경로 파트 `/a`를 리소스 경로의 시작으로 처리하고 API내에 추가 리소스(메서드 없음)를 생성합니다. 예를 들어, `a`가 API 일부로 공개할 단계 이름인 경우 이 옵션을 사용할 수 있습니다.
# AWSOpenAPI 가져오기를 위한 변수
OpenAPI 정의에서 다음 AWS 변수를 사용할 수 있습니다. API Gateway는 API를 가져올 때 변수를 확인합니다. 변수를 지정하려면 `${variable-name}`을 사용합니다. 다음 표에서는 사용 가능한 AWS 변수를 설명합니다.
| 변수 이름 | 설명 |
| --- | --- |
| AWS::AccountId | API를 가져오는 AWS 계정 ID입니다. 예: 123456789012. |
| AWS::Partition | API를 가져올 AWS 파티션입니다. 표준 AWS 리전에서 파티션은 aws입니다. |
| AWS::Region | API를 가져오는 AWS 리전입니다. 예: us-east-2. |
## AWS 변수 예제
다음 예제에서는 AWS 변수를 사용하여 통합에 대한 AWS Lambda 함수를 지정합니다.
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "tasks-api"
version: "v1.0"
paths:
/:
get:
summary: List tasks
description: Returns a list of tasks
responses:
200:
description: "OK"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Task"
500:
description: "Internal Server Error"
content: {}
x-amazon-apigateway-integration:
uri:
arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
httpMethod: "POST"
contentHandling: "CONVERT_TO_TEXT"
type: "aws_proxy"
components:
schemas:
Task:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
```
------
# API를 API Gateway로 가져올 때 발생하는 오류 및 경고
외부 정의 파일을 API Gateway로 가져오면 API Gateway에서 경고 및 오류가 발생할 수 있습니다. 다음 섹션에서는 가져오기 중에 발생할 수 있는 오류 및 경고를 설명합니다.
## 가져오기 중 오류 발생
가져오기 중에 잘못된 OpenAPI 문서 같은 주요 문제에 대한 오류가 생성될 수 있습니다. 오류가 실패한 응답에서 예외(예: `BadRequestException`)로 반환됩니다. 오류가 발생하면 새 API 정의가 삭제되고 기존 API가 변경되지 않습니다.
## 가져오기 중 경고 발생
가져오는 동안 누락된 모델 참조와 같은 사소한 문제에 대한 경고가 생성될 수 있습니다. 경고가 발생한 경우 `failonwarnings=false` 쿼리 표현식이 요청 URL에 추가되면 작업이 계속됩니다. 그렇지 않으면 업데이트가 롤백됩니다. 기본적으로 `failonwarnings`는 `false`로 설정됩니다. 이 경우 경고가 결과 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스에서 필드로 반환됩니다. 그렇지 않으면 경고가 예외의 메시지로 반환됩니다.
# API Gateway에서 REST API 내보내기
API Gateway 콘솔을 사용하거나 달리 API Gateway에서 REST API를 생성 및 구성한 경우, Amazon API Gateway Control Service의 일부인 API Gateway API 내보내기를 사용하여 이를 OpenAPI 파일로 내보낼 수 있습니다. API Gateway 내보내기 API를 사용하려면 API 요청에 서명해야 합니다. 요청 서명에 대한 자세한 내용은 **IAM 사용 설명서의 [AWS API 요청에 서명](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)을 참조하세요. [Postman](https://www.postman.com) 확장뿐만 아니라 API Gateway 통합 확장도 내보낸 OpenAPI 정의 파일에 포함시킬 수 있습니다.
**참고**
AWS CLI를 사용하여 API를 내보낼 경우 다음 예와 같이 확장 파라미터를 포함시켜서 `x-amazon-apigateway-request-validator` 확장이 포함되도록 하세요.
```
aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json
```
페이로드가 `application/json` 유형이 아닐 경우 API를 내보낼 수 없습니다. 내보내기를 시도하면 JSON 본문 모델이 없다는 오류 응답을 받게 됩니다.
## REST API 내보내기 요청
내보내기 API를 사용하여 GET 요청을 제출하고 내보낼 API를 URL 경로의 일부로 지정하여 기존 REST API를 내보내세요. 요청 URL의 형식은 다음과 같습니다.
------
#### [ OpenAPI 3.0 ]
```
https:///restapis//stages//exports/oas30
```
------
#### [ OpenAPI 2.0 ]
```
https:///restapis//stages//exports/swagger
```
------
API Gateway 확장(`integration` 값 사용) 또는 Postman 확장을 포함할지(`postman` 값 사용) 지정하는 `extensions` 쿼리 문자열을 추가할 수 있습니다.
그리고 `Accept` 헤더를 `application/json` 또는 `application/yaml`로 설정하여 API 정의 출력을 각각 JSON 또는 YAML 형식으로 받을 수 있습니다.
API Gateway 내보내기 API를 사용하여 GET 요청을 제출하는 자세한 내용은 [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html)를 참조하세요.
**참고**
API에서 모델을 정의한 경우 API Gateway가 모델을 내보내려면 "application/json" 콘텐츠 유형이어야 합니다. 그렇지 않으면 API Gateway에서 "Only found non-JSON body models for ..." 오류 메시지와 함께 예외가 발생합니다.
모델은 속성을 포함하거나 특정 JSONSchema 형식으로 정의해야 합니다.
## REST API OpenAPI 정의를 JSON으로 다운로드
OpenAPI 정의의 REST API를 JSON 형식으로 내보내고 다운로드하려면
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/json
```
------
예를 들어, 여기서 ``은 `us-east-1`일 수 있습니다. API Gateway를 사용할 수 있는 전체 리전은 [리전 및 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region)를 참조하세요.
## REST API OpenAPI 정의를 YAML로 다운로드
OpenAPI 정의의 REST API를 YAML 형식으로 내보내고 다운로드하려면
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## Postman 확장이 포함된 REST API OpenAPI 정의를 JSON으로 다운로드
OpenAPI 정의의 REST API를 Postman을 사용해 JSON 형식으로 내보내고 다운로드하려면
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
## API Gateway 통합이 포함된 REST API OpenAPI 정의를 YAML로 다운로드
OpenAPI 정의의 REST API를 API Gateway 통합을 사용해 YAML 형식으로 내보내고 다운로드하려면
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## API Gateway 콘솔을 사용하여 REST API 내보내기
[REST API를 단계로 배포](set-up-deployments.md#create-deployment)한 후 API Gateway 콘솔을 사용하여 단계의 API를 OpenAPI 파일로 계속 내보낼 수 있습니다.
API Gateway 콘솔의 **스테이지** 창에서 **스테이지 작업**, **내보내기**를 선택합니다.
![\[API Gateway 콘솔을 사용하여 REST API 내보내기\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/export-new-console.png)
**API 사양 유형**, **형식** 및 **확장**을 지정하여 API의 OpenAPI 정의를 다운로드합니다.